docs: conf.py is now included, sphinx is properly installed using uv

ref: N25B-270

.gitignore

@@ -218,7 +218,9 @@ __marimo__/
 # MacOS
 .DS_Store
 
-
+# Docs
+docs/*
+!docs/conf.py
 
 
 

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
 ```

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

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]

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" },
 ]