Merge pull request #29039 from Luap99/swagger-doc

docs: update API Reference docs

.readthedocs.yaml

@@ -9,6 +9,7 @@ build:
   os: ubuntu-26.04
   tools:
     python: "3.14"
+    # Note this must be at least the go version from test/tools/go.mod in order to be able to build swagger.
     golang: "1.25"
   jobs:
     pre_build:

docs/README.md

@@ -33,29 +33,16 @@ The syntax for the formatting of all man pages can be found [here](MANPAGE_SYNTA
 
 ## API Reference
 
-The [latest online documentation](http://docs.podman.io/en/latest/_static/api.html) is
-automatically generated by two cooperating automation systems based on committed upstream
-source code.  Firstly, the [`Publish swagger` GitHub Actions workflow](../.github/workflows/swagger.yml)
-builds `pkg/api/swagger.yaml` and uploads it to a public-facing location (Google Storage Bucket -
-an online service for storing unstructured data).  Second, [Read The Docs](readthedocs.com)
-reacts to the github.com repository change, building the content for the [libpod documentation
-site](https://podman.readthedocs.io/).  This site includes for the API section,
-some javascript which consumes the uploaded `swagger.yaml` file directly from the Google
-Storage Bucket.
+The [latest online documentation](https://docs.podman.io/en/latest/_static/api.html) is
+automatically generated by the readthedocs build process. It uses redoc to render the
+swagger.yml file, the swagger is build and injected as static resource in the readthedocs
+build process, see the [`.readthedocs.yaml`](../.readthedocs.yaml) file.
 
-Since there are multiple systems and local cache is involved, it's possible that updates to
-documentation (especially the swagger/API docs) will lag by 10-or-so minutes.  However,
-because the client (i.e. your web browser) is fetching content from multiple locations that
-do not share a common domain, accessing the API section may show a stack-trace similar to
-the following:
-
-![JavaScript Stack Trace Image](../hack/ci/swagger_stack_trace.png)
-
-If reloading the page, or clearing your local cache does not fix the problem, it is
-likely caused by broken metadata needed to protect clients from cross-site-scripting
-style attacks.  Please [notify a maintainer](https://github.com/containers/podman#communications)
-so they may investigate how/why the `swagger.yaml` file's CORS-metadata is
-incorrect, or the file isn't accessible for some other reason.
+The swagger file can be downloaded from `https://docs.podman.io/en/latest/_static/swagger.yaml`.
+Note the latest link always contains the latest yaml from the main branch, if you like a specific
+version replace `latest` with the version, i.e. for `v6.0.0` `https://docs.podman.io/en/v6.0.0/_static/swagger.yaml`.
+Also this new process is only done since v5.8.4. Earlier swagger.yml files where
+uploaded [here](https://storage.googleapis.com/libpod-master-releases).
 
 ## Local Testing
 

test/tools/go.mod

@@ -3,6 +3,7 @@ module go.podman.io/podman/test/tools
 // Warning: if there is a "toolchain" directive anywhere in this file (and most of the
 // time there shouldn't be), its version must be an exact match to the "go" directive.
 
+// Important when updating the version here also update it in .readthedocs.yaml
 go 1.25.0
 
 require (