Merge pull request #139 from libranet/docs/migrate-to-mkdocs-material

docs: migrate from Sphinx to MkDocs + Material for MkDocs

Author: woutervh

.github/workflows/docs.yaml

@@ -0,0 +1,73 @@
+# Docs - Github Actions
+#
+# Builds the MkDocs site with --strict, so broken links, missing nav entries and
+# unresolved mkdocstrings cross-references fail the pull request instead of only
+# surfacing in the Read the Docs build after merge.
+#
+# Used actions:
+#   - actions/checkout
+#     repo: https://github.com/actions/checkout
+#     releases: https://github.com/actions/checkout/tags
+#
+#   - astral-sh/setup-uv: set up uv environment
+#     repo: https://github.com/astral-sh/setup-uv
+#     releases: https://github.com/astral-sh/setup-uv/tags
+#     docs: https://docs.astral.sh/uv/guides/integration/github/
+
+
+name: Docs 📗
+
+concurrency:
+    # see https://docs.github.com/en/actions/using-jobs/using-concurrency
+    group: ${{ github.workflow }}-${{ github.ref }}
+
+env:
+    # Silence Material for MkDocs' MkDocs-2.0 stderr banner (it is not a build warning)
+    DISABLE_MKDOCS_2_WARNING: "true"
+
+    # Pin uv version for reproducible builds
+    # https://github.com/astral-sh/uv/releases
+    UV_VERSION: "0.12.6"
+
+on:
+    pull_request:
+        types: [opened, reopened, synchronize]
+    push:
+        branches:
+            - main
+
+permissions:
+    contents: read
+
+jobs:
+    build:
+        name: mkdocs build --strict
+        runs-on: ubuntu-latest
+        timeout-minutes: 5
+        steps:
+
+        # repo: https://github.com/actions/checkout
+        # releases: https://github.com/actions/checkout/tags
+        - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+          with:
+              persist-credentials: false
+
+        # repo: https://github.com/astral-sh/setup-uv
+        # releases: https://github.com/astral-sh/setup-uv/tags
+        # docs: https://docs.astral.sh/uv/guides/integration/github
+        - name: Install pinned version of uv
+          uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d  # v10.0.1
+          with:
+              cache-dependency-glob: "uv.lock"
+              enable-cache: true
+              prune-cache: true
+              python-version: "3.14"  # match tools.python in .readthedocs.yaml
+              version: ${{ env.UV_VERSION }}
+
+        # Mirrors the Read the Docs build: only the "docs" group, project included so
+        # mkdocstrings can import autoread_dotenv from src/.
+        - name: Install docs dependencies
+          run: uv sync --only-group docs
+
+        - name: Build the docs
+          run: uv run mkdocs build --strict

.just/mkdocs.justfile

@@ -0,0 +1,28 @@
+# MkDocs + Material -- see ../mkdocs.yaml
+
+
+# show which mkdocs is used
+[group: 'mkdocs']
+mkdocs-which:
+    @ uv run mkdocs --version
+
+
+# build the static site into var/html-docs (strict: fail on broken refs/links)
+[group: 'mkdocs']
+mkdocs-docs *args:
+    uv run mkdocs build --strict {{ args }}
+    @echo
+    @echo "Build finished -> var/html-docs (see site_dir in ../mkdocs.yaml)"
+
+
+# Extra args pass through, e.g.
+#   just mkdocs-serve -a 0.0.0.0:8000   # bind all interfaces (then browse localhost, NOT 0.0.0.0)
+#   just mkdocs-serve --no-strict
+# live-reloading preview on http://127.0.0.1:8000/ (or http://localhost:8000/ from a WSL2 browser)
+[group: 'mkdocs']
+mkdocs-serve *args:
+    uv run mkdocs serve {{ args }}
+
+
+# alias for mkdocs-docs
+alias docs := mkdocs-docs

.just/sphinx.justfile

@@ -4,6 +4,10 @@
 #  - https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 #  - https://docs.readthedocs.com/platform/stable/build-customization.html
 #  - https://github.com/astral-sh/uv/issues/10074
+#
+# Enable RTD "Build pull requests":
+# go to https://app.readthedocs.org/ → autoread-dotenv project → Admin
+#   → Settings → Check "Build pull requests for this project" → Save
 
 version: 2
 
@@ -22,10 +26,8 @@ build:
 
 formats:
     - htmlzip
-    - pdf
-    # - epub
-    # - all
+    # pdf/epub are Sphinx-only on Read the Docs and not available for MkDocs builds.
 
-sphinx:
-    configuration: docs/conf.py
-    fail_on_warning: false # true is too strict
+mkdocs:
+    configuration: mkdocs.yaml
+    fail_on_warning: false  # Material for MkDocs prints an (unsuppressable) MkDocs-2.0 banner

.readthedocs.yaml

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 
 ## 1.0.7 (unreleased)
 
+- Migrate the documentation from Sphinx to MkDocs + Material for MkDocs. The API
+  reference is now generated by `mkdocstrings` (Python handler) instead of
+  `sphinx-autoapi`; `docs/conf.py`, `docs/index.rst` and the committed
+  `docs/modules/` tree are gone, replaced by `mkdocs.yaml`, `docs/index.md` and
+  `docs/reference/*.md`. Read the Docs keeps hosting the site (`htmlzip` output
+  retained; `pdf` dropped -- Sphinx-only on RTD). Module/function docstrings that
+  used reStructuredText markup (`.. code-block::`, `:func:` / `:class:` roles)
+  were rewritten in Markdown so they render correctly. Adds a `docs/configuration.md`
+  page documenting the `AUTOREAD_DOTENV_PATH` and `AUTOREAD_ENFORCE_DOTENV`
+  environment-variables, which must be set outside `.env`.
+
 - Narrow the blanket `except OSError` in `get_dotenv_path()`. `PermissionError` from
   `is_file()` itself (the documented Python < 3.12 case of an unreadable parent directory)
   still returns the path optimistically and defers to `load_dotenv()`. Any other `OSError`