chore(dev): add option for serving docs locally

amimas · nejch · commit beb2f2457c0a · 2025-02-10T13:18:24.000+01:00
This update can be helpful when changing documentation by serving the docs locally to ensure content presentation and format is as-expected.
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -81,6 +81,9 @@ You need to install ``tox`` (``pip3 install tox``) to run tests and lint checks
    # build the documentation - the result will be generated in build/sphinx/html/:
    tox -e docs
 
+   # build and serve the documentation site locally for validating changes
+   tox -e docs-serve
+
    # List all available tox environments
    tox list
 
diff --git a/requirements-docs.txt b/requirements-docs.txt
@@ -4,3 +4,4 @@ jinja2==3.1.5
 myst-parser==4.0.0
 sphinx==8.1.3
 sphinxcontrib-autoprogram==0.1.9
+sphinx-autobuild==2024.10.3
diff --git a/tox.ini b/tox.ini
@@ -26,7 +26,10 @@ passenv =
   NO_COLOR
   PWD
   PY_COLORS
-setenv = VIRTUAL_ENV={envdir}
+setenv = 
+  DOCS_SOURCE = docs
+  DOCS_BUILD = build/sphinx/html
+  VIRTUAL_ENV={envdir}
 whitelist_externals = true
 usedevelop = True
 install_command = pip install {opts} {packages} -e .
@@ -99,8 +102,17 @@ per-file-ignores =
     gitlab/v4/objects/__init__.py:F401,F403
 
 [testenv:docs]
+description = Builds the docs site. Generated HTML files will be available in '{env:DOCS_BUILD}'. 
 deps = -r{toxinidir}/requirements-docs.txt
-commands = sphinx-build -n -W --keep-going -b html docs build/sphinx/html
+commands = sphinx-build -n -W --keep-going -b html {env:DOCS_SOURCE} {env:DOCS_BUILD}
+
+[testenv:docs-serve]
+description = 
+    Builds and serves the HTML docs site locally. \
+    Use this for verifying updates to docs. \
+    Changes to docs files will be automatically rebuilt and served.
+deps = -r{toxinidir}/requirements-docs.txt
+commands = sphinx-autobuild {env:DOCS_SOURCE} {env:DOCS_BUILD} --open-browser --port 8000
 
 [testenv:cover]
 commands =
