Skip to content

Commit d906918

Browse files
openshift-merge-bot[bot]openshift-merge-bot[bot]
authored
Merge pull request containers#27295 from not-my-profile/docs-api-version
docs: introduce custom version selector in api.html
2 parents 935e825 + f87c8b9 commit d906918

File tree

5 files changed

+111
-52
lines changed

5 files changed

+111
-52
lines changed

‎RELEASE_PROCESS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -156,8 +156,8 @@ spelled with complete minutiae.
156156
1. Edit `version/rawversion/version.go` and bump the `Version` value to the new
157157
release version. If there were API changes, also bump `APIVersion` value.
158158
Make sure to also bump the version in the swagger.yaml `pkg/api/server/docs.go`
159-
For major and minor versions also add the new branch name to
160-
`docs/source/Reference.rst` to show the new swagger version on docs.podman.io.
159+
For major and minor versions also add the new version to
160+
`docs/source/_static/versions.json` to show the new swagger version on docs.podman.io.
161161
1. Commit this and sign the commit (`git commit -a -s -S`). The commit message
162162
should be `Bump to vX.Y.Z` (using the actual version numbers).
163163
1. Push this single change to your GitHub fork, and make a new PR,

‎docs/source/Reference.rst‎

Lines changed: 1 addition & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -7,44 +7,4 @@ Show the API documentation for version:
77

88
* `latest (main branch) <_static/api.html>`_
99

10-
* `version 5.6 <_static/api.html?version=v5.6>`_
11-
12-
* `version 5.5 <_static/api.html?version=v5.5>`_
13-
14-
* `version 5.4 <_static/api.html?version=v5.4>`_
15-
16-
* `version 5.3 <_static/api.html?version=v5.3>`_
17-
18-
* `version 5.2 <_static/api.html?version=v5.2>`_
19-
20-
* `version 5.1 <_static/api.html?version=v5.1>`_
21-
22-
* `version 5.0 <_static/api.html?version=v5.0>`_
23-
24-
* `version 4.9 <_static/api.html?version=v4.9>`_
25-
26-
* `version 4.8 <_static/api.html?version=v4.8>`_
27-
28-
* `version 4.7 <_static/api.html?version=v4.7>`_
29-
30-
* `version 4.6 <_static/api.html?version=v4.6>`_
31-
32-
* `version 4.5 <_static/api.html?version=v4.5>`_
33-
34-
* `version 4.4 <_static/api.html?version=v4.4>`_
35-
36-
* `version 4.3 <_static/api.html?version=v4.3>`_
37-
38-
* `version 4.2 <_static/api.html?version=v4.2>`_
39-
40-
* `version 4.1 <_static/api.html?version=v4.1>`_
41-
42-
* `version 4.0 <_static/api.html?version=v4.0>`_
43-
44-
* `version 3.4 <_static/api.html?version=v3.4>`_
45-
46-
* `version 3.3 <_static/api.html?version=v3.3>`_
47-
48-
* `version 3.2 <_static/api.html?version=v3.2>`_
49-
50-
* `version 3.1 <_static/api.html?version=v3.1>`_
10+
.. api-versions::

‎docs/source/_static/api.html‎

Lines changed: 50 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -15,25 +15,67 @@
1515
margin: 0;
1616
padding: 0;
1717
}
18+
/*
19+
* ReadTheDocs injects its version selector which is confusing on
20+
* this page since it doesn't affect the API version. So we hide it.
21+
*/
22+
readthedocs-flyout {
23+
display: none;
24+
}
25+
/* Our own version selector. */
26+
#versionSelect {
27+
position: fixed;
28+
/*
29+
* Like the ReadTheDocs selector we put it in the bottom-right corner.
30+
* When the browser is narrow ReDoc puts its menu button in the same corner,
31+
* the position here is chosen not to overlap with that.
32+
*/
33+
bottom: 14px;
34+
right: 14px;
35+
z-index: 99;
36+
}
1837
</style>
1938
</head>
2039
<body>
21-
<script>
40+
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
41+
<select id="versionSelect" aria-label="Version">
42+
<option>latest</option>
43+
</select>
44+
<div id="redoc-container"></div>
45+
<script type="module">
46+
const versionSelect = document.getElementById("versionSelect");
47+
const resp = await fetch("versions.json");
48+
const versions = await resp.json();
49+
for (const version of versions) {
50+
const opt = document.createElement("option");
51+
opt.textContent = "v" + version;
52+
versionSelect.append(opt);
53+
}
2254
// get version from query (default to latest)
2355
var queryString = window.location.search;
2456
var query = new URLSearchParams(queryString);
2557
var version = "latest";
2658
if (query.has("version")) {
27-
version = query.get("version");
59+
versionSelect.value = query.get("version");
2860
}
2961

