chore: migrate documentation from Sphinx to MkDocs

.github/workflows/mkdocs.yml

@@ -0,0 +1,115 @@
+---
+name: Docs
+
+"on":
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "pybdl/**"
+      - ".github/workflows/mkdocs.yml"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "CHANGELOG.md"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "pybdl/**"
+      - ".github/workflows/mkdocs.yml"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions: {}
+
+jobs:
+  build:
+    name: Build MkDocs site
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@94527f2e458b27549849d47d273a16bec83a01e9  # v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install project and docs dependencies
+        run: uv sync --group docs
+
+      - name: Build site (strict)
+        run: uv run mkdocs build --strict
+
+      - name: Upload site artifact
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4  # v5
+        with:
+          name: mkdocs-site
+          path: site
+          retention-days: 7
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    name: Deploy versioned docs (mike → gh-pages)
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # Push versioned HTML and mike metadata to the gh-pages branch.
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Authenticate git for push
+        run: git remote set-url origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@94527f2e458b27549849d47d273a16bec83a01e9  # v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install project and docs dependencies
+        run: uv sync --group docs
+
+      - name: Configure Git for mike
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Read version from pyproject.toml
+        id: version
+        run: |
+          v="$(uv run python -c \
+            'import tomllib as t;print(t.load(open("pyproject.toml","rb"))["project"]["version"])')"
+          echo "version=${v}" >> "${GITHUB_OUTPUT}"
+
+      - name: Deploy to gh-pages with mike
+        env:
+          MIKE_VERSION: ${{ steps.version.outputs.version }}
+        run: >
+          uv run mike deploy
+          --push
+          --update-aliases
+          "${MIKE_VERSION}"
+          latest
+
+      - name: Point site root at latest (redirect)
+        run: uv run mike set-default latest --push

.gitignore

@@ -97,7 +97,7 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
+# Legacy Sphinx output (MkDocs uses /site at repo root)
 docs/_build/
 
 # PyBuilder

Makefile

@@ -14,4 +14,4 @@ test:
 	uv run pytest --cov --cov-report term-missing:skip-covered
 
 docs:
-	uv run sphinx-build -W --keep-going -b html docs docs/_build/html
+	uv run --group docs mkdocs build --strict

README.md

@@ -103,21 +103,26 @@ payload_with_meta = bdl.api.data.get_data_by_variable_with_metadata(
 
 ## Documentation
 
-Full documentation is built with Sphinx. To build locally:
+Documentation uses [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) with
+[mkdocstrings](https://mkdocstrings.github.io/) and [mike](https://github.com/jimporter/mike) for versioned
+[GitHub Pages](https://pages.github.com/) (`gh-pages` branch). To build locally:
 
 ```bash
+uv sync --group docs
 make docs
-# or: cd docs && make html
+# or: uv run mkdocs serve   # live reload at http://127.0.0.1:8000
 ```
 
-The built HTML is written to `docs/_build/html/`.
+The static site is written to `site/` (gitignored). Published URLs use version directories and a `latest`
+alias; configure the repository **Settings → Pages** to deploy from the **`gh-pages`** branch at **`/`
+(root)**.
 
 Key documentation pages:
 
-- [Main Client](docs/main_client.rst) — BDL client, access vs API layer, context manager, async
-- [Access Layer](docs/access_layer.rst) — DataFrame interface, enrichment, pagination, metadata
-- [API Clients](docs/api_clients.rst) — Low-level raw-JSON clients
-- [Configuration](docs/config.rst) — All options and environment variables
-- [Rate Limiting](docs/rate_limiting.rst) — Quotas, retry, custom limits
+- [Main client](docs/main_client.md) — BDL client, access vs API layer, context manager, async
+- [Access layer](docs/access_layer.md) — DataFrame interface, enrichment, pagination, metadata
+- [API clients](docs/api_clients.md) — Low-level raw-JSON clients
+- [Configuration](docs/config.md) — All options and environment variables
+- [Rate limiting](docs/rate_limiting.md) — Quotas, retry, custom limits
 - [Examples](docs/examples.ipynb) — Jupyter notebook with real-world examples
 - [Changelog](CHANGELOG.md) — Release history

docs/_static/.gitkeep

@@ -1,2 +1,2 @@
 # This file ensures the _static directory is tracked in git
-# Sphinx will use this directory for custom static files if needed
+# Optional static assets for MkDocs (e.g. extra_css / extra_javascript)