Docs: Initial Sphinx setup and configuration (conf.py, index, structure)

.gitignore

@@ -1,3 +1,4 @@
+docs/_build/
 examples/output/
 
 # Environment variables

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/cli_reference.rst

@@ -0,0 +1,32 @@
+##############
+CLI Reference
+##############
+
+This page details the commands available in Codex CLI Studio.
+
+.. automodule:: codex_cli.main
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :exclude-members: run, console, app, config_app
+
+Command Modules
+===============
+
+.. automodule:: codex_cli.explain
+   :members:
+
+.. automodule:: codex_cli.script
+   :members:
+
+.. automodule:: codex_cli.visualize
+   :members:
+
+.. automodule:: codex_cli.config
+   :members:
+
+Core Utilities
+==============
+
+.. automodule:: codex_cli.core.openai_utils
+   :members:

docs/conf.py

@@ -0,0 +1,122 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+# Point Sphinx to the project root directory to find the source code
+sys.path.insert(0, os.path.abspath('..'))
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Codex CLI Studio'
+copyright = '2024, Michael Shapkin' # Update year if needed
+author = 'Michael Shapkin'
+release = '0.1.2' # The full version, including alpha/beta/rc tags
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+# Add extensions here
+extensions = [
+    'sphinx.ext.autodoc',  # Include documentation from docstrings
+    'sphinx.ext.napoleon', # Support Google and NumPy style docstrings
+    'sphinx.ext.intersphinx', # Link to other projects' documentation
+    'sphinx.ext.viewcode',  # Add links to source code
+    'myst_parser',          # Parse Markdown files (.md)
+    'sphinx_click',         
+]
+
+# Add patterns to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The master toctree document.
+# Sphinx 5+ uses root_doc, older versions use master_doc
+# Keep master_doc for compatibility if needed, otherwise root_doc is preferred
+root_doc = 'index' # Default is 'index'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'furo' # Use the Furo theme
+
+# Add paths for custom static files (css, images, etc.), relative to this directory.
+# They are copied after the builtin static files, so file named "default.css"
+# will overwrite the builtin "default.css".
+# html_static_path = ['_static'] # Uncomment if you have custom static files
+
+# -- Options for autodoc extension -------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
+
+# Automatically document members (methods, attributes)
+autodoc_member_order = 'bysource' # Order members by source code line number
+# Default flags for automodule/autoclass, etc.
+# autodoc_default_options = {
+#     'members': True,
+#     'undoc-members': True,
+#     'private-members': False,
+#     'show-inheritance': True,
+# }
+
+# -- Options for napoleon extension ------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#configuration
+
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = False
+napoleon_type_aliases = None
+napoleon_attr_annotations = True
+
+# -- Options for intersphinx extension ---------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
+
+# Example configuration for linking to the Python documentation
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    #'typer': ('https://typer.tiangolo.com/en/latest/', None),
+    'rich': ('https://rich.readthedocs.io/en/stable/', None),
+    #'openai': ('https://platform.openai.com/docs/api-reference', None), # Check if OpenAI has objects.inv
+}
+intersphinx_timeout = 5 # seconds to wait for remote inventory
+intersphinx_cache_limit = 5 # days to cache remote inventories
+
+# -- Options for MyST parser extension ----------------------------------------
+# https://myst-parser.readthedocs.io/en/latest/configuration.html
+
+# Allow parsing of .md files
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.txt': 'markdown',
+    '.md': 'markdown',
+}
+
+# Optional: Enable specific MyST extensions if needed
+# myst_enable_extensions = [
+#     "colon_fence", # Allow ```{directive} syntax
+#     # "amsmath",
+#     # "deflist",
+#     # "dollarmath",
+#     # "html_admonition",
+#     # "html_image",
+#     # "linkify",
+#     # "replacements",
+#     # "smartquotes",
+#     # "substitution",
+#     # "tasklist",
+# ]
+# myst_url_schemes = ["http", "https", "mailto"] # Default

docs/contributing.md

