Documentation versioning (#2853)

* add documentation versioning * allow release docs workflow dispatch * remove deploy prefix; move docs workflow --------- Co-authored-by: patryk4815 <patryk.sondej@grupawp.pl>
8 months ago · 21dcc0a321
parent 12d9600a0c
commit 21dcc0a321
5 changed files with 132 additions and 15 deletions
--- a/.github/workflows/docs-dev.yml
+++ b/.github/workflows/docs-dev.yml
@ -1,4 +1,4 @@
-name: Docs
+name: Dev Docs
 on: [push, pull_request, workflow_dispatch]

 concurrency:
@ -6,8 +6,8 @@ concurrency:
  cancel-in-progress: true

 jobs:
-  build:
-    name: Build docs
+  check:
+    name: Check docs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
@ -35,8 +35,8 @@ jobs:

  deploy:
    if: github.event_name == 'push' && contains(fromJson('["refs/heads/dev"]'), github.ref)
-    needs: build
-    name: Deploy docs
+    needs: check
+    name: Deploy dev docs
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
@ -45,18 +45,17 @@ jobs:
      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh

-      - name: Install gdb (needed for doc verification)
-        run: |
-          sudo apt update
-          sudo apt install -y gdb
-
-      - name: Verify docs are up to date with source
-        run: |
-          ./scripts/verify_docs.sh
-
      - name: Copy README.md to docs/index.md
        run: cp README.md docs/index.md

      - name: Deploy site
        run: |
-          uv run --group docs mkdocs gh-deploy --strict --force
+          # mike pushes commits to the gh-pages branch
+          git config --global user.email "doc-bot@pwndbg.re"
+          git config --global user.name "DocBot"
+          git fetch --no-tags --prune --depth=1 origin +refs/heads/gh-pages:refs/remotes/origin/gh-pages
+          uv run --group docs mike deploy \
+            --update-aliases \
+            --push \
+            --remote origin \
+            dev
--- a/.github/workflows/docs-release.yml
+++ b/.github/workflows/docs-release.yml
@ -0,0 +1,39 @@
+name: Latest Release Docs
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    name: Deploy docs for latest release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Only allow running on tag refs
+        if: ${{ github.ref_type != 'tag' }}
+        run: |
+          echo "You must run this workflow in the context of a tag."
+          exit 1
+
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+
+      - name: Install uv
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh
+
+      - name: Copy README.md to docs/index.md
+        run: cp README.md docs/index.md
+
+      - name: Deploy site
+        run: |
+          # mike pushes commits to the gh-pages branch
+          git config --global user.email "doc-bot@pwndbg.re"
+          git config --global user.name "DocBot"
+          git fetch --no-tags --prune --depth=1 origin +refs/heads/gh-pages:refs/remotes/origin/gh-pages
+          uv run --group docs mike deploy \
+            --update-aliases \
+            --push \
+            --remote origin \
+            ${{ github.ref_name }} \
+            latest
--- a/mkdocs.yml
+++ b/mkdocs.yml
@ -133,6 +133,12 @@ plugins:
      modules: ['pwndbg']
      nav_section_title: "Source"

+  # Documentation versioning
+  - mike:
+      css_dir: stylesheets
+      version_selector: true
+      canonical_version: latest
+
  - rss:
 # https://squidfunk.github.io/mkdocs-material/tutorials/blogs/engage/#rss-feeds
 # https://guts.github.io/mkdocs-rss-plugin/configuration/#plugin-options
@ -159,6 +165,9 @@ extra:
      link: https://discord.gg/x47DssnGwm
  # Set to false to hide the "Made with Material for MkDocs" text :(.
  generator: true
+  # material integration with mike (doc versioning)
+  version:
+    provider: mike

 extra_css:
  - stylesheets/extra.css
--- a/pyproject.toml
+++ b/pyproject.toml
@ -70,6 +70,7 @@ docs = [
    "griffe-modernized-annotations",
    # Used by mkdocstrings to format source.
    "ruff",
+    "mike",
 ]

 [tool.ruff]
--- a/uv.lock
+++ b/uv.lock
@ -499,6 +499,27 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/76/c6/c88e154df9c4e1a2a66ccf0005a88dfb2650c1dffb6f5ce603dfbd452ce3/idna-3.10-py3-none-any.whl", hash = "sha256:946d195a0d259cbba61165e88e65941f16e9b36ea6ddb97f00452bae8b1287d3", size = 70442 },
 ]

+[[package]]
+name = "importlib-metadata"
+version = "8.6.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "zipp" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/33/08/c1395a292bb23fd03bdf572a1357c5a733d3eecbab877641ceacab23db6e/importlib_metadata-8.6.1.tar.gz", hash = "sha256:310b41d755445d74569f993ccfc22838295d9fe005425094fad953d7f15c8580", size = 55767 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/79/9d/0fb148dc4d6fa4a7dd1d8378168d9b4cd8d4560a6fbf6f0121c5fc34eb68/importlib_metadata-8.6.1-py3-none-any.whl", hash = "sha256:02a89390c1e15fdfdc0d7c6b25cb3e62650d0494005c97d6f148bf5b9787525e", size = 26971 },
+]
+
+[[package]]
+name = "importlib-resources"
+version = "6.5.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/cf/8c/f834fbf984f691b4f7ff60f50b514cc3de5cc08abfc3295564dd89c5e2e7/importlib_resources-6.5.2.tar.gz", hash = "sha256:185f87adef5bcc288449d98fb4fba07cea78bc036455dd44c5fc4a2fe78fed2c", size = 44693 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a4/ed/1f1afb2e9e7f38a545d628f864d562a5ae64fe6f7a10e28ffb9b185b4e89/importlib_resources-6.5.2-py3-none-any.whl", hash = "sha256:789cfdc3ed28c78b67a06acb8126751ced69a3d5f79c095a98298cd8a760ccec", size = 37461 },
+]
+
 [[package]]
 name = "iniconfig"
 version = "2.0.0"
