Skip to content

Commit a046547

Browse files
vpratzvpratz
committed
docs: polyversion, WIP
1 parent f2b9791 commit a046547

File tree

7 files changed

+268
-3
lines changed

7 files changed

+268
-3
lines changed

‎docsrc/Makefile‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
# You can set these variables from the command line, and also
55
# from the environment for the first two.
66
SPHINXOPTS ?=
7-
SPHINXBUILD ?= sphinx-build
7+
SPHINXBUILD ?= sphinx-multiversion
88
SOURCEDIR = source
99
BUILDDIR = _build
1010

@@ -22,7 +22,7 @@ github:
2222
@cp ../CONTRIBUTING.md source/contributing.md
2323
@cp -a ../examples/. source/_examples
2424
@rm -rf source/_examples/in_progress # ignore if in_progress does not exist
25-
@make html
25+
@$(SPHINXBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
2626
@echo 'Copying output from _build/html to ../docs.'
2727
@cp -a _build/html/. ../docs
2828
@cp .nojekyll ../docs/.nojekyll

‎docsrc/poly.py‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
from datetime import datetime
2+
from pathlib import Path
3+
4+
from sphinx_polyversion.api import apply_overrides
5+
from sphinx_polyversion.driver import DefaultDriver
6+
from sphinx_polyversion.git import Git, GitRef, GitRefType, file_predicate, refs_by_type
7+
from sphinx_polyversion.pyvenv import Pip
8+
from sphinx_polyversion.sphinx import SphinxBuilder
9+
10+
#: Regex matching the branches to build docs for
11+
BRANCH_REGEX = r"master-doctest"
12+
13+
#: Regex matching the tags to build docs for
14+
TAG_REGEX = r"v1.1.6"
15+
16+
#: Output dir relative to project root
17+
OUTPUT_DIR = "_polybuild"
18+
19+
#: Source directory
20+
SOURCE_DIR = "docsrc/"
21+
22+
#: Arguments to pass to `poetry install`
23+
POETRY_ARGS = "numpy"
24+
25+
#: Arguments to pass to `sphinx-build`
26+
SPHINX_ARGS = "-a -v"
27+
28+
#: Mock data used for building local version
29+
MOCK_DATA = {
30+
"revisions": [
31+
GitRef("v1.1.6", "", "", GitRefType.TAG, datetime.fromtimestamp(0)),
32+
GitRef("master-doctest", "", "", GitRefType.BRANCH, datetime.fromtimestamp(3)),
33+
],
34+
"current": GitRef("master-doctest", "", "", GitRefType.TAG, datetime.fromtimestamp(6)),
35+
}
36+
MOCK = True
37+
38+
39+
#: Data passed to templates
40+
def data(driver, rev, env):
41+
revisions = driver.targets
42+
branches, tags = refs_by_type(revisions)
43+
latest = max(tags or branches)
44+
return {
45+
"current": rev,
46+
"tags": tags,
47+
"branches": branches,
48+
"revisions": revisions,
49+
"latest": latest,
50+
}
51+
52+
53+
def root_data(driver):
54+
revisions = driver.builds
55+
branches, tags = refs_by_type(revisions)
56+
latest = max(tags or branches)
57+
return {"revisions": revisions, "latest": latest}
58+
59+
60+
# Load overrides read from commandline to global scope
61+
apply_overrides(globals())
62+
# Determine repository root directory
63+
root = Git.root(Path(__file__).parent)
64+
print("root", root)
65+
66+
# Setup driver and run it
67+
src = Path(SOURCE_DIR)
68+
DefaultDriver(
69+
root,
70+
OUTPUT_DIR,
71+
vcs=Git(
72+
branch_regex=BRANCH_REGEX,
73+
tag_regex=TAG_REGEX,
74+
buffer_size=1 * 10**9, # 1 GB
75+
predicate=file_predicate([src]), # exclude refs without source dir
76+
),
77+
builder=SphinxBuilder(src / "source", args=SPHINX_ARGS.split()),
78+
env=Pip.factory(args=POETRY_ARGS.split(), venv="buildvenv"),
79+
template_dir=root / src / "polyversion/templates",
80+
static_dir=root / src / "polyversion/static",
81+
data_factory=data,
82+
root_data_factory=root_data,
83+
mock=MOCK_DATA,
84+
).run(MOCK)

‎docsrc/polyversion/templates/index.html‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!doctype html>
2+
3+
<html>
4+
<head>
5+
<title>Redirecting to master branch</title>
6+
<meta charset="utf-8" />
7+
<meta
8+
http-equiv="refresh"
9+
content="0; url=./{{ latest.name }}/index.html"
10+
/>
11+
<link rel="canonical" href="./{{ latest.name }}/index.html" />
12+
</head>
13+
</html>

‎docsrc/source/_static/custom.css‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
/* Style our version picker
2+
3+
The version picker is defined in `_templates/versioning.html` and uses the same classes
4+
and ids as the one provided by the theme for use with readthedocs.io
5+
This allows us to load the styles by readthedocs as a basis
6+
and adjust them to our likings.
7+
*/
8+
9+
/* Import RTD styles */
10+
@import url("https://assets.readthedocs.org/static/css/readthedocs-doc-embed.css");
11+
@import url("https://assets.readthedocs.org/static/css/badge_only.css");
12+
13+
/* remove border around version picker */
14+
#furo-readthedocs-versions:focus-within,
15+
#furo-readthedocs-versions:hover {
16+
box-shadow: none;
17+
}
18+
19+
/* adjust the element showing the selected version */
20+
.rst-versions .rst-current-version {
21+
padding: var(--sidebar-item-spacing-vertical)
22+
var(--sidebar-item-spacing-horizontal);
23+
border-top: 1px solid var(--color-sidebar-search-border);
24+
color: var(--color-foreground-primary);
25+
}
26+
27+
/* .rst-versions .rst-current-version.rst-out-of-date {
28+
color: #c64334;
29+
}
30+
31+
.rst-versions .rst-current-version.rst-active-old-version {
32+
color: #634f00;
33+
} */
34+
35+
/* adjust the element listing all available versions */
36+
#furo-readthedocs-versions > .rst-other-versions {
37+
padding: var(--sidebar-item-spacing-vertical)
38+
var(--sidebar-item-spacing-horizontal);
39+
border-style: none;
40+
border-top: 1px solid var(--color-sidebar-search-border);
41+
}
42+
43+
/* adjust list headings */
44+
.rst-versions .rst-other-versions dt {
45+
color: var(--color-foreground-secondary);
46+
}
47+
48+
/* adjust selectable version items */
49+
.rst-versions .rst-other-versions dd a {
50+
color: var(--color-sidebar-link-text--top-level);
51+
padding-left: 0px;
52+
padding-right: 12px;
53+
}
54+
55+
/* adjust icons for the list headings */
56+
.bi.version-header {
57+
margin-right: 1ch;
58+
}
59+
60+
/* adjust icon for the version picker */
61+
.rst-current-version .bi-git {
62+
float: left;
63+
color: var(--color-foreground-primary);
64+
left: var(--sidebar-item-spacing-horizontal);
65+
}

