Skip to content

Commit cf3c166

Browse files
OriolAbrilOriolAbril
authored
0.16 updates: improve search and navbar icons (#5)
* 0.16 updates: improve search and navbar icons * fix link to search page * 0.16.1 breaks the right sidebar * try javascript from rtd docs * add theme features to readme
1 parent ce57216 commit cf3c166

File tree

13 files changed

+187
-17
lines changed

13 files changed

+187
-17
lines changed

‎README.md‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,27 @@
11
# pymc-sphinx-theme
22

3-
A thin sphinx theme to customize pydata-sphinx-theme consistently cross PyMC websites.
3+
A thin sphinx theme to customize [pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io) (PST) consistently cross PyMC websites.
4+
5+
## Theme customizations
6+
7+
### Custom search page
8+
PyMC docs are organized as subprojects in readthedocs. The custom search page shows two
9+
search bars, one that triggers the readthedocs search function of the parent project
10+
and that allows searching accross subprojects, and the PST one for local search
11+
within that particular project only.
12+
13+
![Search page with two search bars](./screenshots/double_search_bar.png)
14+
15+
![Flyout of the global readthedocs search](./screenshots/global_rtd_search.png)
16+
17+
### Centralize navbar customization
18+
The version indicator by the logo/project name is added as well as the mastodon, twitter,
19+
youtube and discord icon links. If no icon links are provided by the specific project,
20+
an extra link to the GitHub org is added, otherwise the project provided links are extended
21+
with the four mentioned.
22+
23+
### Extra right sidebar elements
24+
An extra "Support PyMC" link to the NumFOCUS donation page is automatically added,
25+
and the template of the "Edit on GitHub" link is modified so it is not shown in API pages that
26+
are generated from a docstring. The logic of this exclusion is extremely simple, as we use
27+
`:toctree: generated/` as autosummary option, pages with "generated" in their path are excluded.

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ classifiers = [
2424
]
2525
dynamic = ["version", "description"]
2626
dependencies = [
27-
"pydata-sphinx-theme>=0.15.0,<0.16",
27+
"pydata-sphinx-theme>=0.16.0,<0.17,!=0.16.1",
2828
"sphinx>=5",
2929
]
3030

‎screenshots/double_search_bar.png‎

22.7 KB
Loading

‎screenshots/global_rtd_search.png‎

66.5 KB
Loading

‎src/pymc_sphinx_theme/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
"""A thin sphinx theme to customize pydata-sphinx-theme consistently cross PyMC websites."""
22

3-
__version__ = "0.15.0"
3+
__version__ = "0.16.0"
44

55
from pathlib import Path
66

‎src/pymc_sphinx_theme/components/pymc_icon_links.html‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
1+
{%- set pymc_icon_links = [
2+
{ "url": "https://bayes.club/@pymc", "icon": "fa-brands fa-mastodon", "name": "Mastodon" },
3+
{ "url": "https://twitter.com/pymc_devs/", "icon": "fa-brands fa-twitter", "name": "Twitter" },
4+
{ "url": "https://www.youtube.com/c/PyMCDevelopers", "icon": "fa-brands fa-youtube", "name": "YouTube" },
5+
{ "url": "https://discourse.pymc.io", "icon": "fa-brands fa-discourse", "name": "Discourse" },
6+
] -%}
17
{%- if not theme_icon_links -%}
2-
{%- set theme_icon_links = [
3-
{ "url": "https://github.com/pymc-devs", "icon": "fa-brands fa-github", "name": "GitHub" },
4-
{ "url": "https://bayes.club/@pymc", "icon": "fa-brands fa-mastodon", "name": "Mastodon" },
5-
{ "url": "https://twitter.com/pymc_devs/", "icon": "fa-brands fa-twitter", "name": "Twitter" },
6-
{ "url": "https://www.youtube.com/c/PyMCDevelopers", "icon": "fa-brands fa-youtube", "name": "YouTube" },
7-
{ "url": "https://discourse.pymc.io", "icon": "fa-brands fa-discourse", "name": "Discourse" },
8-
] -%}
8+
{%- set theme_icon_links = [{ "url": "https://github.com/pymc-devs", "icon": "fa-brands fa-github", "name": "GitHub" }] + pymc_icon_links -%}
9+
{%- else -%}
10+
{%- set theme_icon_links = theme_icon_links + pymc_icon_links -%}
911
{%- endif -%}
1012
{% extends "navbar-icon-links.html" %}

‎src/pymc_sphinx_theme/components/search-button.html‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<div>
2+
<a class="nav-link pst-navbar-icon" href="{{ pathto('search.html', 1) }}">
3+
<i class="fa-solid fa-magnifying-glass fa-lg"></i>
4+
</a>
5+
</div>

‎src/pymc_sphinx_theme/components/search-field.html‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,9 @@
11
{# A bootstrap-styled field that will direct to the `search.html` page when submitted #}
22
{# It is copied over from pydata-sphinx-theme to hijack the search bar in readthedocs subprojects to search over all subprojects like in main website #}
33

4-
{% if theme_use_search_override %}
5-
<form class="bd-search d-flex align-items-center"
6-
action="https://www.pymc.io/search.html"
7-
method="get">
8-
{% else %}
94
<form class="bd-search d-flex align-items-center"
105
action="{{ pathto('search') }}"
116
method="get">
12-
{% endif %}
137
<i class="fa-solid fa-magnifying-glass"></i>
148
<input type="search"
159
class="form-control"
@@ -21,5 +15,5 @@
2115
autocorrect="off"
2216
autocapitalize="off"
2317
spellcheck="false"/>
24-
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span>
18+
<span class="search-button__kbd-shortcut">Local&nbsp;search</span>
2519
</form>

‎src/pymc_sphinx_theme/layout.html‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{%- extends "pydata_sphinx_theme/layout.html" %}
2+
{%- block extrahead %}
3+
{{ super() }}
4+
{% if pagename == 'search' %}
5+
<script src="{{ pathto('_static/js/readthedocs.js', 1) }}"></script>
6+
{% endif %}
7+
{%- endblock extrahead %}

‎src/pymc_sphinx_theme/search.html‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
{%- extends "pydata_sphinx_theme/search.html" %}
2+
3+
{% block docs_body %}
4+
<div class="bd-search-container">
5+
<h1>{{ _("Search") }}</h1>
6+
<noscript>
7+
<div class="admonition error">
8+
<p class="admonition-title">{% trans %}Error{% endtrans %}</p>
9+
<p>{% trans %}Please activate JavaScript to enable the search functionality.{% endtrans %}</p>
10+
</div>
11+
</noscript>
12+
{% if theme_use_search_override %}
13+
<form class="global-search d-flex align-items-center"
14+
{% if github_repo == "pymc.io" %}
15+
action=""
16+
{% else %}
17+
action="https://www.pymc.io/search.html"
18+
{% endif %}
19+
method="get">
20+
<i class="fa-solid fa-magnifying-glass"></i>
21+
<input type="global-search"
22+
class="form-control"
23+
name="q"
24+
id="search-input-global"
25+
placeholder="Search across all PyMC sites..."
26+
aria-label="Search across all PyMC sites"
27+
autocomplete="off"
28+
autocorrect="off"
29+
autocapitalize="off"
30+
spellcheck="false"/>
31+
<span class="search-button__kbd-shortcut">Global&nbsp;search</span>
32+
</form>
33+
{% endif %}
34+
<br>
35+
{% include "../components/search-field.html" %}
36+
<div id="search-results"></div>
37+
</div>
38+
<script>
39+
// Activate the search field on page load
40+
let searchInput = document.querySelector("form.bd-search input");
41+
if (searchInput) {
42+
searchInput.focus();
43+
searchInput.select();
44+
console.log("[PST]: Set focus on search field.");
45+
}
46+
</script>
47+
{% endblock docs_body %}

0 commit comments

Comments
 (0)