ci: fix docs infra and tests

.github/workflows/policy_docs.yml

@@ -118,6 +118,8 @@ jobs:
         if: ${{ matrix.platform == 'macos-latest' && matrix.python-version != '3.6' }}
         run: brew install enchant
 
+      - run: tox -e pin-docs -vv -s false
+
       - name: Run Documentation Tests
         if: ${{ matrix.platform == 'ubuntu-latest' || matrix.python-version  != '3.6' }}
         run: tox -e docs --sitepackages -vv -s false

pyproject.toml

@@ -118,17 +118,11 @@ pytest-xdist = { version = ">= 1.34", optional = true }
 
 
 # Docs: development and build dependencies
-mkdocs = { version = "^1.5.3", optional = true }
-mkdocs-macros-plugin = { version = "^1.0.5", optional = true }
-mkdocs-material = { version = "^9.4.14", optional = true }
-mkdocs-mermaid2-plugin = { version = "^1.1.1", optional = true }
-mkdocs-section-index = { version = "^0.3.8", optional = true }
-mkdocs-gen-files = { version = "^0.5.0", optional = true }
-mkdocstrings = { version = "^0.24.0", optional = true }
-mkdocstrings-python = { version = "^1.7.5", optional = true }
-mkdocs-literate-nav = { version = "^0.6.1", optional = true }
-mkdocs-click = { version = "^0.8.1", optional = true }
-pymdown-extensions = { version = "^10.5", optional = true }
+sphinx = { version = "~= 4.0", optional = true }
+sphinx-autodoc-typehints = { version = ">= 1.10", optional = true }
+sphinx-rtd-theme = { version = "== 0.5.0", optional = true }
+sphinxcontrib-spelling = { version = "~= 7.3.3", optional = true }
+sphinx-autobuild = { version = "^2021.3.14", optional = true }
 
 
 # Type Checking: packages required for the type check (ie mypy) to pass
@@ -148,6 +142,13 @@ docs = [
     "sphinx-rtd-theme",
     "sphinxcontrib-spelling",
 ]
+docslive = [
+    "sphinx",
+    "sphinx-autodoc-typehints",
+    "sphinx-rtd-theme",
+    "sphinxcontrib-spelling",
+    "sphinx-autobuild",
+]
 typing = [
     "mypy",
     "types-requests",

tox.ini

@@ -166,43 +166,48 @@ changedir = {toxinidir}
 commands = mypy --show-error-codes {posargs:src{/}{env:PY_PACKAGE} tests}
 
 
-### DOCS ###
-# poetry export -o req-docs.txt -E docs && tox -e docs
-# poetry export -o req-docs.txt -E docs && tox -e live-html
 ## BUILD DOCUMENTATION PAGES ##
+# tox -e pin-docs,docs
+# tox -e pin-docs -- docslive && tox -e docs-live
 [testenv:pin-docs]
-description = 'Pin Docs Python Dependencies in requirements.txt type of format.'
+description = 'Pin Dependencies for Sphinx and its Plugins in "requirements.txt" format.'
 basepython = {env:TOXPYTHON:python3}
 deps = poetry
 skip_install = true
-commands = poetry export -o req-docs.txt -E docs && tox -e docs
+commands = poetry export -o req-docs.txt -E {posargs:docs}
 
 [testenv:docs]
-description = 'Build the documentation, leveraging Mkocs as a Static Site Generator (SSG).'
+description = Build the documentation. Read the source .rst and .py files and
+    build ready-to-render/ready-to-serve html (eg you can host it in a
+    'read the docs server'). Before building, any sphinx doctest found is
+    executed. After building, both word spelling and url links proper redirects
+    are checked.
 basepython = {env:TOXPYTHON:python3}
 setenv =
     {[testenv]setenv}
+    PYTHONPATH = {toxinidir}{/}src
     SPELLCHECK=1
 deps = -r req-docs.txt
 skip_install = true
+changedir = {toxinidir}
 commands =
-    mkdocs {posargs}
+    sphinx-build {posargs:-E} -b doctest docs {env:DOCS_BUILD_LOCATION:dist{/}docs}
+    sphinx-build {posargs:-E} -b html docs {env:DOCS_BUILD_LOCATION:dist{/}docs}
+    sphinx-build -b spelling docs {env:DOCS_BUILD_LOCATION:dist{/}docs}
+    - sphinx-build -b linkcheck docs {env:DOCS_BUILD_LOCATION:dist{/}docs}
+    python -c 'print("View documentation at {env:DOCS_BUILD_LOCATION:dist/docs}/index.html; it is ready to be hosted!")'
 
 ## SERVE LIVE DOCUMENTATION ##
-# poetry export -o req-docs.txt -E docs && tox -e live-html
-[testenv:live-html]
-description = Start documentation dev-server (with hot-reloading) for browser preview
+[testenv:docs-live]
+description = Rebuild Sphinx documentation on changes, with live-reload in the browser.
 basepython = {env:TOXPYTHON:python3}
 setenv =
     {[testenv]setenv}
+    PYTHONPATH = {toxinidir}{/}src
     SPELLCHECK=1
 deps = -r req-docs.txt
-usedevelop = true
 changedir = {toxinidir}
-commands_pre =
-    python ./scripts/visualize-dockerfile.py -o docs/dockerfile_mermaid.md
-    python ./scripts/visualize-ga-workflow.py .github/workflows/test.yaml -o docs/cicd_mermaid.md
-commands = mkdocs serve
+commands = sphinx-autobuild docs docs{/}_build{/}html {posargs:--port 8005}