docs: generate Reference version list from json file

Signed-off-by: Martin Fischer <martin@push-f.com>

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
+      For major and minor versions also add the new version to
-      `docs/source/Reference.rst` to show the new swagger version on docs.podman.io.
+      `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,

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>`_
+.. api-versions::
-
-* `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>`_

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"
+]

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)