@ -705,6 +726,25 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/2c/19/04f9b178c2d8a15b076c8b5140708fa6ffc5601fb6f1e975537072df5b2a/mergedeep-1.3.4-py3-none-any.whl", hash = "sha256:70775750742b25c0d8f36c55aed03d24c3384d17c951b3175d898bd778ef0307", size = 6354 },
 ]

+[[package]]
+name = "mike"
+version = "2.1.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "importlib-metadata" },
+    { name = "importlib-resources" },
+    { name = "jinja2" },
+    { name = "mkdocs" },
+    { name = "pyparsing" },
+    { name = "pyyaml" },
+    { name = "pyyaml-env-tag" },
+    { name = "verspec" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ab/f7/2933f1a1fb0e0f077d5d6a92c6c7f8a54e6128241f116dff4df8b6050bbf/mike-2.1.3.tar.gz", hash = "sha256:abd79b8ea483fb0275b7972825d3082e5ae67a41820f8d8a0dc7a3f49944e810", size = 38119 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fd/1a/31b7cd6e4e7a02df4e076162e9783620777592bea9e4bb036389389af99d/mike-2.1.3-py3-none-any.whl", hash = "sha256:d90c64077e84f06272437b464735130d380703a76a5738b152932884c60c062a", size = 33754 },
+]
+
 [[package]]
 name = "mkdocs"
 version = "1.6.1"
@ -1160,6 +1200,7 @@ dev = [
 docs = [
    { name = "griffe-modernized-annotations" },
    { name = "mdutils" },
+    { name = "mike" },
    { name = "mkdocs" },
    { name = "mkdocs-api-autonav" },
    { name = "mkdocs-gen-files" },
@ -1215,6 +1256,7 @@ dev = [
 docs = [
    { name = "griffe-modernized-annotations" },
    { name = "mdutils" },
+    { name = "mike" },
    { name = "mkdocs" },
    { name = "mkdocs-api-autonav" },
    { name = "mkdocs-gen-files" },
@ -1330,6 +1372,15 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/5e/22/d3db169895faaf3e2eda892f005f433a62db2decbcfbc2f61e6517adfa87/PyNaCl-1.5.0-cp36-abi3-win_amd64.whl", hash = "sha256:20f42270d27e1b6a29f54032090b972d97f0a1b0948cc52392041ef7831fee93", size = 212141 },
 ]

+[[package]]
+name = "pyparsing"
+version = "3.2.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/bb/22/f1129e69d94ffff626bdb5c835506b3a5b4f3d070f17ea295e12c2c6f60f/pyparsing-3.2.3.tar.gz", hash = "sha256:b9c13f1ab8b3b542f72e28f634bad4de758ab3ce4546e4301970ad6fa77c38be", size = 1088608 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/05/e7/df2285f3d08fee213f2d041540fa4fc9ca6c2d44cf36d3a035bf2a8d2bcc/pyparsing-3.2.3-py3-none-any.whl", hash = "sha256:a749938e02d6fd0b59b356ca504a24982314bb090c383e3cf201c95ef7e2bfcf", size = 111120 },
+]
+
 [[package]]
 name = "pyreadline3"
 version = "3.5.4"
@ -1881,6 +1932,15 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/2e/98/1a2ca43e6d646421eea16ec19977e2e6d1ea9079bd9d873bfae513d43f1c/vermin-1.6.0-py2.py3-none-any.whl", hash = "sha256:f1fa9ee40f59983dc40e0477eb2b1fa8061a3df4c3b2bcf349add462a5610efb", size = 90845 },
 ]

+[[package]]
+name = "verspec"
+version = "0.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e7/44/8126f9f0c44319b2efc65feaad589cadef4d77ece200ae3c9133d58464d0/verspec-0.1.0.tar.gz", hash = "sha256:c4504ca697b2056cdb4bfa7121461f5a0e81809255b41c03dda4ba823637c01e", size = 27123 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a4/ce/3b6fee91c85626eaf769d617f1be9d2e15c1cca027bbdeb2e0d751469355/verspec-0.1.0-py3-none-any.whl", hash = "sha256:741877d5633cc9464c45a469ae2a31e801e6dbbaa85b9675d481cda100f11c31", size = 19640 },
+]
+
 [[package]]
 name = "watchdog"
 version = "6.0.0"
@ -1922,6 +1982,15 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/fd/84/fd2ba7aafacbad3c4201d395674fc6348826569da3c0937e75505ead3528/wcwidth-0.2.13-py2.py3-none-any.whl", hash = "sha256:3da69048e4540d84af32131829ff948f1e022c1c6bdb8d6102117aac784f6859", size = 34166 },
 ]

+[[package]]
+name = "zipp"
+version = "3.21.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/3f/50/bad581df71744867e9468ebd0bcd6505de3b275e06f202c2cb016e3ff56f/zipp-3.21.0.tar.gz", hash = "sha256:2c9958f6430a2040341a52eb608ed6dd93ef4392e02ffe219417c1b28b5dd1f4", size = 24545 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b7/1a/7e4798e9339adc931158c9d69ecc34f5e6791489d469f5e50ec15e35f458/zipp-3.21.0-py3-none-any.whl", hash = "sha256:ac1bbe05fd2991f160ebce24ffbac5f6d11d83dc90891255885223d42b3cd931", size = 9630 },
+]
+
 [[package]]
 name = "zstandard"
 version = "0.23.0"