diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md index 24cf0b3c2c..69872580d4 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 branch name to - `docs/source/Reference.rst` to show the new swagger version on docs.podman.io. + 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. 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..c1bed83d34 100644 --- a/docs/source/Reference.rst +++ b/docs/source/Reference.rst @@ -7,44 +7,4 @@ 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>`_ +.. api-versions:: diff --git a/docs/source/_static/api.html b/docs/source/_static/api.html index 0d2d2a8a10..87a5aa4521 100644 --- a/docs/source/_static/api.html +++ b/docs/source/_static/api.html @@ -15,25 +15,67 @@ 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; + } - + +
+ - diff --git a/docs/source/_static/versions.json b/docs/source/_static/versions.json new file mode 100644 index 0000000000..793e9a0841 --- /dev/null +++ b/docs/source/_static/versions.json @@ -0,0 +1,23 @@ +[ + "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 a5a271d8d5..95d750b416 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -14,10 +14,14 @@ # import sys # sys.path.insert(0, os.path.abspath('.')) -import re +import json import os +import re 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", "") @@ -103,5 +107,35 @@ 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)