docs: consolidate sphinx and mkdocs into single-version zensical

Replace the dual sphinx (readthedocs) + mkdocs (gh-pages) stack with
zensical: new zensical.toml (material theme, mkdocstrings on src),
rewritten landing page, real docs/docs-test Makefile targets, a
check-docs CI job, and a Pages-artifact deploy workflow. Remove
conf.py, mkdocs.yml, .readthedocs.yml, docs/requirements.txt and the
sphinx-only include shim pages

Author: raederan

.github/workflows/docs.yml

@@ -1,31 +1,48 @@
-# This is a basic workflow to help you get started with Actions
+# Deploys the documentation to GitHub Pages via the Pages artifact method
+# (repo setting: Pages source = "GitHub Actions").
+# NOTE: the docs-versioning phase of the migration replaces this with a
+# mike-based deploy to the gh-pages branch.
 
 name: Docs
 
-# Controls when the workflow will run
 on:
-  # Triggers the workflow on push or pull request events but only for the master branch
   push:
-    branches: [ main ]
-
-  # Allows you to run this workflow manually from the Actions tab
+    branches: [main]
   workflow_dispatch:
 
-# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
 jobs:
-  # This workflow contains a single job called "build"
-  build:
-    # The type of runner that the job will run on
+  deploy-docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
-
-    # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v2
+      - name: Check out
+        uses: actions/checkout@v4
         with:
+          # deep clone incl. tags so hatch-vcs can derive the version
           fetch-depth: 0
-      - uses: actions/setup-python@v2
-      - run: pip install --upgrade pip && pip install mkdocs mkdocs-gen-files "mkdocstrings[python]" mkdocs-material
-      - run: git config user.name 'github-actions[bot]' && git config user.email 'github-actions[bot]@users.noreply.github.com'
-      - name: Publish docs
-        run: mkdocs gh-deploy
+
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+
+      - name: Build documentation
+        run: uv run zensical build --clean
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/main.yml

@@ -79,3 +79,18 @@ jobs:
         if: ${{ matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11' }}
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  check-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out
+        uses: actions/checkout@v4
+        with:
+          # deep clone incl. tags so hatch-vcs can derive the version
+          fetch-depth: 0
+
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+
+      - name: Check if documentation can be built
+        run: uv run zensical build -s

.pre-commit-config.yaml

@@ -1,6 +1,3 @@
-# Legacy sphinx config; excluded until it is removed in the docs phase
-exclude: '^docs/conf.py'
-
 minimum_pre_commit_version: 3.2.0
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks

.readthedocs.yml

@@ -38,12 +38,12 @@ publish: ## Publish a release to PyPI (CI-only via OIDC trusted publishing)
 	@echo "Push a version tag (v*) to trigger a release."
 
 .PHONY: docs
-docs: ## Build and serve the documentation (available after the docs phase)
-	@echo "Docs are built with zensical from the docs phase onward."
+docs: ## Build and serve the documentation locally
+	@uv run zensical serve
 
 .PHONY: docs-test
-docs-test: ## Test if documentation can be built without errors (available after the docs phase)
-	@echo "Docs are built with zensical from the docs phase onward."
+docs-test: ## Test if documentation can be built without warnings or errors
+	@uv run zensical build -s
 
 .PHONY: help
 help: