opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-11-28 17:18:58 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #27295 from not-my-profile/docs-api-version

Browse Source 
docs: introduce custom version selector in api.html
This commit is contained in:
openshift-merge-bot[bot]
2025-10-21 15:10:21 +00:00
committed by GitHub
parent 935e82544a f87c8b9cba
commit d906918c3d
5 changed files with 111 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
RELEASE_PROCESS.md
View File

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

42
docs/source/Reference.rst
View File

@@ -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::

58
docs/source/_static/api.html
View File

@@ -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;
}
</style>
</head>
<body>
<script>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/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")) {
version = query.get("version");
versionSelect.value = query.get("version");
}
var redoc = document.createElement("redoc");
redoc.setAttribute("sort-props-alphabetically","");
redoc.setAttribute("sort-operations-alphabetically","");
redoc.setAttribute("spec-url","https://storage.googleapis.com/libpod-master-releases/swagger-" + version + ".yaml");
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);
document.body.appendChild(redoc);
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>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
</body>
</html>

23
docs/source/_static/versions.json Normal file
View File

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

36
docs/source/conf.py
View File

@@ -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)