docs: creating sphinx documentation

arthurbrenno · arthurbrenno · commit 6dbb9c872f60 · 2025-04-29T15:32:56.000-03:00
diff --git a/.github/workflows/sphinx.yaml b/.github/workflows/sphinx.yaml
@@ -0,0 +1,47 @@
+name: sphinx
+ 
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'src/**'
+      - 'docs/**'
+  workflow_dispatch:
+
+permissions:
+  pages: write
+  id-token: write
+  contents: write
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install PIP
+        run: pip install --root-user-action=ignore --upgrade pip
+
+      - name: Install project dependencies for docs using pip # Use uv and dev dependencies
+        run: pip install sphinx furo
+
+      - name: Build Docs # Use your makefile to build docs
+        run: make docs # This will execute 'make docs' in your root directory
+
+      - name: Prepare Deployment Directory
+        run: |
+          mkdir -p deploy_output/docs  # Create deploy_output and docs subdirectory in one go
+          cp docs/_static/landing.html deploy_output/index.html # Copy landing.html to staging root as index.html
+          cp -r docs/_build/html/* deploy_output/docs # Copy ALL Sphinx output to staging/docs
+
+      - name: Deploy to GitHub Pages # Using peaceiris/actions-gh-pages - a popular action
+        uses: peaceiris/actions-gh-pages@v3
+        if: github.ref == 'refs/heads/master'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./deploy_output # Publish the staging directory
diff --git a/docs/Makefile b/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     = source
+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)
diff --git a/docs/make.bat b/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=source
+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
diff --git a/docs/source/_static/logo-dark.svg b/docs/source/_static/logo-dark.svg
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg width="200" height="50" xmlns="http://www.w3.org/2000/svg">
+  <rect width="200" height="50" fill="#333333"/>
+  <text x="10" y="35" font-family="Arial" font-size="24" fill="white">Agentle</text>
+</svg> 
diff --git a/docs/source/_static/logo-light.svg b/docs/source/_static/logo-light.svg
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg width="200" height="50" xmlns="http://www.w3.org/2000/svg">
+  <rect width="200" height="50" fill="white"/>
+  <text x="10" y="35" font-family="Arial" font-size="24" fill="#333333">Agentle</text>
+</svg> 
diff --git a/docs/source/api/agents.rst b/docs/source/api/agents.rst
@@ -0,0 +1,7 @@
+Agents API
+=========
+
+.. automodule:: agentle.agents
+   :members:
+   :undoc-members:
+   :show-inheritance: 
diff --git a/docs/source/api/generations.rst b/docs/source/api/generations.rst
@@ -0,0 +1,7 @@
+Generations API
+==============
+
+.. automodule:: agentle.generations
+   :members:
+   :undoc-members:
+   :show-inheritance: 
diff --git a/docs/source/api/guardrails.rst b/docs/source/api/guardrails.rst
@@ -0,0 +1,7 @@
+Guardrails API
+=============
+
+.. automodule:: agentle.guardrails
+   :members:
+   :undoc-members:
+   :show-inheritance: 
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
@@ -0,0 +1,16 @@
+API Reference
+============
+
+This section contains detailed API documentation for Agentle.
+
+.. toctree::
+   :maxdepth: 2
+
+   agents
+   rag
+   stt
+   tts
+   guardrails
+   prompts
+   mcp
+   generations 
diff --git a/docs/source/api/mcp.rst b/docs/source/api/mcp.rst
@@ -0,0 +1,7 @@
+MCP API
+=======
+
+.. automodule:: agentle.mcp
+   :members:
+   :undoc-members:
+   :show-inheritance: 
diff --git a/docs/source/api/prompts.rst b/docs/source/api/prompts.rst
@@ -0,0 +1,7 @@
+Prompts API
+===========
+
+.. automodule:: agentle.prompts
+   :members:
+   :undoc-members:
+   :show-inheritance: 
diff --git a/docs/source/api/rag.rst b/docs/source/api/rag.rst
@@ -0,0 +1,7 @@
+RAG API
+=======
+
+.. automodule:: agentle.rag
+   :members:
+   :undoc-members:
+   :show-inheritance: 
diff --git a/docs/source/api/stt.rst b/docs/source/api/stt.rst
@@ -0,0 +1,7 @@
+Speech-to-Text API
+================
+
+.. automodule:: agentle.stt
+   :members:
+   :undoc-members:
+   :show-inheritance: 
diff --git a/docs/source/api/tts.rst b/docs/source/api/tts.rst
@@ -0,0 +1,7 @@
+Text-to-Speech API
+================
+
+.. automodule:: agentle.tts
+   :members:
+   :undoc-members:
+   :show-inheritance: 
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,61 @@
+# 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
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import os
+import sys
+
+# Add the project root directory to the path so Sphinx can find the package
+sys.path.insert(0, os.path.abspath("../.."))
+
+project = "Agentle"
+copyright = "2025, Arthur Brenno"
+author = "Arthur Brenno"
+release = "0.0.13"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.autosummary",
+]
+
+templates_path = ["_templates"]
+pygments_style = "default"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- autodoc configuration --------------------------------------------------
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+}
+autodoc_typehints = "description"
+autoclass_content = "both"
+autosummary_generate = True
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_theme_options = {
+    "light_logo": "logo-light.svg",
+    "dark_logo": "logo-dark.svg",
+    "sidebar_hide_name": False,
+}
+html_static_path = ["_static"]
+html_title = f"{project} {release} Documentation"
+
+# Intersphinx mapping
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "pandas": ("https://pandas.pydata.org/docs/", None),
+}
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -0,0 +1,59 @@
+Contributing
+============
+
+We welcome contributions to Agentle! This document outlines the process for contributing to the project.
+
+Development Setup
+---------------
+
+1. Fork the repository on GitHub
+2. Clone your fork locally
+3. Install development dependencies:
+
+   .. code-block:: bash
+
+      pip install -e ".[dev]"
+
+4. Create a branch for your feature:
+
+   .. code-block:: bash
+
+      git checkout -b feature-name
+
+Code Standards
+------------
+
+- We use mypy for type checking
+- Ruff for linting
+- All code should be properly typed
+
+Testing
+------
+
+Before submitting a pull request, make sure all tests pass:
+
+.. code-block:: bash
+
+   # Run tests command here
+
+Documentation
+------------
+
+Please update the documentation when adding or modifying features.
+
+To build the documentation locally:
+
+.. code-block:: bash
+
+   cd docs
+   make html
+
+The built documentation will be available in the `docs/build/html` directory.
+
+Submitting Changes
+----------------
+
+1. Push your changes to your fork
+2. Submit a pull request to the main repository
+3. Ensure CI checks pass
+4. Update your PR based on reviewer feedback 
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
@@ -0,0 +1,43 @@
+Examples
+========
+
+This page contains detailed examples of how to use Agentle in various scenarios.
+
+Example 1: Creating Agents
+------------------------
+
+.. code-block:: python
+
+   from agentle.agents import Agent
+   
+   # Example code for creating and configuring agents
+
+Example 2: Working with RAG
+-------------------------
+
+.. code-block:: python
+
+   from agentle.rag import RAGSystem
+   
+   # Example code for setting up and using RAG
+
+Example 3: Using Guardrails
+-------------------------
+
+.. code-block:: python
+
+   from agentle.guardrails import GuardrailConfig
+   
+   # Example code for implementing guardrails
+
+Example 4: Speech Integration
+--------------------------
+
+.. code-block:: python
+
+   from agentle.stt import SpeechToText
+   from agentle.tts import TextToSpeech
+   
+   # Example code for speech integration
+
+For more examples, check the examples.ipynb notebook in the repository. 
diff --git a/docs/source/index.rst b/docs/source/index.rst
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
diff --git a/makefile b/makefile
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/uv.lock b/uv.lock
