ci: Use uv rather than a Dockerfile for mkdocs

Author: LukeMathWalker

.github/ci_generator/templates/job_steps/build_docs.jinja

@@ -9,28 +9,22 @@
   run: |
     mkdir -p docs/api_reference
     cp -r target/doc/* docs/api_reference
-- name: Set up QEMU
-  uses: docker/setup-qemu-action@v3
-- name: Set up Docker Buildx
-  uses: docker/setup-buildx-action@v3
-- name: Build and export to Docker
-  uses: docker/build-push-action@v5
-  with:
-    context: docs/
-    load: true
-    tags: pavex-docs
+- name: Install uv
+  uses: astral-sh/setup-uv@v6
+- name: Install the project
+  run: uv sync --locked
 - name: Build docs
   run: |
-    docker run --rm -v ${PWD}:/docs pavex-docs build --strict
-- uses: actions/upload-artifact@v4
+    uv run mkdocs build --strict
+- uses: actions/upload-artifact@v5
   with:
     name: docs
     path: site/
 - name: Fix base
   run: |
     # Convert all "absolute" guide links in the reference to relative links so that we can scan for dead links
-    sudo find . -type f -exec sed -i "s#https://pavex.dev/docs/#file:///${PWD}/site/#g" {} +
-    sudo find . -type f -exec sed -i "s#https://pavex.dev/#file:///${PWD}/site/#g" {} +
+    sudo find ./site -type f -exec sed -i "s#https://pavex.dev/docs/#file:///${PWD}/site/#g" {} +
+    sudo find ./site -type f -exec sed -i "s#https://pavex.dev/#file:///${PWD}/site/#g" {} +
 - name: Link Checker
   uses: lycheeverse/lychee-action@v2
   with:
@@ -45,6 +39,7 @@
       --exclude-path="site/api_reference/pavex/time"
       --exclude-path="site/api_reference/help.html"
       --exclude-path="site/api_reference/settings.html"
+      --exclude-path="site/404.html"
       --exclude=".*crate#per-style$"
       --exclude="https://doc.rust-lang.org/*"
       --exclude="https://stackoverflow.com/*"
@@ -55,4 +50,12 @@
       --require-https
       --no-progress
       site
+- name: Update unstable documentation
+  # if: github.ref == 'refs/heads/main' && github.event_name == 'push' && github.event.repository.full_name == github.repository)
+  run: |
+    # We made some destructive updates to perform link checking,
+    # so best to regenerate the site
+    rm -rf site
+    uv run mkdocs build --strict
+    uv run mike deploy --push --allow-empty unstable
 <%- endblock %>

.github/workflows/docs.yml

@@ -1717,28 +1717,22 @@ jobs:
       run: |
         mkdir -p docs/api_reference
         cp -r target/doc/* docs/api_reference
-    - name: Set up QEMU
-      uses: docker/setup-qemu-action@v3
-    - name: Set up Docker Buildx
-      uses: docker/setup-buildx-action@v3
-    - name: Build and export to Docker
-      uses: docker/build-push-action@v5
-      with:
-        context: docs/
-        load: true
-        tags: pavex-docs
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+    - name: Install the project
+      run: uv sync --locked
     - name: Build docs
       run: |
-        docker run --rm -v ${PWD}:/docs pavex-docs build --strict
-    - uses: actions/upload-artifact@v4
+        uv run mkdocs build --strict
+    - uses: actions/upload-artifact@v5
       with:
         name: docs
         path: site/
     - name: Fix base
       run: |
         # Convert all "absolute" guide links in the reference to relative links so that we can scan for dead links
-        sudo find . -type f -exec sed -i "s#https://pavex.dev/docs/#file:///${PWD}/site/#g" {} +
-        sudo find . -type f -exec sed -i "s#https://pavex.dev/#file:///${PWD}/site/#g" {} +
+        sudo find ./site -type f -exec sed -i "s#https://pavex.dev/docs/#file:///${PWD}/site/#g" {} +
+        sudo find ./site -type f -exec sed -i "s#https://pavex.dev/#file:///${PWD}/site/#g" {} +
     - name: Link Checker
       uses: lycheeverse/lychee-action@v2
       with:
@@ -1753,6 +1747,7 @@ jobs:
           --exclude-path="site/api_reference/pavex/time"
           --exclude-path="site/api_reference/help.html"
           --exclude-path="site/api_reference/settings.html"
+          --exclude-path="site/404.html"
           --exclude=".*crate#per-style$"
           --exclude="https://doc.rust-lang.org/*"
           --exclude="https://stackoverflow.com/*"
@@ -1763,6 +1758,14 @@ jobs:
           --require-https
           --no-progress
           site
+    - name: Update unstable documentation
+      # if: github.ref == 'refs/heads/main' && github.event_name == 'push' && github.event.repository.full_name == github.repository)
+      run: |
+        # We made some destructive updates to perform link checking,
+        # so best to regenerate the site
+        rm -rf site
+        uv run mkdocs build --strict
+        uv run mike deploy --push --allow-empty unstable
     - uses: ./.github/actions/finalize-check
       if: ${{ always() && github.event_name != 'push' }}
       with:

docs/.dockerignore

@@ -9,33 +9,32 @@ and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
 
 ## Prerequisites
 
-We don't want to force you to set up a Python dev environment: we rely on Docker to build and preview the docs.
-Make sure you have [Docker](https://www.docker.com/) installed and running.
-
-You'll then need to build the relevant image:
+Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/), a Python toolchain manager and built tool.
+Then run:
 
 ```bash
-docker build -t pavex-docs .
+uv sync
 ```
 
+from the root of the repository.
+
 ## Commands
 
 You can preview the docs locally by running from the root of the repository (i.e., the parent folder of
 the directory containing this README file):
 
 ```bash
-docker run --rm -it -p 8001:8000 \
-  -v ${PWD}:/docs \
-  pavex-docs
+uv run mkdocs serve --open
 ```
 
-The docs will be available at [http://localhost:8001](http://localhost:8001) and will auto-reload when you make changes.
+The docs will be available at [http://localhost:8000](http://localhost:8000) and will auto-reload when you make changes.
 
 The docs embed the auto-generated API reference for the first-party Pavex crates: the command above mounts the
 relevant folders so that the docs can access the generated HTML files, but it **won't (re)generate them for you**.\
 If you want to generate or update the API reference,
-you'll need to run the following command from the root of the repository:
+you'll need to run the following commands from the root of the repository:
 
 ```bash
-cargo api_ref && cp -r target/doc/* ../docs/api_reference
+mkdir -p docs/api_reference
+cargo api_ref && cp -r target/doc/* docs/api_reference
 ```

docs/Dockerfile

@@ -1,5 +1,5 @@
 [project]
-name = "md-slash"
+name = "md_slash"
 version = "0.1.0"
 readme = "README.md"
 description = "MkDocs extension to convert trailing slashes to <br>"
@@ -8,7 +8,7 @@ requires-python = ">=3.11"
 dependencies = ["Markdown"]
 
 [project.entry-points."markdown.extensions"]
-trailing_slash = "md-slash:makeExtension"
+trailing_slash = "md_slash:makeExtension"
 
 [build-system]
 requires = ["hatchling"]

docs/README.md

@@ -1,15 +1,20 @@
 site_name: Pavex
-site_url: "https://pavex.dev/"
+site_url: "https://pavex.dev/docs/"
 site_description: "The documentation for Pavex, a framework for building robust APIs in Rust."
 repo_url: "https://github.com/LukeMathWalker/pavex"
 repo_name: "LukeMathWalker/pavex"
 edit_uri: "edit/main/docs/"
 plugins:
   #  - social
   - search
+  - mike:
+      canonical_version: "latest"
   - redirects:
       redirect_maps:
         "index.md": "overview/index.md"
+extra:
+  version:
+    provider: "mike"
 markdown_extensions:
   - admonition
   - pymdownx.details

docs/tools/md_slash/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "pavex"
+version = "0.1.0"
+requires-python = ">=3.13"
+dependencies = [
+    "mike>=2.1.3",
+    "mkdocs-awesome-pages-plugin>=2.10.1",
+    "mkdocs-material>=9.6.23",
+    "mkdocs-redirects>=1",
+    "pymdown-extensions>=10",
+    "pygments-ansi-color>=0.3.0",
+    "pip>=25",
+    "md_slash"
+]
+
+[project.entry-points."markdown.extensions"]
+trailing_slash = "md_slash:makeExtension"
+
+[tool.uv.sources]
+md_slash = { workspace = true }
+
+[tool.uv.workspace]
+members = ["docs/tools/md_slash"]