Skip to content

Commit 6467254

Browse files
authored
Merge pull request #2974 from Unidata/dependabot-pip-ci-pydata-sphinx-theme-0.13.3
CI: (deps): Bump pydata-sphinx-theme from 0.8.1 to 0.13.3 in /ci
2 parents a044032 + 3a4b3f0 commit 6467254

File tree

12 files changed

+211
-239
lines changed

12 files changed

+211
-239
lines changed

CONTRIBUTING.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -212,6 +212,21 @@ Then, still from within your ``devel`` environment,
212212
* Remove any old builds and build the current docs ``make clean html``
213213
* Open ``docs/build/html/index.html`` and see your changes!
214214

215+
### `doc-server.py`
216+
217+
The MetPy documentation relies on the
218+
[Pydata Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html)
219+
for style and functionality.
220+
The theme includes some live javascript elements, including the version switcher.
221+
To test these elements, use our `doc-server.py` to deploy the built docs html files to a local
222+
server. If testing changes to `pst-versions.json` locally, change
223+
`html_theme_options['switcher']['json_url']` to reference `/MetPy/pst-versions.json` and the
224+
builds should pass and reflect any testing changes to `docs/test-server/pst-versions.json`.
225+
Documentation builds may fail if the links in the json fail to resolve.
226+
Change `html_theme_options['check_switcher']` to `False` in `conf.py` to bypass this behavior.
227+
Note: for production, `pst-versions.json` must live and is automatically updated on the online
228+
MetPy documentation via the `gh-pages` branch on GitHub.
229+
215230
## Tests
216231

217232
Unit tests are the lifeblood of the project, as it ensures that we can continue to add and

ci/doc_requirements.txt

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
1-
sphinx==4.5.0
2-
pydata-sphinx-theme==0.8.1
1+
sphinx==6.2.1
2+
pydata-sphinx-theme==0.13.3
3+
sphinx-design==0.4.1
34
sphinx-gallery==0.13.0
4-
myst-parser==0.18.1
5+
myst-parser==1.0.0
56
netCDF4==1.6.3
67
geopandas==0.13.0
78
rtree==1.0.1

docs/_static/doc_shared.js

Lines changed: 66 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,75 @@
11
const project = "MetPy";
22

