From 8c209d3adb9a61d83b760eee73e2af16ab8d53dc Mon Sep 17 00:00:00 2001
From: Storm <stormluykx@gmail.com>
Date: Wed, 19 Nov 2025 17:47:10 +0100
Subject: [PATCH] docs: conf.py is now included, sphinx is properly installed
 using uv

ref: N25B-270
---
 .gitignore     |  4 +++-
 README.md      | 19 ++++++++++++-------
 docs/conf.py   | 36 ++++++++++++++++++++++++++++++++++++
 pyproject.toml |  4 ++--
 uv.lock        |  4 ++--
 5 files changed, 55 insertions(+), 12 deletions(-)
 create mode 100644 docs/conf.py

diff --git a/.gitignore b/.gitignore
index b6322a4..f58719a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -218,7 +218,9 @@ __marimo__/
 # MacOS
 .DS_Store
 
-
+# Docs
+docs/*
+!docs/conf.py
 
 
 
diff --git a/README.md b/README.md
index 4d3b2dd..1527215 100644
--- a/README.md
+++ b/README.md
@@ -67,21 +67,26 @@ Then run the pre-commit install commands again.
 ## Documentation
 Generate documentation web pages using:
 
+### Linux & macOS
 ```bash
 PYTHONPATH=src sphinx-apidoc -F -o docs src/control_backend
 ```
 
-Optionally, in the `conf.py` file in the new `docs` folder, change preferences. 
-For the page theme, change `html_theme` to `'sphinx_rtd_theme'`.
+### Windows
+```bash
+$env:PYTHONPATH="src"; sphinx-apidoc -F -o docs src/control_backend
+```
+
+Optionally, in the `conf.py` file in the `docs` folder, change preferences. 
 
 In the `docs` folder:
 
+### Linux & macOS
+```bash
+make html
+```
+
 ### Windows
 ```bash
 .\make.bat html
-```
-
-### MacOS
-```bash
-make html
 ```
\ No newline at end of file
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..4522141
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,36 @@
+# 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
+
+project = 'control_backend'
+copyright = '2025, Author'
+author = 'Author'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.todo',
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+language = 'en'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+# -- Options for todo extension ----------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration
+
+todo_include_todos = True
diff --git a/pyproject.toml b/pyproject.toml
index fe835dc..40a8d88 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -23,10 +23,10 @@ dependencies = [
     "silero-vad>=6.0.0",
     "spade>=4.1.0",
     "spade-bdi>=0.3.2",
+    "sphinx>=7.3.7",
+    "sphinx-rtd-theme>=3.0.2",
     "torch>=2.8.0",
     "uvicorn>=0.37.0",
-    "sphinx",
-    "sphinx_rtd_theme",
 ]
 
 [dependency-groups]
diff --git a/uv.lock b/uv.lock
index b277dd7..61c1205 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1443,8 +1443,8 @@ requires-dist = [
     { name = "silero-vad", specifier = ">=6.0.0" },
     { name = "spade", specifier = ">=4.1.0" },
     { name = "spade-bdi", specifier = ">=0.3.2" },
-    { name = "sphinx" },
-    { name = "sphinx-rtd-theme" },
+    { name = "sphinx", specifier = ">=7.3.7" },
+    { name = "sphinx-rtd-theme", specifier = ">=3.0.2" },
     { name = "torch", specifier = ">=2.8.0" },
     { name = "uvicorn", specifier = ">=0.37.0" },
 ]