From 8dee14e304cf8986646c154e550d29d3dbf8922a Mon Sep 17 00:00:00 2001 From: Paul Holzinger Date: Tue, 23 Jun 2026 17:15:36 +0200 Subject: [PATCH 1/6] readthedocs: update build env Signed-off-by: Paul Holzinger --- .readthedocs.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 501aa38100..592a1847fe 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,9 +6,9 @@ version: 2 # Set the version of Python and other tools you might need build: - os: ubuntu-22.04 + os: ubuntu-26.04 tools: - python: "3.11" + python: "3.14" # Build documentation in the docs/ directory with Sphinx sphinx: From 250c530055702ae577910373b92a8bfaf58c493b Mon Sep 17 00:00:00 2001 From: Paul Holzinger Date: Tue, 23 Jun 2026 17:50:03 +0200 Subject: [PATCH 2/6] Revert "docs: generate Reference version list from json file" This reverts commit 858150288f686b8bb8366d87be28f105b285471f. In the next commit I add a custom build for the swagger yaml which adds it as part of the main readthedocs build so we can use the default version selector and drop our custom workarounds. Signed-off-by: Paul Holzinger --- RELEASE_PROCESS.md | 4 +-- docs/source/Reference.rst | 42 ++++++++++++++++++++++++++++++- docs/source/_static/versions.json | 24 ------------------ docs/source/conf.py | 36 +------------------------- 4 files changed, 44 insertions(+), 62 deletions(-) delete mode 100644 docs/source/_static/versions.json diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md index 4ac94e3cbe..f6cf911df2 100644 --- a/RELEASE_PROCESS.md +++ b/RELEASE_PROCESS.md @@ -156,8 +156,8 @@ spelled with complete minutiae. 1. Edit `version/rawversion/version.go` and bump the `Version` value to the new release version. If there were API changes, also bump `APIVersion` value. Make sure to also bump the version in the swagger.yaml `pkg/api/server/docs.go` - For major and minor versions also add the new version to - `docs/source/_static/versions.json` to show the new swagger version on docs.podman.io. + For major and minor versions also add the new branch name to + `docs/source/Reference.rst` to show the new swagger version on docs.podman.io. 1. Commit this and sign the commit (`git commit -a -s -S`). The commit message should be `Bump to vX.Y.Z` (using the actual version numbers). 1. Push this single change to your GitHub fork, and make a new PR, diff --git a/docs/source/Reference.rst b/docs/source/Reference.rst index c1bed83d34..a9e66edef4 100644 --- a/docs/source/Reference.rst +++ b/docs/source/Reference.rst @@ -7,4 +7,44 @@ Show the API documentation for version: * `latest (main branch) <_static/api.html>`_ -.. api-versions:: +* `version 5.6 <_static/api.html?version=v5.6>`_ + +* `version 5.5 <_static/api.html?version=v5.5>`_ + +* `version 5.4 <_static/api.html?version=v5.4>`_ + +* `version 5.3 <_static/api.html?version=v5.3>`_ + +* `version 5.2 <_static/api.html?version=v5.2>`_ + +* `version 5.1 <_static/api.html?version=v5.1>`_ + +* `version 5.0 <_static/api.html?version=v5.0>`_ + +* `version 4.9 <_static/api.html?version=v4.9>`_ + +* `version 4.8 <_static/api.html?version=v4.8>`_ + +* `version 4.7 <_static/api.html?version=v4.7>`_ + +* `version 4.6 <_static/api.html?version=v4.6>`_ + +* `version 4.5 <_static/api.html?version=v4.5>`_ + +* `version 4.4 <_static/api.html?version=v4.4>`_ + +* `version 4.3 <_static/api.html?version=v4.3>`_ + +* `version 4.2 <_static/api.html?version=v4.2>`_ + +* `version 4.1 <_static/api.html?version=v4.1>`_ + +* `version 4.0 <_static/api.html?version=v4.0>`_ + +* `version 3.4 <_static/api.html?version=v3.4>`_ + +* `version 3.3 <_static/api.html?version=v3.3>`_ + +* `version 3.2 <_static/api.html?version=v3.2>`_ + +* `version 3.1 <_static/api.html?version=v3.1>`_ diff --git a/docs/source/_static/versions.json b/docs/source/_static/versions.json deleted file mode 100644 index 9ce561a80b..0000000000 --- a/docs/source/_static/versions.json +++ /dev/null @@ -1,24 +0,0 @@ -[ - "5.7", - "5.6", - "5.5", - "5.4", - "5.3", - "5.2", - "5.1", - "5.0", - "4.9", - "4.8", - "4.7", - "4.6", - "4.5", - "4.4", - "4.3", - "4.2", - "4.1", - "4.0", - "3.4", - "3.3", - "3.2", - "3.1" -] diff --git a/docs/source/conf.py b/docs/source/conf.py index 95d750b416..a5a271d8d5 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -14,14 +14,10 @@ # import sys # sys.path.insert(0, os.path.abspath('.')) -import json -import os import re +import os import subprocess -from docutils.parsers.rst import Directive -from docutils import nodes - # Define the canonical URL for our custom docs.podman.io domain configured on Read the Docs html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "") @@ -107,35 +103,5 @@ def convert_markdown_title(app, docname, source): # after the user's last visit. source[0] = re.sub(r"^% (.*)\s(\d)", r"```{title} \g<1>\n```", source[0]) - -class APIVersionsDirective(Directive): - """ - Custom directive to generate a bullet list from the versions defined in _static/versions.json. - - Usage in RST: - .. api-versions:: - """ - required_arguments = 0 - has_content = False - - def run(self): - env = self.state.document.settings.env - json_file = f"{env.app.confdir}/_static/versions.json" - - with open(json_file, "r") as f: - versions = json.load(f) - - bullet_list = nodes.bullet_list() - - for version in versions: - list_item = nodes.list_item() - paragraph = nodes.paragraph() - paragraph += nodes.reference("", f"version {version}", refuri=f"_static/api.html?version=v{version}") - list_item += paragraph - bullet_list += list_item - - return [bullet_list] - def setup(app): - app.add_directive("api-versions", APIVersionsDirective) app.connect("source-read", convert_markdown_title) From 50a7acb3641d3ebc5a440a766642fc8e205d5499 Mon Sep 17 00:00:00 2001 From: Paul Holzinger Date: Tue, 23 Jun 2026 17:57:02 +0200 Subject: [PATCH 3/6] Revert "docs: introduce custom version selector in api.html" This reverts commit f87c8b9cba9141f02e5aa8429e3d019bbc0d834e. Signed-off-by: Paul Holzinger --- docs/source/_static/api.html | 55 ++++-------------------------------- 1 file changed, 6 insertions(+), 49 deletions(-) diff --git a/docs/source/_static/api.html b/docs/source/_static/api.html index 666e38c135..86c07742ed 100644 --- a/docs/source/_static/api.html +++ b/docs/source/_static/api.html @@ -15,67 +15,24 @@ margin: 0; padding: 0; } - /* - * ReadTheDocs injects its version selector which is confusing on - * this page since it doesn't affect the API version. So we hide it. - */ - readthedocs-flyout { - display: none; - } - /* Our own version selector. */ - #versionSelect { - position: fixed; - /* - * Like the ReadTheDocs selector we put it in the bottom-right corner. - * When the browser is narrow ReDoc puts its menu button in the same corner, - * the position here is chosen not to overlap with that. - */ - bottom: 14px; - right: 14px; - z-index: 99; - } -
- From c2ffe88ce08997328a6e6cf7b36e6b1237522a7d Mon Sep 17 00:00:00 2001 From: Paul Holzinger Date: Tue, 23 Jun 2026 18:00:00 +0200 Subject: [PATCH 4/6] build the swagger.yml on readthedocs One problem with the swagger upload is we need an extra bucket and then we need our own custom version schema and selector on the website. If we can just embed the swagger.yml as part of the official build we can get rid of all of that and have a much simpler way as the regular readthedocs version selector will work. We also no longer need to maintain an extra bucket upload and no longer need to update the version list which was forgotten all the time. Fixes: #28827 Signed-off-by: Paul Holzinger --- .readthedocs.yaml | 5 ++++ RELEASE_PROCESS.md | 2 -- docs/source/Reference.rst | 46 +----------------------------------- docs/source/_static/api.html | 10 +------- 4 files changed, 7 insertions(+), 56 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 592a1847fe..461f710639 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -9,6 +9,11 @@ build: os: ubuntu-26.04 tools: python: "3.14" + golang: "1.25" + jobs: + pre_build: + - make swagger + - mv pkg/api/swagger.yaml docs/source/_static/swagger.yaml # Build documentation in the docs/ directory with Sphinx sphinx: diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md index f6cf911df2..4c28f86778 100644 --- a/RELEASE_PROCESS.md +++ b/RELEASE_PROCESS.md @@ -156,8 +156,6 @@ spelled with complete minutiae. 1. Edit `version/rawversion/version.go` and bump the `Version` value to the new release version. If there were API changes, also bump `APIVersion` value. Make sure to also bump the version in the swagger.yaml `pkg/api/server/docs.go` - For major and minor versions also add the new branch name to - `docs/source/Reference.rst` to show the new swagger version on docs.podman.io. 1. Commit this and sign the commit (`git commit -a -s -S`). The commit message should be `Bump to vX.Y.Z` (using the actual version numbers). 1. Push this single change to your GitHub fork, and make a new PR, diff --git a/docs/source/Reference.rst b/docs/source/Reference.rst index a9e66edef4..921e897d43 100644 --- a/docs/source/Reference.rst +++ b/docs/source/Reference.rst @@ -3,48 +3,4 @@ Reference ========= -Show the API documentation for version: - -* `latest (main branch) <_static/api.html>`_ - -* `version 5.6 <_static/api.html?version=v5.6>`_ - -* `version 5.5 <_static/api.html?version=v5.5>`_ - -* `version 5.4 <_static/api.html?version=v5.4>`_ - -* `version 5.3 <_static/api.html?version=v5.3>`_ - -* `version 5.2 <_static/api.html?version=v5.2>`_ - -* `version 5.1 <_static/api.html?version=v5.1>`_ - -* `version 5.0 <_static/api.html?version=v5.0>`_ - -* `version 4.9 <_static/api.html?version=v4.9>`_ - -* `version 4.8 <_static/api.html?version=v4.8>`_ - -* `version 4.7 <_static/api.html?version=v4.7>`_ - -* `version 4.6 <_static/api.html?version=v4.6>`_ - -* `version 4.5 <_static/api.html?version=v4.5>`_ - -* `version 4.4 <_static/api.html?version=v4.4>`_ - -* `version 4.3 <_static/api.html?version=v4.3>`_ - -* `version 4.2 <_static/api.html?version=v4.2>`_ - -* `version 4.1 <_static/api.html?version=v4.1>`_ - -* `version 4.0 <_static/api.html?version=v4.0>`_ - -* `version 3.4 <_static/api.html?version=v3.4>`_ - -* `version 3.3 <_static/api.html?version=v3.3>`_ - -* `version 3.2 <_static/api.html?version=v3.2>`_ - -* `version 3.1 <_static/api.html?version=v3.1>`_ +Show the API documentation for the `current version <_static/api.html>`_ diff --git a/docs/source/_static/api.html b/docs/source/_static/api.html index 86c07742ed..8abea0bda1 100644 --- a/docs/source/_static/api.html +++ b/docs/source/_static/api.html @@ -21,15 +21,7 @@