Skip to content

Commit

Permalink
docs: update rst-versions style, defaults default version to latest, …
Browse files Browse the repository at this point in the history 
…and fixes the zh/en indexing (#2803)

Signed-off-by: Tao He <linzhu.ht@alibaba-inc.com>
  • Loading branch information
@sighingnow
sighingnow committed Jun 5, 2023
1 parent 9efd4f6 commit d49d0ed
Show file tree
Hide file tree
Showing 9 changed files with 131 additions and 82 deletions.
2 changes: 1 addition & 1 deletion docs/_static/css/custom.css
View file
Expand Up @@ -12,7 +12,7 @@ body {
}

.sidebar-scroll {
margin-bottom: 175px;
margin-bottom: 200px;
}

.fa.fa-2x {
Expand Down
14 changes: 10 additions & 4 deletions docs/_static/css/rst-versions.css
View file
Expand Up @@ -15,15 +15,17 @@
}

.rst-versions-ver {
bottom: 128px !important;
/* bottom: 128px !important; */
bottom: 100px !important;
}

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

.rst-versions-lang {
height: 128px !important;
/* height: 128px !important; */
bottom: 1rem !important;;
}

.rst-versions {
Expand Down Expand Up @@ -133,7 +135,7 @@

.rst-versions .rst-other-versions {
font-size: 90%;
padding: 12px;
padding: 0 12px 0 12px;
color: gray;
display: none;
}
Expand All @@ -147,9 +149,13 @@
border-top: solid 1px #413d3d
}

.rst-versions .rst-other-versions dl {
margin: 0;
}

.rst-versions .rst-other-versions dd {
display: inline-block;
margin: 0
margin: 0;
}

.rst-versions .rst-other-versions dd a {
Expand Down
Empty file added docs/_static/js/.gitkeep
View file
Empty file.
1 change: 0 additions & 1 deletion docs/_static/js/readthedocs-doc-embed.js
View file

This file was deleted.

9 changes: 0 additions & 9 deletions docs/_static/js/readthedocs.js
View file

This file was deleted.

76 changes: 59 additions & 17 deletions docs/_templates/sidebar/rtd-versions.html
View file
@@ -1,43 +1,85 @@
{# Add rst-badge after rst-versions for small badge style. #}
{% if READTHEDOCS %}
<div class="rst-versions rst-versions-ver" data-toggle="rst-versions" role="note" aria-label="versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<span class="fa fa-book"> Read the Docs</span>
v: {{ version }}
<span class="fa fa-caret-down"></span>
</span>
<div class="rst-versions rst-versions-ver shift-up" role="note" aria-label="versions">
<div class="rst-other-versions">
<hr />
<dl>
<dt>{{ _('Versions') }}</dt>
<dt><span class="fa fa-book">{{ _('Versions') }}</span></dt>
{% for ver in versions %}
{% if ver == "stable" %}
{% if version == "stable" %}
{% if 'zh' in pagename %}
<dd><a href="{{ pathto('zh/index.html', 1) }}">{{ ver }}</a></dd>
<dd><a href="{{ pathto('zh/index.html', 1) }}">
{% if version == ver %}
<strong><em>{{ ver }}</em></strong>
{% else %}
{{ ver }}
{% endif %}
</a></dd>
{% else %}
<dd><a href="{{ pathto('index.html', 1) }}">{{ ver }}</a></dd>
<dd><a href="{{ pathto('index.html', 1) }}">
{% if version == ver %}
<strong><em>{{ ver }}</em></strong>
{% else %}
{{ ver }}
{% endif %}
</a></dd>
{% endif %}
{% else %}
{% if 'zh' in pagename %}
<dd><a href="../../{{ concat_path(pathto('zh/index.html', 1), 'zh') }}/index.html">{{ ver }}</a></dd>
<dd><a href="../../{{ concat_path(pathto('zh/index.html', 1), 'zh') }}/index.html">
{% if version == ver %}
<strong><em>{{ ver }}</em></strong>
{% else %}
{{ ver }}
{% endif %}
</a></dd>
{% else %}
<dd><a href="../{{ pathto('index.html', 1) }}">{{ ver }}</a></dd>
<dd><a href="../{{ pathto('index.html', 1) }}">
{% if version == ver %}
<strong><em>{{ ver }}</em></strong>
{% else %}
{{ ver }}
{% endif %}
</a></dd>
{% endif %}
{% endif %}

{% else %}

{% if version == "stable" %}
{% if 'zh' in pagename %}
<dd><a href="../{{ concat_path(pathto('zh/index.html', 1), ver) }}/zh/index.html">{{ ver }}</a></dd>
<dd><a href="../{{ concat_path(pathto('zh/index.html', 1), ver) }}/zh/index.html">
{% if version == ver %}
<strong><em>{{ ver }}</em></strong>
{% else %}
{{ ver }}
{% endif %}
</a></dd>
{% else %}
<dd><a href="{{ concat_path(pathto('index.html', 1), ver) }}/index.html">{{ ver }}</a></dd>
<dd><a href="{{ concat_path(pathto('index.html', 1), ver) }}/index.html">
{% if version == ver %}
<strong><em>{{ ver }}</em></strong>
{% else %}
{{ ver }}
{% endif %}
</a></dd>
{% endif %}
{% else %}
{% if 'zh' in pagename %}
<dd><a href="../../{{ concat_path(pathto('zh/index.html', 1), ver) }}/zh/index.html">{{ ver }}</a></dd>
<dd><a href="../../{{ concat_path(pathto('zh/index.html', 1), ver) }}/zh/index.html">
{% if version == ver %}
<strong><em>{{ ver }}</em></strong>
{% else %}
{{ ver }}
{% endif %}
</a></dd>
{% else %}
<dd><a href="../{{ concat_path(pathto('index.html', 1), ver) }}/index.html">{{ ver }}</a></dd>
<dd><a href="../{{ concat_path(pathto('index.html', 1), ver) }}/index.html">
{% if version == ver %}
<strong><em>{{ ver }}</em></strong>
{% else %}
{{ ver }}
{% endif %}
</a></dd>
{% endif %}
{% endif %}
{% endif %}
Expand Down
6 changes: 0 additions & 6 deletions docs/conf.py
View file
Expand Up @@ -136,15 +136,9 @@
html_logo = "images/logo-h.png"

html_js_files = [
"js/readthedocs.js",
"js/readthedocs-doc-embed.js",
]

html_css_files = [
# "css/brands.min.css", # font-awesome
# "css/regular.min.css", # font-awesome
# "css/solid.min.css", # font-awesome
# "css/fontawesome.min.css", # font-awesome
"css/custom.css",
"css/panels.css",
"css/rst-versions.css",
Expand Down
1 change: 0 additions & 1 deletion docs/index.rst
View file
Expand Up @@ -108,7 +108,6 @@ and the vineyard store that offers efficient in-memory data transfers.
development/how_to_test
.. development/how_to_debug
development/how_to_contribute


.. toctree::
:maxdepth: 1
Expand Down
104 changes: 61 additions & 43 deletions docs/sphinx_ext.py
View file
Expand Up @@ -19,33 +19,41 @@
import os
import shutil
import subprocess
from typing import Dict, Any, List

import sphinx
import sphinx.application
from sphinx import addnodes
from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.environment.adapters.toctree import TocTree

from furo.navigation import get_navigation_tree

def resolve_git_tags():

def resolve_git_tags(maximum_recent_versions=4):
git = shutil.which("git")
if git is None:
return "latest", []
try:
head = subprocess.check_output(
[shutil.which("git"), "describe", "--exact-match", "--tags", "HEAD"],
[git, "describe", "--exact-match", "--tags", "HEAD"],
stderr=subprocess.DEVNULL,
)
head = head.decode("utf-8", errors="ignore").strip()
except:
head = "latest"
releases = (
subprocess.check_output(
[shutil.which("git"), "tag", "--list", "--sort=-creatordate"]
)
subprocess.check_output([git, "tag", "--list", "--sort=-creatordate"])
.decode("utf-8", errors="ignore")
.strip()
.split()
)
releases = [r for r in releases if r.startswith("v")][0:maximum_recent_versions]
return head, releases


current_version, releases = resolve_git_tags()


def concat_path(page, base):
if "/" in page:
return page[: (page.rfind("/") + 1)] + base
Expand Down Expand Up @@ -79,41 +87,51 @@ def get_local_toctree_for(self, master_doc, docname, builder, collapse, **kwargs
return result


class StandaloneHTMLBuilderExt(StandaloneHTMLBuilder):
"""Extend the standard `StandaloneHTMLBuilder` with a `toctree_for` derivate in
context to creating toctrees for zh_CN documentations.
"""

def _get_local_toctree_ext(self, master_doc, pagename, collapse, **kwargs):
if "includehidden" not in kwargs:
kwargs["includehidden"] = False
if kwargs.get("maxdepth") == "":
kwargs.pop("maxdepth")
return self.render_partial(
TocTreeExt(self.env).get_local_toctree_for(
master_doc, pagename, self, collapse, **kwargs
)
)["fragment"]

def handle_page(self, pagename, *args, **kwargs):
version, releases = resolve_git_tags()
if os.environ.get("TAG_VER", None) == "stable":
version = "stable"
self.globalcontext["version"] = version
# self.globalcontext['stable'] = releases[0]
self.globalcontext["versions"] = ["latest", "stable"] + releases

self.globalcontext["concat_path"] = concat_path
self.globalcontext[
"toctree_for"
] = lambda master_doc, **kwargs: self._get_local_toctree_ext(
master_doc, pagename, **kwargs
)
return super(StandaloneHTMLBuilderExt, self).handle_page(
pagename, *args, **kwargs
def _compute_navigation_tree(
app: sphinx.application.Sphinx, pagename: str, context: Dict[str, Any]
) -> str:
toctree = TocTreeExt(app.builder.env)
if "zh" in pagename:
master_doc = "zh/index"
else:
master_doc = "index"
toctree_html = app.builder.render_partial(
toctree.get_local_toctree_for(
master_doc,
docname=pagename,
builder=app.builder,
collapse=False,
titles_only=True,
maxdepth=-1,
includehidden=False,
)


def setup(app):
app.add_builder(StandaloneHTMLBuilderExt, override=True)
return {"version": sphinx.__display_version__, "parallel_read_safe": True}
)["fragment"]
return get_navigation_tree(toctree_html)


def _html_page_context(
app: sphinx.application.Sphinx,
pagename: str,
templatename: str,
context: Dict[str, Any],
doctree: Any,
):
version = current_version
if os.environ.get("TAG_VER", None) == "stable":
version = "stable"
context["version"] = version
context["stable"] = releases[0]
context["versions"] = ["latest", "stable"] + releases
context["concat_path"] = concat_path

# customize toctree for en/zh_CN docs
context["furo_navigation_tree"] = _compute_navigation_tree(app, pagename, context)


def setup(app: sphinx.application.Sphinx) -> Dict[str, Any]:
app.connect("html-page-context", _html_page_context, priority=1000)
return {
"version": sphinx.__display_version__,
"parallel_read_safe": True,
"parallel_write_safe": True,
}

0 comments on commit d49d0ed

Please sign in to comment.