30-
var redoc = document.createElement("redoc");
31-
redoc.setAttribute("sort-props-alphabetically","");
32-
redoc.setAttribute("sort-operations-alphabetically","");
33-
redoc.setAttribute("spec-url","https://storage.googleapis.com/libpod-master-releases/swagger-" + version + ".yaml");
62+
function load() {
63+
// Note: We replace the whole container element because otherwise Redoc.init calls
64+
// after the initial Redoc.init call take a second rather than just a few ms.
65+
let redocContainer = document.createElement('div');
66+
redocContainer.id = 'redoc-container';
67+
let oldContainer = document.getElementById("redoc-container");
68+
oldContainer.parentNode.replaceChild(redocContainer, oldContainer);
3469

35-
document.body.appendChild(redoc);
70+
Redoc.init("https://storage.googleapis.com/libpod-master-releases/swagger-" + versionSelect.value + ".yaml", {
71+
sortPropsAlphabetically: true,
72+
sortOperationsAlphabetically: true,
73+
}, redocContainer);
74+
history.pushState(null, '', '?version=' + versionSelect.value);
75+
document.title = 'Reference ' + versionSelect.value;
76+
}
77+
load();
78+
versionSelect.addEventListener('change', load);
3679
</script>
37-
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
3880
</body>
3981
</html>

‎docs/source/_static/versions.json‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
[
2+
"5.6",
3+
"5.5",
4+
"5.4",
5+
"5.3",
6+
"5.2",
7+
"5.1",
8+
"5.0",
9+
"4.9",
10+
"4.8",
11+
"4.7",
12+
"4.6",
13+
"4.5",
14+
"4.4",
15+
"4.3",
16+
"4.2",
17+
"4.1",
18+
"4.0",
19+
"3.4",
20+
"3.3",
21+
"3.2",
22+
"3.1"
23+
]

‎docs/source/conf.py‎

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,14 @@
1414
# import sys
1515
# sys.path.insert(0, os.path.abspath('.'))
1616

17-
import re
17+
import json
1818
import os
19+
import re
1920
import subprocess
2021

22+
from docutils.parsers.rst import Directive
23+
from docutils import nodes
24+
2125
# Define the canonical URL for our custom docs.podman.io domain configured on Read the Docs
2226
html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
2327

@@ -103,5 +107,35 @@ def convert_markdown_title(app, docname, source):
103107
# after the user's last visit.
104108
source[0] = re.sub(r"^% (.*)\s(\d)", r"```{title} \g<1>\n```", source[0])
105109

110+
111+
class APIVersionsDirective(Directive):
112+
"""
113+
Custom directive to generate a bullet list from the versions defined in _static/versions.json.
114+
115+
Usage in RST:
116+
.. api-versions::
117+
"""
118+
required_arguments = 0
119+
has_content = False
120+
121+
def run(self):
122+
env = self.state.document.settings.env
123+
json_file = f"{env.app.confdir}/_static/versions.json"
124+
125+
with open(json_file, "r") as f:
126+
versions = json.load(f)
127+
128+
bullet_list = nodes.bullet_list()
129+
130+
for version in versions:
131+
list_item = nodes.list_item()
132+
paragraph = nodes.paragraph()
133+
paragraph += nodes.reference("", f"version {version}", refuri=f"_static/api.html?version=v{version}")
134+
list_item += paragraph
135+
bullet_list += list_item
136+
137+
return [bullet_list]
138+
106139
def setup(app):
140+
app.add_directive("api-versions", APIVersionsDirective)
107141
app.connect("source-read", convert_markdown_title)

0 commit comments

Comments
 (0)