Add Sphinx documentation and related configuration

Introduce Sphinx for documentation generation, including configuration files, themes, and build scripts. Integrated doc generation into the project workflow and configured Read the Docs for automated deployment. Updated dependencies to include required Sphinx packages.

Signed-off-by: DanielAvdar <66269169+DanielAvdar@users.noreply.github.com>

Author: DanielAvdar

.github/dependabot.yml

@@ -9,6 +9,10 @@ updates:
     directory: "/" # Location of package manifests
     schedule:
       interval: daily
+  - package-ecosystem: "uv" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: daily
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:

.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+name: Publish docs GH Pages
+on:
+  pull_request: # todo: remove this after testing
+  release:
+    types: [ published ]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+
+  create-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv python install 3.11
+
+      - run: make
+      - run: make doc
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/build
+          keep_files: true

.pre-commit-config.yaml

@@ -7,14 +7,9 @@ repos:
       - id: trailing-whitespace
       - id: no-commit-to-branch
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.4
+    rev: v0.11.4
     hooks:
       - id: ruff-format
         args: [ --preview, --config=pyproject.toml ]
       - id: ruff
         args: [ --preview, --fix,--unsafe-fixes, --config=pyproject.toml ]
-
-  - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.5.13
-    hooks:
-      - id: uv-lock

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the "docs/" directory with Sphinx
+
+sphinx:
+   configuration: docs/source/conf.py
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: all
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_install:
+      - pip install uv
+      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --all-extras --group docs --link-mode=copy

Makefile

@@ -22,4 +22,7 @@ coverage:
 	uv run pytest --cov=ml_orchestrator --cov-report=xml
 
 mypy:
-	uv tool run mypy . --config-file pyproject.toml
+	uv tool run mypy my_pkg --config-file pyproject.toml # todo: chanege my_pkg to the actual package name
+
+doc:
+	uv run sphinx-build -M html docs/source docs/build/

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)

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

docs/source/conf.py

@@ -0,0 +1,45 @@
+# 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
+from importlib.metadata import version
+
+sys.path.insert(0, os.path.abspath("../../"))
+# sys.path.insert(0, os.path.abspath("./"))  # in conf.py
+
+
+project = "python-template"  # todo: change this to your project name
+version = version("my-pkg")  # todo: change my-pkg to your package name
+release = version
+
+copyright = "2025, DanielAvdar"  # noqa  todo: change this to your name
+author = "DanielAvdar"  # todo: change this to your name
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",  # Core extension for pulling docstrings
+    "sphinx.ext.napoleon",  # Support for Google and NumPy style docstrings
+    "sphinx.ext.viewcode",  # Add links to source code
+    "sphinx.ext.githubpages",  # If deploying to GitHub Pages
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+master_doc = "index"
+html_static_path = ["_static"]

docs/source/index.rst

@@ -0,0 +1,16 @@
+.. python-template documentation master file, created by
+   sphinx-quickstart on Wed Apr  9 13:29:29 2025.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+python-template documentation
+=============================
+
+Add your content using ``reStructuredText`` syntax. See the
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+documentation for details.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:

my_pkg/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("my-pkg")