@@ -0,0 +1,37 @@
+# Contributing to Codex CLI Studio
+
+First off, thank you for considering contributing! We're excited to build this AI-augmented open-source ecosystem together. Whether it's a bug report, a new feature idea, documentation, or code, your help is valuable.
+
+## How Can I Contribute?
+
+*   **Reporting Bugs:** If you find a bug, please open an issue using the "Bug report" template. Provide as much detail as possible.
+*   **Suggesting Enhancements:** Have an idea for a new feature or an improvement? Open an issue using the "Feature request" template or start a discussion in the "Ideas" category.
+*   **Discussions:** Join the conversation in our [GitHub Discussions](https://github.com/michaelshapkin/codex-cli-studio/discussions)! Ask questions, share how you use the tool, or brainstorm new possibilities.
+*   **Improving Documentation:** Found a typo or think something could be clearer? Feel free to open an issue or a Pull Request.
+*   **Writing Code:** If you'd like to contribute code (fix a bug, implement a feature):
+    1.  Look for existing issues, especially those tagged `good first issue` or `help wanted`.
+    2.  Discuss your plan in the issue or start a new discussion before significant work.
+    3.  Follow the development workflow below.
+
+## Development Workflow
+
+1.  **Fork & Clone:** Fork the repository and clone your fork locally.
+2.  **Setup:** Follow the installation steps in the [README](installation.md), making sure to install development dependencies (`pip install -e .[dev]` or `pip install pytest pytest-mock`).
+3.  **Create Branch:** Create a new branch for your changes (`git checkout -b feature/YourFeature` or `fix/BugDescription`).
+4.  **Code:** Make your changes. Follow existing code style.
+5.  **Test:** Add tests for your changes and ensure *all* tests pass (`python -m pytest -v`).
+6.  **Commit:** Write clear, concise commit messages.
+7.  **Push:** Push your branch to your fork (`git push origin feature/YourFeature`).
+8.  **Open Pull Request:** Create a PR from your fork's branch to the `main` branch of the original repository. Fill in the PR template, explaining your changes.
+
+## Code Review & AI Assistance
+
+*   **CI Checks:** All Pull Requests will automatically run tests via GitHub Actions. Please ensure these pass.
+*   **AI Explain (Experimental):** We may use `cstudio explain` or other AI tools to help understand the proposed code changes and facilitate review.
+*   **Maintainer Review:** The project maintainer ([@michaelshapkin](https://github.com/michaelshapkin)) will review the PR conceptually and based on test/AI feedback. We value collaboration and will provide constructive feedback.
+
+## Joining the Team
+
+We're building an open community! Active and helpful contributors may be invited to become core members or maintainers as the project grows. The best way to get involved is to start contributing via issues, discussions, and pull requests.
+
+Let's build the future of AI-assisted development together! 🚀

docs/index.rst

@@ -0,0 +1,32 @@
+.. automodule:: codex_cli
+   :noindex:
+
+##################
+Codex CLI Studio
+##################
+
+Welcome to the documentation for Codex CLI Studio!
+
+.. image:: ../codex-cli-studio-demo.svg
+   :alt: Codex CLI Studio Demo
+   :align: center
+
+A powerful suite of command-line tools powered by OpenAI models (like GPT-4o),
+built to supercharge productivity, learning, and automation for developers,
+DevOps, and students alike.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   usage
+   cli_reference
+   contributing
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/installation.md

@@ -0,0 +1,21 @@
+# 🔌 Installation
+
+**Prerequisites:**
+*   Python 3.9+
+*   `pip`
+*   [Graphviz](https://graphviz.org/download/) (specifically the `dot` command) - *Required only for rendering visualizations to image formats (png, svg, etc.) using the `visualize` command.*
+*   An OpenAI API Key.
+
+**Install using pip:**
+
+```bash
+pip install codex-cli-studio
+```
+
+**Set up your OpenAI API Key:**
+The tool reads the API key from the OPENAI_API_KEY environment variable. 
+
+You can set it:
+* System-wide: Add export OPENAI_API_KEY='your_key_here' to your shell profile (.zshrc, .bashrc, etc.).
+* Per session: Run export OPENAI_API_KEY='your_key_here' in your terminal before using cstudio.
+* Using a .env file: Create a .env file in the directory where you run the cstudio command and add the line OPENAI_API_KEY='your_key_here'.

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/usage.md

@@ -0,0 +1,26 @@
+# ✨ Usage
+After installation, use the `cstudio` command:
+
+```bash
+# General help
+cstudio --help
+
+# Explain a code snippet
+cstudio explain 'import sys; print(sys.argv[1])' --lang en
+
+# Explain a file in detail
+cstudio explain path/to/your/code.py --detail detailed
+
+# Generate a Python script
+cstudio script "read lines from data.txt and print them numbered" -t python
+
+# Generate a bash script (dry run only)
+cstudio script "delete all *.tmp files in /tmp" --dry-run
+
+# Visualize a Python file, saving as PNG
+cstudio visualize path/to/visualize.py -f png -o visualize_graph.png
+
+# Explain a YAML config file
+cstudio config explain path/to/config.yaml
+```
+

pyproject.toml

@@ -42,18 +42,20 @@ dependencies = [
     "graphviz>=0.20.1,<1.0.0", # For visualize module
 ]
 
-# --- ADDED/UPDATED SECTION ---
 # Optional dependencies, installable via pip install .[dev]
 [project.optional-dependencies]
 dev = [
     "pytest>=8.2,<9.0",       # For running tests
     "pytest-mock>=3.12,<4.0", # For mocking API calls in tests
+    "Sphinx>=7.0,<8.0",
+    "furo>=2024.1.29",
+    "myst-parser>=2.0,<3.0",
+    "sphinx-click",
     # Future dev tools can be added here:
     # "black",                # Code formatter
     # "ruff",                 # Linter
     # "mkdocs",               # Documentation generator
 ]
-# --- END ADDED/UPDATED SECTION ---
 
 # Define the command-line script entry point
 [project.scripts]