‎docsrc/source/_templates/versioning.html‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<div
2+
class="rst-versions"
3+
data-toggle="rst-versions"
4+
role="note"
5+
aria-label="{{ _('Versions') }}"
6+
tabindex="0"
7+
>
8+
{# this element shows the current version and is visible by default It hides
9+
on hover while the element below becomes appears in its place. #}
10+
<span class="rst-current-version" data-toggle="rst-current-version">
11+
{# git icon indicating the version selector #}
12+
<i class="bi bi-git"></i>
13+
{# show current version; prepend `v` in case of branches #} {% if not
14+
current or not current.name.startswith("v") %} v: {% endif %} {{
15+
current.name if current else "undefined" }}
16+
</span>
17+
{% if revisions %} {# This item lists the avaible versions grouped into
18+
branches and tags. The item is hidden by default but appears when the user
19+
hovers over the version selector. #}
20+
<div class="rst-other-versions">
21+
{% if tags %} {# List of tags #}
22+
<dl>
23+
<dt>
24+
<i class="bi bi-tags-fill version-header"></i>{{ _('Tags') }}
25+
</dt>
26+
{% for item in tags %}
27+
<dd><a href="../{{ item.name }}/index.html" {% if current and current.name == item.name %}class="current"{%endif%}>{{ item.name }}</a></dd>
28+
{% endfor %}
29+
</dl>
30+
{% endif %} {% if branches %} {# List of branches #}
31+
<dl>
32+
<dt><i class="bi bi-git version-header"></i>{{ _('Branches') }}</dt>
33+
{% for item in branches %}
34+
{% if current and current.name == item.name %}Huhu{% endif %}
35+
<dd><a href="../{{ item.name }}/index.html" {% if current and current.name == item.name %}class="current"{% endif %}>{{ item.name }}</a></dd>
36+
{% endfor %}
37+
</dl>
38+
{% endif %}
39+
</div>
40+
{% endif %}
41+
</div>

‎docsrc/source/conf.py‎

Lines changed: 63 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@
1111
# documentation root, use os.path.abspath to make it absolute, like shown here.
1212
import os
1313
import sys
14+
import shutil
15+
from sphinx_polyversion import load
16+
from sphinx_polyversion.git import GitRef
1417

1518
sys.path.insert(0, os.path.abspath("../.."))
1619

@@ -87,7 +90,8 @@
8790
# Add any paths that contain custom _static files (such as style sheets) here,
8891
# relative to this directory. They are copied after the builtin _static files,
8992
# so a file named "default.css" will overwrite the builtin "default.css".
90-
# html_static_path = ["css/custom.css"]
93+
html_static_path = ["_static"]
94+
html_css_files = ["custom.css"]
9195
html_show_sourcelink = False
9296
html_theme_options = {
9397
"repository_url": "https://github.com/bayesflow-org/bayesflow",
@@ -102,6 +106,15 @@
102106
html_favicon = "_static/bayesflow_hex.ico"
103107
html_baseurl = "https://www.bayesflow.org/"
104108
html_js_files = ["https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"]
109+
html_sidebars = {
110+
"**": [
111+
"navbar-logo.html",
112+
"icon-links.html",
113+
"search-button-field.html",
114+
"sbt-sidebar-nav.html",
115+
"versioning.html",
116+
],
117+
}
105118

106119
todo_include_todos = True
107120

@@ -120,3 +133,52 @@
120133
remove_from_toctrees = ["_autosummary/*"]
121134

122135
autosummmary_generate = True
136+
137+
# sphinx-multiversion: select tags, branches and remotes
138+
smv_tag_whitelist = r"^(v1.1.6)$"
139+
# smv_branch_whitelist = r"^(|doc-autosummary|master|dev)$"
140+
smv_branch_whitelist = r"^(master)$"
141+
smv_remote_whitelist = None
142+
143+
144+
# move files around if necessary
145+
def copy_files_handler(app, config):
146+
print("TODO")
147+
return
148+
current_version = config["smv_current_version"]
149+
current_metadata = config["smv_metadata"][current_version]
150+
basedir = current_metadata["basedir"]
151+
sourcedir = current_metadata["sourcedir"]
152+
153+
print("Current version:", current_version)
154+
print("Basedir:", basedir)
155+
print("Metadata:", current_metadata)
156+
157+
examples_src = os.path.join(basedir, "examples")
158+
examples_dst = os.path.join(sourcedir, "_examples")
159+
if os.path.exists(examples_src):
160+
shutil.copytree(examples_src, examples_dst, dirs_exist_ok=True)
161+
examples_in_progress = os.path.join(examples_dst, "in_progress")
162+
if os.path.exists(examples_in_progress):
163+
shutil.rmtree(examples_in_progress)
164+
contributing_src = os.path.join(basedir, "CONTRIBUTING.md")
165+
contributing_dst = os.path.join(sourcedir, "contributing.md")
166+
if os.path.exists(contributing_src):
167+
shutil.copy2(contributing_src, contributing_dst)
168+
installation_src = os.path.join(basedir, "INSTALL.rst")
169+
installation_dst = os.path.join(sourcedir, "installation.rst")
170+
if os.path.exists(installation_src):
171+
shutil.copy2(installation_src, installation_dst)
172+
173+
174+
def cleanup_handler(app, exception):
175+
print("Done, what now?")
176+
177+
178+
def setup(app):
179+
app.connect("config-inited", copy_files_handler)
180+
app.connect("build-finished", cleanup_handler)
181+
182+
183+
data = load(globals())
184+
current: GitRef = data["current"]

‎docsrc/source/css/custom.css‎

Whitespace-only changes.

0 commit comments

Comments
 (0)