Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

Add docs version swicther based on mike

Louis Choquel75d08fbd3183
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
index 34a42ff7a..bc7b5a958 100644
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@@ -1,20 +1,23 @@
-name: Preview MkDocs on GitHub Pages
+name: Deploy MkDocs with Versioning
on:
push:
- branches: main
+ branches:
+ - main
permissions:
contents: write
pages: write
jobs:
- preview:
+ deploy:
runs-on: ubuntu-latest
env:
VIRTUAL_ENV: ${{ github.workspace }}/.venv
steps:
- uses: actions/checkout@v4
+ with:
+ fetch-depth: 0 # Required for mike to access git history
- uses: actions/setup-python@v5
with:
@@ -32,5 +35,20 @@ jobs:
- name: Install docs dependencies
run: uv pip install -e ".[docs]"
+ - name: Configure git for mike
+ run: |
+ git config --global user.name "github-actions[bot]"
+ git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+ - name: Extract version from pyproject.toml
+ id: version
+ run: |
+ VERSION=$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+ echo "version=$VERSION" >> $GITHUB_OUTPUT
+ echo "Extracted version: $VERSION"
+
- name: Deploy documentation
- run: make docs-deploy
+ run: |
+ . "$VIRTUAL_ENV/bin/activate"
+ mike deploy --push --update-aliases ${{ steps.version.outputs.version }} latest
+ mike set-default --push latest
diff --git a/Makefile b/Makefile
index f47291b81..888809fb7 100644
--- a/Makefile
+++ b/Makefile
@@ -15,6 +15,7 @@ VENV_PYRIGHT := "$(VIRTUAL_ENV)/bin/pyright"
VENV_MYPY := "$(VIRTUAL_ENV)/bin/mypy"
VENV_PIPELEX := "$(VIRTUAL_ENV)/bin/pipelex"
VENV_MKDOCS := "$(VIRTUAL_ENV)/bin/mkdocs"
+VENV_MIKE := "$(VIRTUAL_ENV)/bin/mike"
VENV_PYLINT := "$(VIRTUAL_ENV)/bin/pylint"
VENV_PIPELEX_DEV := "$(VIRTUAL_ENV)/bin/pipelex-dev"
@@ -98,7 +99,11 @@ make check-TODOs - Check for TODOs
make docs - Serve documentation locally with mkdocs
make docs-check - Check documentation build with mkdocs
-make docs-deploy - Deploy documentation with mkdocs
+make docs-serve-versioned - Serve versioned docs locally with mike
+make docs-list - List deployed documentation versions
+make docs-deploy VERSION=x.y.z - Deploy docs as version x.y.z (local, no push)
+make docs-deploy-stable - Deploy stable docs with 'latest' alias (CI only)
+make docs-deploy-beta - Manually deploy pre-release docs with '-beta' suffix
make check - Shorthand -> format lint mypy
make c - Shorthand -> check
@@ -121,7 +126,8 @@ export HELP
run-all-tests run-manual-trigger-gha-tests run-gha_disabled-tests \
validate v check c cc \
merge-check-ruff-lint merge-check-ruff-format merge-check-mypy merge-check-pyright \
- li check-unused-imports fix-unused-imports check-uv check-TODOs docs docs-check docs-deploy \
+ li check-unused-imports fix-unused-imports check-uv check-TODOs \
+ docs docs-check docs-serve-versioned docs-list docs-deploy docs-deploy-stable docs-deploy-beta \
test-count check-test-badge
all help:
@@ -528,6 +534,9 @@ check-TODOs: env
### DOCUMENTATION
##########################################################################################
+# Extract version from pyproject.toml for docs deployment
+DOCS_VERSION := $(shell grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+
docs: env
$(call PRINT_TITLE,"Serving documentation with mkdocs")
$(VENV_MKDOCS) serve -a 127.0.0.1:8000 -f "$(CURDIR)/mkdocs.yml" --watch "$(CURDIR)/docs" -s
@@ -536,9 +545,26 @@ docs-check: env
$(call PRINT_TITLE,"Checking documentation build with mkdocs")
$(VENV_MKDOCS) build --strict
+docs-serve-versioned: env
+ $(call PRINT_TITLE,"Serving versioned documentation with mike")
+ $(VENV_MIKE) serve
+
+docs-list: env
+ $(call PRINT_TITLE,"Listing deployed documentation versions")
+ $(VENV_MIKE) list
+
docs-deploy: env
- $(call PRINT_TITLE,"Deploying documentation with mkdocs")
- $(VENV_MKDOCS) gh-deploy --force --clean -s
+ $(call PRINT_TITLE,"Deploying documentation version $(if $(VERSION),$(VERSION),$(DOCS_VERSION))")
+ $(VENV_MIKE) deploy $(if $(VERSION),$(VERSION),$(DOCS_VERSION))
+
+docs-deploy-stable: env
+ $(call PRINT_TITLE,"Deploying stable documentation $(DOCS_VERSION) with latest alias")
+ $(VENV_MIKE) deploy --push --update-aliases $(DOCS_VERSION) latest
+ $(VENV_MIKE) set-default --push latest
+
+docs-deploy-beta: env
+ $(call PRINT_TITLE,"Deploying pre-release documentation $(DOCS_VERSION)-beta")
+ $(VENV_MIKE) deploy --push $(DOCS_VERSION)-beta
##########################################################################################
### SHORTHANDS
diff --git a/mkdocs.yml b/mkdocs.yml
index 3cbcb9358..fdfea5301 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -45,6 +45,8 @@ extra:
link: https://go.pipelex.com/discord
name: Pipelex on Discord
generator: false
+ version:
+ provider: mike
plugins:
- search
diff --git a/pyproject.toml b/pyproject.toml
index b34a5e0e5..676b68d27 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -59,10 +59,11 @@ google = ["google-auth-oauthlib>=1.2.1"]
google-genai = ["google-genai", "instructor[google-genai]"]
mistralai = ["mistralai==1.5.2"]
docs = [
- "mkdocs==1.6.1",
- "mkdocs-glightbox==0.4.0",
- "mkdocs-material==9.6.14",
- "mkdocs-meta-manager==1.1.0",
+ "mkdocs>=1.6.1",
+ "mkdocs-glightbox>=0.4.0",
+ "mkdocs-material>=9.6.14",
+ "mkdocs-meta-manager>=1.1.0",
+ "mike>=2.1.3",
]
dev = [
diff --git a/uv.lock b/uv.lock
index 78aa023e9..cebf5d984 100644
--- a/uv.lock
+++ b/uv.lock
@@ -873,6 +873,27 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl", hash = "sha256:771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea", size = 71008, upload-time = "2025-10-12T14:55:18.883Z" },
]
+[[package]]
+name = "importlib-metadata"
+version = "8.7.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+ { name = "zipp" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f3/49/3b30cad09e7771a4982d9975a8cbf64f00d4a1ececb53297f1d9a7be1b10/importlib_metadata-8.7.1.tar.gz", hash = "sha256:49fef1ae6440c182052f407c8d34a68f72efc36db9ca90dc0113398f2fdde8bb", size = 57107, upload-time = "2025-12-21T10:00:19.278Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/fa/5e/f8e9a1d23b9c20a551a8a02ea3637b4642e22c2626e3a13a9a29cdea99eb/importlib_metadata-8.7.1-py3-none-any.whl", hash = "sha256:5a1f80bf1daa489495071efbb095d75a634cf28a8bc299581244063b53176151", size = 27865, upload-time = "2025-12-21T10:00:18.329Z" },
+]
+
+[[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, upload-time = "2025-01-03T18:51:56.698Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/a4/ed/1f1afb2e9e7f38a545d628f864d562a5ae64fe6f7a10e28ffb9b185b4e89/importlib_resources-6.5.2-py3-none-any.whl", hash = "sha256:789cfdc3ed28c78b67a06acb8126751ced69a3d5f79c095a98298cd8a760ccec", size = 37461, upload-time = "2025-01-03T18:51:54.306Z" },
+]
+
[[package]]
name = "iniconfig"
version = "2.3.0"
@@ -1162,6 +1183,25 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/2c/19/04f9b178c2d8a15b076c8b5140708fa6ffc5601fb6f1e975537072df5b2a/mergedeep-1.3.4-py3-none-any.whl", hash = "sha256:70775750742b25c0d8f36c55aed03d24c3384d17c951b3175d898bd778ef0307", size = 6354, upload-time = "2021-02-05T18:55:29.583Z" },
]
+[[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, upload-time = "2024-08-13T05:02:14.167Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/fd/1a/31b7cd6e4e7a02df4e076162e9783620777592bea9e4bb036389389af99d/mike-2.1.3-py3-none-any.whl", hash = "sha256:d90c64077e84f06272437b464735130d380703a76a5738b152932884c60c062a", size = 33754, upload-time = "2024-08-13T05:02:12.515Z" },
+]
+
[[package]]
name = "mistralai"
version = "1.5.2"
@@ -1770,6 +1810,7 @@ dev = [
{ name = "types-pyyaml" },
]
docs = [
+ { name = "mike" },
{ name = "mkdocs" },
{ name = "mkdocs-glightbox" },
{ name = "mkdocs-material" },
@@ -1808,11 +1849,12 @@ requires-dist = [
{ name = "json2html", specifier = ">=1.3.0" },
{ name = "kajson", specifier = "==0.3.1" },
{ name = "markdown", specifier = ">=3.6" },
+ { name = "mike", marker = "extra == 'docs'", specifier = ">=2.1.3" },
{ name = "mistralai", marker = "extra == 'mistralai'", specifier = "==1.5.2" },
- { name = "mkdocs", marker = "extra == 'docs'", specifier = "==1.6.1" },
- { name = "mkdocs-glightbox", marker = "extra == 'docs'", specifier = "==0.4.0" },
- { name = "mkdocs-material", marker = "extra == 'docs'", specifier = "==9.6.14" },
- { name = "mkdocs-meta-manager", marker = "extra == 'docs'", specifier = "==1.1.0" },
+ { name = "mkdocs", marker = "extra == 'docs'", specifier = ">=1.6.1" },
+ { name = "mkdocs-glightbox", marker = "extra == 'docs'", specifier = ">=0.4.0" },
+ { name = "mkdocs-material", marker = "extra == 'docs'", specifier = ">=9.6.14" },
+ { name = "mkdocs-meta-manager", marker = "extra == 'docs'", specifier = ">=1.1.0" },
{ name = "mypy", marker = "extra == 'dev'", specifier = ">=1.11.2" },
{ name = "networkx", specifier = ">=3.4.2" },
{ name = "openai", specifier = ">=1.108.1" },
@@ -2162,6 +2204,15 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/81/40/b2d7b9fdccc63e48ae4dbd363b6b89eb7ac346ea49ed667bb71f92af3021/pymdown_extensions-10.17.1-py3-none-any.whl", hash = "sha256:1f160209c82eecbb5d8a0d8f89a4d9bd6bdcbde9a8537761844cfc57ad5cd8a6", size = 266310, upload-time = "2025-11-11T21:44:56.809Z" },
]
+[[package]]
+name = "pyparsing"
+version = "3.3.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/33/c1/1d9de9aeaa1b89b0186e5fe23294ff6517fce1bc69149185577cd31016b2/pyparsing-3.3.1.tar.gz", hash = "sha256:47fad0f17ac1e2cad3de3b458570fbc9b03560aa029ed5e16ee5554da9a2251c", size = 1550512, upload-time = "2025-12-23T03:14:04.391Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/8b/40/2614036cdd416452f5bf98ec037f38a1afb17f327cb8e6b652d4729e0af8/pyparsing-3.3.1-py3-none-any.whl", hash = "sha256:023b5e7e5520ad96642e2c6db4cb683d3970bd640cdf7115049a6e9c3682df82", size = 121793, upload-time = "2025-12-23T03:14:02.103Z" },
+]
+
[[package]]
name = "pypdfium2"
version = "5.0.0"
@@ -2767,6 +2818,15 @@ wheels = [
{ url = "https://files.pythonhosted.org/packages/a7/c2/fe1e52489ae3122415c51f387e221dd0773709bad6c6cdaa599e8a2c5185/urllib3-2.5.0-py3-none-any.whl", hash = "sha256:e6b01673c0fa6a13e374b50871808eb3bf7046c4b125b216f6bf1cc604cff0dc", size = 129795, upload-time = "2025-06-18T14:07:40.39Z" },
]
+[[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, upload-time = "2020-11-30T02:24:09.646Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/a4/ce/3b6fee91c85626eaf769d617f1be9d2e15c1cca027bbdeb2e0d751469355/verspec-0.1.0-py3-none-any.whl", hash = "sha256:741877d5633cc9464c45a469ae2a31e801e6dbbaa85b9675d481cda100f11c31", size = 19640, upload-time = "2020-11-30T02:24:08.387Z" },
+]
+
[[package]]
name = "virtualenv"
version = "20.35.4"
@@ -3021,3 +3081,12 @@ name = "yattag"
version = "1.16.1"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/1c/1a/d3b2a2b8f843f5e7138471c4a5c9172ef62bb41239aa4371784b7448110c/yattag-1.16.1.tar.gz", hash = "sha256:baa8f254e7ea5d3e0618281ad2ff5610e0e5360b3608e695c29bfb3b29d051f4", size = 29069, upload-time = "2024-11-02T22:38:30.443Z" }
+
+[[package]]
+name = "zipp"
+version = "3.23.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e3/02/0f2892c661036d50ede074e376733dca2ae7c6eb617489437771209d4180/zipp-3.23.0.tar.gz", hash = "sha256:a07157588a12518c9d4034df3fbbee09c814741a33ff63c05fa29d26a2404166", size = 25547, upload-time = "2025-06-08T17:06:39.4Z" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/2e/54/647ade08bf0db230bfea292f893923872fd20be6ac6f53b2b936ba839d75/zipp-3.23.0-py3-none-any.whl", hash = "sha256:071652d6115ed432f5ce1d34c336c0adfd6a884660d1e9712a256d3d3bd4b14e", size = 10276, upload-time = "2025-06-08T17:06:38.034Z" },
+]