Merge pull request #29017 from Luap99/readthedocs

build the swagger.yml on readthedocs

.github/workflows/swagger.yml

@@ -1,75 +0,0 @@
-name: Publish swagger
-
-# Build the libpod API spec (pkg/api/swagger.yaml) and publish it to the
-# public GCS bucket consumed by the API reference docs
-# (docs/source/_static/api.html -> https://storage.googleapis.com/libpod-master-releases/swagger-<version>.yaml).
-# Pushes to main publish "swagger-latest.yaml"; tags publish "swagger-<tag>.yaml".
-on:
-  push:
-    branches:
-      - main
-    tags:
-      - "v*"
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  publish-swagger:
-    # TODO we need to setup the permissions and likely use our new oracle bucket instead
-    # For now lets just skip this part
-    if: false
-    name: Build and publish swagger.yaml
-    runs-on: cncf-ubuntu-8-32-x86
-    steps:
-      - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-        with:
-          persist-credentials: false
-
-      - name: Install build dependencies
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y \
-            gawk \
-            libassuan-dev \
-            libbtrfs-dev \
-            libgpgme-dev \
-            libseccomp-dev \
-            libsystemd-dev \
-            libclone-perl \
-            man-db \
-            podman \
-            python3-pip
-
-      - name: Set up Go
-        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6.4.0
-        with:
-          go-version-file: go.mod
-          cache: false
-
-      - name: Build swagger.yaml
-        run: make swagger
-
-      - name: Publish swagger.yaml to GCS
-        env:
-          GCPJSON: ${{ secrets.GCPJSON }}
-          GCPNAME: ${{ secrets.GCPNAME }}
-          GCPPROJECT: libpod-218412
-          # Pushes to main publish "latest"; tags publish under their tag name.
-          TO_GCSURI: gs://libpod-master-releases/swagger-${{ github.ref_type == 'tag' && github.ref_name || 'latest' }}.yaml
-          FROM_FILEPATH: /src/pkg/api/swagger.yaml
-          # Uploader image tag, copied from .cirrus.yml IMAGE_SUFFIX.
-          GCSUPLD_FQIN: quay.io/libpod/gcsupld:c20260425t010036z-f43f42d14
-        run: |
-          # Pass secrets through podman's environment (-e VAR) rather than an
-          # env-file so they are never written to disk.
-          podman run --rm --security-opt label=disable \
-            -e GCPJSON -e GCPNAME -e GCPPROJECT -e FROM_FILEPATH -e TO_GCSURI \
-            -v "$GITHUB_WORKSPACE:/src:ro" \
-            --workdir /src \
-            "$GCSUPLD_FQIN"

.readthedocs.yaml

@@ -6,9 +6,14 @@ 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"
+    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:

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 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,

docs/source/Reference.rst

@@ -3,8 +3,4 @@
 Reference
 =========
 
-Show the API documentation for version:
-
-* `latest (main branch) <_static/api.html>`_
-
-.. api-versions::
+Show the API documentation for the `current version <_static/api.html>`_

docs/source/_static/api.html

@@ -15,67 +15,16 @@
         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;
-      }
     </style>
   </head>
   <body>
     <script src="https://cdn.jsdelivr.net/npm/redoc@v2/bundles/redoc.standalone.js"> </script>
-    <select id="versionSelect" aria-label="Version">
-      <option>latest</option>
-    </select>
     <div id="redoc-container"></div>
-    <script type="module">
-      const versionSelect = document.getElementById("versionSelect");
-      const resp = await fetch("versions.json");
-      const versions = await resp.json();
-      for (const version of versions) {
-        const opt = document.createElement("option");
-        opt.textContent = "v" + version;
-        versionSelect.append(opt);
-      }
-      // get version from query (default to latest)
-      var queryString = window.location.search;
-      var query = new URLSearchParams(queryString);
-      var version = "latest";
-      if (query.has("version")) {
-        versionSelect.value = query.get("version");
-      }
-
-      function load() {
-        // Note: We replace the whole container element because otherwise Redoc.init calls
-        // after the initial Redoc.init call take a second rather than just a few ms.
-        let redocContainer = document.createElement('div');
-        redocContainer.id = 'redoc-container';
-        let oldContainer =  document.getElementById("redoc-container");
-        oldContainer.parentNode.replaceChild(redocContainer, oldContainer);
-
-        Redoc.init("https://storage.googleapis.com/libpod-master-releases/swagger-" + versionSelect.value + ".yaml", {
-          sortPropsAlphabetically: true,
-          sortOperationsAlphabetically: true,
-        }, redocContainer);
-        history.pushState(null, '', '?version=' + versionSelect.value);
-        document.title = 'Reference ' + versionSelect.value;
-      }
-      load();
-      versionSelect.addEventListener('change', load);
+    <script>
+      Redoc.init("swagger.yaml", {
+        sortPropsAlphabetically: true,
+        sortOperationsAlphabetically: true,
+      }, document.getElementById("redoc-container"));
     </script>
   </body>
 </html>

docs/source/_static/versions.json

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

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)

pkg/api/server/doc.go

@@ -46,13 +46,13 @@
 //	Schemes: http, https
 //	Host: podman.io
 //	BasePath: /
-//	Version: 5.0.0
+//	Version: 6.0.0
 //	License: Apache-2.0 https://opensource.org/licenses/Apache-2.0
 //	Contact: Podman <podman@lists.podman.io> https://podman.io/community
 //
 //	InfoExtensions:
 //	x-logo:
-//	  - url: https://raw.githubusercontent.com/containers/libpod/main/logo/podman-logo.png
+//	  - url: https://raw.githubusercontent.com/podman-container-tools/podman/main/logo/podman-logo.png
 //	  - altText: "Podman logo"
 //
 //	Produces: