Skip to content

Commit 251a6f8

Browse files
committed
Allow making site links server-absolute
... instead of globally absolute with an explicit server name. This allows the docs to be served from a different server (e.g., on localhost), without links leaking out to the real matplotlib.org.
1 parent e9c6463 commit 251a6f8

File tree

4 files changed

+35
-35
lines changed

4 files changed

+35
-35
lines changed

docs/conf.py

+6-1
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,12 @@
4747
# and CI builds https://github.com/pydata/pydata-sphinx-theme/pull/386
4848
"collapse_navigation": not is_release_build,
4949
"show_prev_next": False,
50-
"native_site": False
50+
# Determines the type of links produced in the navigation header:
51+
# - absolute: Links point to the URL https://matplotlib.org/...
52+
# - relative: Links point to top-level of the server /...
53+
# - internal: Links point to the internal files as expanded by the `pathto`
54+
# template function in Sphinx.
55+
"navbar_links": "absolute",
5156
}
5257

5358
# Add any paths that contain custom static files (such as style sheets) here,

mpl_sphinx_theme/__init__.py

+21
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,30 @@ def get_html_theme_path():
88
return [str(Path(__file__).parent.parent.resolve())]
99

1010

11+
def setup_html_page_context(app, pagename, templatename, context, doctree):
12+
"""Add a mpl_path template function."""
13+
navbar_links = context['theme_navbar_links']
14+
if navbar_links not in ['internal', 'absolute', 'relative']:
15+
raise ValueError(f'Invalid navbar_links theme option: {navbar_links}')
16+
17+
def mpl_path(path):
18+
if navbar_links == 'internal':
19+
pathto = context['pathto']
20+
return pathto(path)
21+
elif navbar_links == 'absolute':
22+
return f'https://matplotlib.org/stable/{path}'
23+
elif navbar_links == 'relative':
24+
return f'/stable/{path}'
25+
else:
26+
raise ValueError(
27+
f'Invalid navbar_links theme option: {navbar_links}')
28+
context['mpl_path'] = mpl_path
29+
30+
1131
# For more details, see:
1232
# https://www.sphinx-doc.org/en/master/development/theming.html#distribute-your-theme-as-a-python-package
1333
def setup(app):
1434
app.add_html_theme("mpl_sphinx_theme",
1535
str(Path(__file__).parent.resolve()))
36+
app.connect("html-page-context", setup_html_page_context)
1637
return {'version': __version__, 'parallel_read_safe': True}

mpl_sphinx_theme/mpl_nav_bar.html

+7-33
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,23 @@
1-
{% if theme_native_site %}
21
<ul id="navbar-main-elements" class="navbar-nav">
32
<li class="nav-item">
4-
<a class="reference internal nav-link" href="{{ pathto('plot_types/index') }}">Plot types</a>
3+
<a class="reference internal nav-link" href="{{ mpl_path('plot_types/index') }}">Plot types</a>
54
</li>
65
<li class="nav-item">
7-
<a class="reference internal nav-link" href="{{ pathto('gallery/index') }}">Examples</a>
6+
<a class="reference internal nav-link" href="{{ mpl_path('gallery/index') }}">Examples</a>
87
</li>
98
<li class="nav-item">
10-
<a class="reference internal nav-link" href="{{ pathto('tutorials/index') }}">Tutorials</a>
9+
<a class="reference internal nav-link" href="{{ mpl_path('tutorials/index') }}">Tutorials</a>
1110
</li>
1211
<li class="nav-item">
13-
<a class="reference internal nav-link" href="{{ pathto('api/index') }}">Reference</a>
12+
<a class="reference internal nav-link" href="{{ mpl_path('api/index') }}">Reference</a>
1413
</li>
1514
<li class="nav-item">
16-
<a class="reference internal nav-link" href="{{ pathto('users/index') }}">User guide</a>
15+
<a class="reference internal nav-link" href="{{ mpl_path('users/index') }}">User guide</a>
1716
</li>
1817
<li class="nav-item">
19-
<a class="reference internal nav-link" href="{{ pathto('devel/index') }}">Develop</a>
18+
<a class="reference internal nav-link" href="{{ mpl_path('devel/index') }}">Develop</a>
2019
</li>
2120
<li class="nav-item">
22-
<a class="reference internal nav-link" href="{{ pathto('users/release_notes') }}">Release notes</a>
21+
<a class="reference internal nav-link" href="{{ mpl_path('users/release_notes') }}">Release notes</a>
2322
</li>
2423
</ul>
25-
{% else %}
26-
<ul id="navbar-main-elements" class="navbar-nav">
27-
<li class="nav-item">
28-
<a class="reference internal nav-link" href="https://matplotlib.org/stable/plot_types/index">Plot types</a>
29-
</li>
30-
<li class="nav-item">
31-
<a class="reference internal nav-link" href="https://matplotlib.org/stable/gallery/index">Examples</a>
32-
</li>
33-
<li class="nav-item">
34-
<a class="reference internal nav-link" href="https://matplotlib.org/stable/tutorials/index">Tutorials</a>
35-
</li>
36-
<li class="nav-item">
37-
<a class="reference internal nav-link" href="https://matplotlib.org/stable/api/index">Reference</a>
38-
</li>
39-
<li class="nav-item">
40-
<a class="reference internal nav-link" href="https://matplotlib.org/stable/users/index">Usage guide</a>
41-
</li>
42-
<li class="nav-item">
43-
<a class="reference internal nav-link" href="https://matplotlib.org/stable/devel/index">Develop</a>
44-
</li>
45-
<li class="nav-item">
46-
<a class="reference internal nav-link" href="https://matplotlib.org/stable/users/release_notes">Release notes</a>
47-
</li>
48-
</ul>
49-
{% endif %}

mpl_sphinx_theme/theme.conf

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ inherit = pydata_sphinx_theme
33
stylesheet = css/style.css
44

55
[options]
6-
native_site = False
6+
navbar_links = absolute
77
navbar_start = mpl_navbar_logo.html
88
navbar_center = mpl_nav_bar.html
99
navbar_end = mpl_icon_links.html

0 commit comments

Comments
 (0)