3-
$(document).ready(function() {
4-
cur_ver = DOCUMENTATION_OPTIONS.VERSION;
5-
end = cur_ver.lastIndexOf('.');
6-
if (end > -1) {
7-
cur_ver = 'v' + cur_ver.substring(0, end);
8-
}
9-
console.log('cur_ver: ' + cur_ver);
10-
11-
$.getJSON('/' + project + '/versions.json', function(data) {
12-
if (cur_ver !== data.latest) {
13-
let msg;
14-
if (cur_ver.includes('dev') || data.prereleases.indexOf(cur_ver) > -1) {
15-
msg = 'development / pre-release';
16-
} else {
17-
msg = 'previous';
18-
}
19-
content = $('<div class="alert alert-secondary alert-version" role="alert">This documentation page is for a ' + msg +
20-
' version. For the latest release version, go to <a class="alert-link" href="https://unidata.github.io/MetPy/latest/">https://unidata.github.io/MetPy/latest/</a>');
21-
$('#banner').append(content);
3+
function documentReady(callback) {
4+
if (document.readyState != "loading") callback();
5+
else document.addEventListener("DOMContentLoaded", callback);
6+
}
7+
8+
documentReady(function () {
9+
// Use PST version metadata to match current doc version
10+
const cur_ver = DOCUMENTATION_OPTIONS.theme_switcher_version_match;
11+
console.log("cur_ver: " + cur_ver);
12+
13+
fetch("/" + project + "/pst-versions.json")
14+
.then(function (response) {
15+
return response.json();
16+
})
17+
.then(function (data) {
18+
// Find matching version entry in PST version list
19+
const entry = data[data.findIndex((obj) => obj.version == cur_ver)];
20+
21+
// Find out if matched version is latest
22+
// and construct alert message
23+
if (entry.is_latest != true) {
24+
let rel_type;
25+
if (cur_ver.includes("dev") || entry.is_prerelease == true) {
26+
rel_type = "development/pre-release";
27+
} else {
28+
rel_type = "previous";
2229
}
2330

24-
$.each(data.versions, function() {
25-
if (this !== 'latest') {
26-
const url = DOCUMENTATION_OPTIONS.URL_ROOT + '../' + this;
27-
const name = this.startsWith('v') ? this.substring(1) : this;
28-
$('#version-menu').append('<a class="dropdown-item" href="' + url + '">' + name + '</a>');
29-
}
30-
});
31+
let msg =
32+
`This documentation page is for a ${rel_type} version. For the latest release version, go to <a class="alert-link" href="https://unidata.github.io/MetPy/latest/">https://unidata.github.io/MetPy/latest/</a>`;
33+
34+
// Create alert div and fill with message content
35+
let content = document.createElement("div");
36+
content.classList.add("alert", "alert-secondary", "alert-version");
37+
content.setAttribute("role", "alert");
38+
content.innerHTML = msg;
39+
40+
// Append alert div to banner div under navbar
41+
document.querySelector("#banner").appendChild(content);
42+
} else {
43+
console.log("MetPy version latest.");
44+
}
45+
})
46+
.catch(function (err) {
47+
console.warn("Something went wrong.", err);
3148
});
3249
});
3350

34-
// Borrowed from Bokeh docs to look for a banner.html at the base of the docs repo and add that
35-
// to the banner if present.
36-
$(document).ready(function () {
37-
$.get('/' + project + '/banner.html', function (data) {
38-
if (data.length > 0) {
39-
console.log(data);
40-
$('#banner').prepend(data);
51+
documentReady(function () {
52+
fetch("/" + project + "/banner.html")
53+
.then(function (response) {
54+
return response.text();
55+
})
56+
.then(function (html) {
57+
// If any banner.html exists, parse it and add to banner div
58+
if (html.length > 0) {
59+
let parser = new DOMParser();
60+
let doc = parser.parseFromString(html.trim(), "text/html");
61+
62+
// Get all div elements from banner.html
63+
// and prepend them to banner div under navbar
64+
let divs = doc.getElementsByTagName("div");
65+
for (let div of divs) {
66+
document.querySelector("#banner").prepend(div);
4167
}
68+
} else {
69+
console.log("Banner empty.");
70+
}
4271
})
43-
})
72+
.catch(function (err) {
73+
return console.warn("Something went wrong.", err);
74+
});
75+
});

docs/_static/theme-unidata.css

Lines changed: 23 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,36 @@
1-
/* UCAR style heading towards use of Poppins font */
2-
.header-style, h1, h2, h3, h4, h5, h6 {
3-
font-family: Poppins, sans-serif;
4-
}
5-
6-
/* Unidata header color */
7-
.bg-unidata {
8-
background-color: #06778F;
1+
/* Define "Unidata Blue" RGB values */
2+
:root {
3+
--unidata-blue-rgb: 6, 119, 143;
94
}
105

11-
/* Override the default color set in the original theme */
12-
.navbar-nav>.active>.nav-link {
13-
color: #fff !important;
14-
font-weight: 400 !important;
15-
font-style: italic;
6+
/* Header and heading font style */
7+
.header-style, h1, h2, h3, h4, h5, h6 {
8+
font-family: Poppins, sans-serif;
169
}
1710

18-
.fa-github-square:before {
19-
color: rgba(255, 255, 255, 0.5) !important;
20-
font-weight: 400 !important;
11+
/* Header colors */
12+
.bd-header {
13+
background: rgb(var(--unidata-blue-rgb)) !important;
2114
}
2215

23-
.fa-twitter-square:before {
24-
color: rgba(255, 255, 255, 0.5) !important;
25-
font-weight: 400 !important;
16+
.theme-switch-button {
17+
border-color: rgb(var(--unidata-blue-rgb)) !important;
2618
}
2719

28-
/* Override the default logo height */
29-
.navbar-brand {
30-
height: 50px;
20+
.bd-header .navbar-nav>.nav-item>.nav-link,
21+
.bd-header .dropdown-toggle,
22+
.bd-header .fa-solid {
23+
color: #fff !important;
24+
}
25+
26+
.navbar-nav .dropdown-menu {
27+
background-color: var(--pst-color-background);
3128
}
3229

33-
/* Enhance the links to function docs in the gallery examples */
30+
/* Increase contrast of links in code snippets */
3431
div[class^="highlight"] a {
35-
background-color: #EEEEEE;
32+
background-color: rgb(var(--unidata-blue-rgb), 0.2);
33+
color: var(--pst-color-text-muted);
3634
}
3735

3836
/* Control the appearance of the version alert banner */
@@ -43,87 +41,12 @@ div[class^="highlight"] a {
4341
font-weight: 600; font-size: 16px;
4442
}
4543

46-
.intro-card {
47-
background: #d8e5e8;
48-
border: none;
49-
border-radius: 0;
50-
padding: 30px 10px 10px 10px;
51-
margin: 10px 0px;
52-
}
53-
54-
.intro-card .card-text {
55-
margin: 20px 0px;
56-
}
57-
58-
.card-button {
59-
background-color: #fafafa;
60-
border: none;
61-
color: #484848;
62-
text-align: center;
63-
text-decoration: none;
64-
display: inline-block;
65-
font-size: 0.9rem;
66-
border-radius: 0.5rem;
67-
max-width: 220px;
68-
padding: 0.5rem 0rem;
69-
margin-top: auto;
70-
}
71-
72-
.card-button a {
73-
color: #484848;
74-
}
75-
76-
.card-button p {
77-
margin-top: 0;
78-
margin-bottom: 0rem;
79-
color: #484848;
80-
}
81-
8244
/* Tweaks to the appearance of the sidebars */
8345
.bd-sidebar {
8446
flex: 0 0 20%;
8547
border-right: none;
8648
}
8749

88-
.bd-toc .tocsection {
89-
border-left: none;
90-
}
91-
92-
.bd-toc .section-nav {
50+
.bd-sidebar-secondary div {
9351
border-left: none;
9452
}
95-
96-
/* Can remove once theme releases new version */
97-
/* xarray output display in bootstrap */
98-
.xr-wrap[hidden] {
99-
display: block !important;
100-
}
101-
102-
.xr-var-data pre {
103-
border: none;
104-
box-shadow: none;
105-
}
106-
107-
108-
/* Styling the API Changes Table */
109-
.api-table tr:nth-child(3n + 1){
110-
background: #EEF5F5;
111-
}
112-
113-
.api-table tr:nth-child(3n + 2){
114-
opacity: 0.65;
115-
}
116-
117-
code.literal:not(.xref) span.pre {
118-
color: #000;
119-
}
120-
121-
.api-table tr:nth-child(3n + 2)>td span:first-child::before{
122-
content: url(old.png);
123-
zoom: 0.25;
124-
}
125-
126-
.api-table tr:nth-child(3n + 3)>td span:first-child::before{
127-
content: url(new.png);
128-
zoom: 0.21;
129-
}

docs/_templates/layout.html

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44
<style>
55
@import url('https://fonts.googleapis.com/css2?family=Poppins:ital,wght@0,400;0,600;0,700;1,400;1,600;1,700&display=swap');
66
</style>
7-
{{ super() }}
87
{% endblock %}
98

109
{% block extrahead %}
@@ -13,10 +12,7 @@
1312
{% endblock %}
1413

1514
{% block docs_navbar %}
16-
<nav class="navbar navbar-dark navbar-expand-lg bg-unidata fixed-top bd-navbar shadow" id="navbar-main">
17-
{%- include "docs-navbar.html" %}
18-
</nav>
19-
20-
{# Added to support a banner with an alert #}
15+
{{ super() }}
16+
{# Added to support a banner with an alert #}
2117
<div class="container-fluid" id="banner"></div>
2218
{% endblock %}

docs/_templates/versions.html

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

docs/conf.py

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@
4040
'sphinx.ext.mathjax',
4141
'sphinx.ext.napoleon',
4242
'sphinx.ext.viewcode',
43+
'sphinx_design',
4344
'sphinx_gallery.gen_gallery',
4445
'matplotlib.sphinxext.plot_directive',
4546
'myst_parser',
@@ -206,20 +207,28 @@
206207
{
207208
'name': 'GitHub',
208209
'url': 'https://github.com/Unidata/MetPy',
209-
'icon': 'fab fa-github-square',
210+
'icon': 'fa-brands fa-github-square',
211+
'type': 'fontawesome',
210212
},
211213
{
212214
'name': 'Twitter',
213215
'url': 'https://twitter.com/MetPy',
214-
'icon': 'fab fa-twitter-square',
216+
'icon': 'fa-brands fa-twitter-square',
217+
'type': 'fontawesome',
215218
}
216219
],
217220
'use_edit_page_button': False,
218-
'google_analytics_id': 'UA-92978945-1',
221+
'analytics': {'google_analytics_id': 'G-J48T2BG3J7'},
219222
'navbar_align': 'left',
220-
'navbar_start': ['navbar-logo'],
223+
'navbar_start': ['navbar-logo', 'version-switcher'],
221224
'navbar_center': ['navbar-nav'],
222-
'navbar_end': ['search-field', 'navbar-icon-links'],
225+
'header_links_before_dropdown': 6,
226+
'navbar_persistent': ['search-button'],
227+
'navbar_end': ['navbar-icon-links', 'theme-switcher'],
228+
'switcher': {
229+
'json_url': 'https://unidata.github.io/MetPy/pst-versions.json',
230+
'version_match': 'dev' if 'dev' in version else f'v{version}',
231+
},
223232
}
224233

225234
# Theme options are theme-specific and customize the look and feel of a theme
@@ -238,6 +247,7 @@
238247
'github_user': 'Unidata',
239248
'github_repo': 'MetPy',
240249
'github_version': 'main', # Make changes to the main branch
250+
'default_mode': 'light',
241251
}
242252

243253
# Add any paths that contain custom themes here, relative to this directory.
@@ -282,7 +292,7 @@
282292

283293
# Custom sidebar templates, maps document names to template names.
284294
html_sidebars = {
285-
'**': ['versions', 'sidebar-nav-bs']
295+
'**': ['sidebar-nav-bs']
286296
}
287297

288298
# Additional templates that should be rendered to pages, maps page names to

docs/doc-server.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,8 @@ def translate_path(self, path):
2222
"""Translate a request path to the proper path into the built docs."""
2323
if path == '/MetPy/banner.html':
2424
return str(TEST_FILES_DIR / 'banner.html')
25-
elif path == '/MetPy/versions.json':
26-
return str(TEST_FILES_DIR / 'versions.json')
25+
elif path == '/MetPy/pst-versions.json':
26+
return str(TEST_FILES_DIR / 'pst-versions.json')
2727
elif path.startswith('/MetPy/'):
2828
path = posixpath.join('/', *path.split('/')[3:])
2929
return super().translate_path(path)
@@ -33,7 +33,7 @@ def translate_path(self, path):
3333

3434
with socketserver.TCPServer(('', PORT), build_server) as httpd:
3535
try:
36-
print(f'Serving docs at: http://localhost:{PORT}/MetPy/v1.0')
36+
print(f'Serving docs at: http://localhost:{PORT}/MetPy/dev')
3737
httpd.serve_forever()
3838
except KeyboardInterrupt:
3939
sys.exit(0)

0 commit comments

Comments
 (0)