Skip to content

Commit d49d0ed

Browse files
sighingnowsighingnow
authored
docs: update rst-versions style, defaults default version to latest, and fixes the zh/en indexing (#2803)
Signed-off-by: Tao He <[email protected]>
1 parent 9efd4f6 commit d49d0ed

File tree

9 files changed

+131
-82
lines changed

9 files changed

+131
-82
lines changed

‎docs/_static/css/custom.css‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ body {
1212
}
1313

1414
.sidebar-scroll {
15-
margin-bottom: 175px;
15+
margin-bottom: 200px;
1616
}
1717

1818
.fa.fa-2x {

‎docs/_static/css/rst-versions.css‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,15 +15,17 @@
1515
}
1616

1717
.rst-versions-ver {
18-
bottom: 128px !important;
18+
/* bottom: 128px !important; */
19+
bottom: 100px !important;
1920
}
2021

2122
.rst-versions.rst-versions-ver .rst-current-version {
2223
padding: 10px 0 12px 10px;
2324
}
2425

2526
.rst-versions-lang {
26-
height: 128px !important;
27+
/* height: 128px !important; */
28+
bottom: 1rem !important;;
2729
}
2830

2931
.rst-versions {
@@ -133,7 +135,7 @@
133135

134136
.rst-versions .rst-other-versions {
135137
font-size: 90%;
136-
padding: 12px;
138+
padding: 0 12px 0 12px;
137139
color: gray;
138140
display: none;
139141
}
@@ -147,9 +149,13 @@
147149
border-top: solid 1px #413d3d
148150
}
149151

152+
.rst-versions .rst-other-versions dl {
153+
margin: 0;
154+
}
155+
150156
.rst-versions .rst-other-versions dd {
151157
display: inline-block;
152-
margin: 0
158+
margin: 0;
153159
}
154160

155161
.rst-versions .rst-other-versions dd a {

‎docs/_static/js/.gitkeep‎

Whitespace-only changes.

‎docs/_static/js/readthedocs-doc-embed.js‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎docs/_static/js/readthedocs.js‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎docs/_templates/sidebar/rtd-versions.html‎

Lines changed: 59 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,85 @@
11
{# Add rst-badge after rst-versions for small badge style. #}
22
{% if READTHEDOCS %}
3-
<div class="rst-versions rst-versions-ver" data-toggle="rst-versions" role="note" aria-label="versions">
4-
<span class="rst-current-version" data-toggle="rst-current-version">
5-
<span class="fa fa-book"> Read the Docs</span>
6-
v: {{ version }}
7-
<span class="fa fa-caret-down"></span>
8-
</span>
3+
<div class="rst-versions rst-versions-ver shift-up" role="note" aria-label="versions">
94
<div class="rst-other-versions">
5+
<hr />
106
<dl>
11-
<dt>{{ _('Versions') }}</dt>
7+
<dt><span class="fa fa-book">{{ _('Versions') }}</span></dt>
128
{% for ver in versions %}
139
{% if ver == "stable" %}
1410
{% if version == "stable" %}
1511
{% if 'zh' in pagename %}
16-
<dd><a href="{{ pathto('zh/index.html', 1) }}">{{ ver }}</a></dd>
12+
<dd><a href="{{ pathto('zh/index.html', 1) }}">
13+
{% if version == ver %}
14+
<strong><em>{{ ver }}</em></strong>
15+
{% else %}
16+
{{ ver }}
17+
{% endif %}
18+
</a></dd>
1719
{% else %}
18-
<dd><a href="{{ pathto('index.html', 1) }}">{{ ver }}</a></dd>
20+
<dd><a href="{{ pathto('index.html', 1) }}">
21+
{% if version == ver %}
22+
<strong><em>{{ ver }}</em></strong>
23+
{% else %}
24+
{{ ver }}
25+
{% endif %}
26+
</a></dd>
1927
{% endif %}
2028
{% else %}
2129
{% if 'zh' in pagename %}
22-
<dd><a href="../../{{ concat_path(pathto('zh/index.html', 1), 'zh') }}/index.html">{{ ver }}</a></dd>
30+
<dd><a href="../../{{ concat_path(pathto('zh/index.html', 1), 'zh') }}/index.html">
31+
{% if version == ver %}
32+
<strong><em>{{ ver }}</em></strong>
33+
{% else %}
34+
{{ ver }}
35+
{% endif %}
36+
</a></dd>
2337
{% else %}
24-
<dd><a href="../{{ pathto('index.html', 1) }}">{{ ver }}</a></dd>
38+
<dd><a href="../{{ pathto('index.html', 1) }}">
39+
{% if version == ver %}
40+
<strong><em>{{ ver }}</em></strong>
41+
{% else %}
42+
{{ ver }}
43+
{% endif %}
44+
</a></dd>
2545
{% endif %}
2646
{% endif %}
27-
2847
{% else %}
29-
3048
{% if version == "stable" %}
3149
{% if 'zh' in pagename %}
32-
<dd><a href="../{{ concat_path(pathto('zh/index.html', 1), ver) }}/zh/index.html">{{ ver }}</a></dd>
50+
<dd><a href="../{{ concat_path(pathto('zh/index.html', 1), ver) }}/zh/index.html">
51+
{% if version == ver %}
52+
<strong><em>{{ ver }}</em></strong>
53+
{% else %}
54+
{{ ver }}
55+
{% endif %}
56+
</a></dd>
3357
{% else %}
34-
<dd><a href="{{ concat_path(pathto('index.html', 1), ver) }}/index.html">{{ ver }}</a></dd>
58+
<dd><a href="{{ concat_path(pathto('index.html', 1), ver) }}/index.html">
59+
{% if version == ver %}
60+
<strong><em>{{ ver }}</em></strong>
61+
{% else %}
62+
{{ ver }}
63+
{% endif %}
64+
</a></dd>
3565
{% endif %}
3666
{% else %}
3767
{% if 'zh' in pagename %}
38-
<dd><a href="../../{{ concat_path(pathto('zh/index.html', 1), ver) }}/zh/index.html">{{ ver }}</a></dd>
68+
<dd><a href="../../{{ concat_path(pathto('zh/index.html', 1), ver) }}/zh/index.html">
69+
{% if version == ver %}
70+
<strong><em>{{ ver }}</em></strong>
71+
{% else %}
72+
{{ ver }}
73+
{% endif %}
74+
</a></dd>
3975
{% else %}
40-
<dd><a href="../{{ concat_path(pathto('index.html', 1), ver) }}/index.html">{{ ver }}</a></dd>
76+
<dd><a href="../{{ concat_path(pathto('index.html', 1), ver) }}/index.html">
77+
{% if version == ver %}
78+
<strong><em>{{ ver }}</em></strong>
79+
{% else %}
80+
{{ ver }}
81+
{% endif %}
82+
</a></dd>
4183
{% endif %}
4284
{% endif %}
4385
{% endif %}

‎docs/conf.py‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -136,15 +136,9 @@
136136
html_logo = "images/logo-h.png"
137137

138138
html_js_files = [
139-
"js/readthedocs.js",
140-
"js/readthedocs-doc-embed.js",
141139
]
142140

143141
html_css_files = [
144-
# "css/brands.min.css", # font-awesome
145-
# "css/regular.min.css", # font-awesome
146-
# "css/solid.min.css", # font-awesome
147-
# "css/fontawesome.min.css", # font-awesome
148142
"css/custom.css",
149143
"css/panels.css",
150144
"css/rst-versions.css",

‎docs/index.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,6 @@ and the vineyard store that offers efficient in-memory data transfers.
108108
development/how_to_test
109109
.. development/how_to_debug
110110
development/how_to_contribute
111-
112111

113112
.. toctree::
114113
:maxdepth: 1

‎docs/sphinx_ext.py‎

Lines changed: 61 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -19,33 +19,41 @@
1919
import os
2020
import shutil
2121
import subprocess
22+
from typing import Dict, Any, List
2223

2324
import sphinx
25+
import sphinx.application
2426
from sphinx import addnodes
25-
from sphinx.builders.html import StandaloneHTMLBuilder
2627
from sphinx.environment.adapters.toctree import TocTree
2728

29+
from furo.navigation import get_navigation_tree
2830

29-
def resolve_git_tags():
31+
32+
def resolve_git_tags(maximum_recent_versions=4):
33+
git = shutil.which("git")
34+
if git is None:
35+
return "latest", []
3036
try:
3137
head = subprocess.check_output(
32-
[shutil.which("git"), "describe", "--exact-match", "--tags", "HEAD"],
38+
[git, "describe", "--exact-match", "--tags", "HEAD"],
3339
stderr=subprocess.DEVNULL,
3440
)
3541
head = head.decode("utf-8", errors="ignore").strip()
3642
except:
3743
head = "latest"
3844
releases = (
39-
subprocess.check_output(
40-
[shutil.which("git"), "tag", "--list", "--sort=-creatordate"]
41-
)
45+
subprocess.check_output([git, "tag", "--list", "--sort=-creatordate"])
4246
.decode("utf-8", errors="ignore")
4347
.strip()
4448
.split()
4549
)
50+
releases = [r for r in releases if r.startswith("v")][0:maximum_recent_versions]
4651
return head, releases
4752

4853

54+
current_version, releases = resolve_git_tags()
55+
56+
4957
def concat_path(page, base):
5058
if "/" in page:
5159
return page[: (page.rfind("/") + 1)] + base
@@ -79,41 +87,51 @@ def get_local_toctree_for(self, master_doc, docname, builder, collapse, **kwargs
7987
return result
8088

8189

82-
class StandaloneHTMLBuilderExt(StandaloneHTMLBuilder):
83-
"""Extend the standard `StandaloneHTMLBuilder` with a `toctree_for` derivate in
84-
context to creating toctrees for zh_CN documentations.
85-
"""
86-
87-
def _get_local_toctree_ext(self, master_doc, pagename, collapse, **kwargs):
88-
if "includehidden" not in kwargs:
89-
kwargs["includehidden"] = False
90-
if kwargs.get("maxdepth") == "":
91-
kwargs.pop("maxdepth")
92-
return self.render_partial(
93-
TocTreeExt(self.env).get_local_toctree_for(
94-
master_doc, pagename, self, collapse, **kwargs
95-
)
96-
)["fragment"]
97-
98-
def handle_page(self, pagename, *args, **kwargs):
99-
version, releases = resolve_git_tags()
100-
if os.environ.get("TAG_VER", None) == "stable":
101-
version = "stable"
102-
self.globalcontext["version"] = version
103-
# self.globalcontext['stable'] = releases[0]
104-
self.globalcontext["versions"] = ["latest", "stable"] + releases
105-
106-
self.globalcontext["concat_path"] = concat_path
107-
self.globalcontext[
108-
"toctree_for"
109-
] = lambda master_doc, **kwargs: self._get_local_toctree_ext(
110-
master_doc, pagename, **kwargs
111-
)
112-
return super(StandaloneHTMLBuilderExt, self).handle_page(
113-
pagename, *args, **kwargs
90+
def _compute_navigation_tree(
91+
app: sphinx.application.Sphinx, pagename: str, context: Dict[str, Any]
92+
) -> str:
93+
toctree = TocTreeExt(app.builder.env)
94+
if "zh" in pagename:
95+
master_doc = "zh/index"
96+
else:
97+
master_doc = "index"
98+
toctree_html = app.builder.render_partial(
99+
toctree.get_local_toctree_for(
100+
master_doc,
101+
docname=pagename,
102+
builder=app.builder,
103+
collapse=False,
104+
titles_only=True,
105+
maxdepth=-1,
106+
includehidden=False,
114107
)
115-
116-
117-
def setup(app):
118-
app.add_builder(StandaloneHTMLBuilderExt, override=True)
119-
return {"version": sphinx.__display_version__, "parallel_read_safe": True}
108+
)["fragment"]
109+
return get_navigation_tree(toctree_html)
110+
111+
112+
def _html_page_context(
113+
app: sphinx.application.Sphinx,
114+
pagename: str,
115+
templatename: str,
116+
context: Dict[str, Any],
117+
doctree: Any,
118+
):
119+
version = current_version
120+
if os.environ.get("TAG_VER", None) == "stable":
121+
version = "stable"
122+
context["version"] = version
123+
context["stable"] = releases[0]
124+
context["versions"] = ["latest", "stable"] + releases
125+
context["concat_path"] = concat_path
126+
127+
# customize toctree for en/zh_CN docs
128+
context["furo_navigation_tree"] = _compute_navigation_tree(app, pagename, context)
129+
130+
131+
def setup(app: sphinx.application.Sphinx) -> Dict[str, Any]:
132+
app.connect("html-page-context", _html_page_context, priority=1000)
133+
return {
134+
"version": sphinx.__display_version__,
135+
"parallel_read_safe": True,
136+
"parallel_write_safe": True,
137+
}

0 commit comments

Comments
 (0)