Skip to content

Commit

Permalink
Merge pull request #2974 from Unidata/dependabot-pip-ci-pydata-sphinx…
Browse files Browse the repository at this point in the history
…-theme-0.13.3

CI: (deps): Bump pydata-sphinx-theme from 0.8.1 to 0.13.3 in /ci
  • Loading branch information
dopplershift authored May 16, 2023
2 parents a044032 + 3a4b3f0 commit 6467254
Show file tree
Hide file tree
Showing 12 changed files with 211 additions and 239 deletions.
15 changes: 15 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -212,6 +212,21 @@ Then, still from within your ``devel`` environment,
* Remove any old builds and build the current docs ``make clean html``
* Open ``docs/build/html/index.html`` and see your changes!

### `doc-server.py`

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

## Tests

Unit tests are the lifeblood of the project, as it ensures that we can continue to add and
Expand Down
7 changes: 4 additions & 3 deletions ci/doc_requirements.txt
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
sphinx==4.5.0
pydata-sphinx-theme==0.8.1
sphinx==6.2.1
pydata-sphinx-theme==0.13.3
sphinx-design==0.4.1
sphinx-gallery==0.13.0
myst-parser==0.18.1
myst-parser==1.0.0
netCDF4==1.6.3
geopandas==0.13.0
rtree==1.0.1
100 changes: 66 additions & 34 deletions docs/_static/doc_shared.js
Original file line number Diff line number Diff line change
@@ -1,43 +1,75 @@
const project = "MetPy";

$(document).ready(function() {
cur_ver = DOCUMENTATION_OPTIONS.VERSION;
end = cur_ver.lastIndexOf('.');
if (end > -1) {
cur_ver = 'v' + cur_ver.substring(0, end);
}
console.log('cur_ver: ' + cur_ver);

$.getJSON('/' + project + '/versions.json', function(data) {
if (cur_ver !== data.latest) {
let msg;
if (cur_ver.includes('dev') || data.prereleases.indexOf(cur_ver) > -1) {
msg = 'development / pre-release';
} else {
msg = 'previous';
}
content = $('<div class="alert alert-secondary alert-version" role="alert">This documentation page is for a ' + msg +
' 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>');
$('#banner').append(content);
function documentReady(callback) {
if (document.readyState != "loading") callback();
else document.addEventListener("DOMContentLoaded", callback);
}

documentReady(function () {
// Use PST version metadata to match current doc version
const cur_ver = DOCUMENTATION_OPTIONS.theme_switcher_version_match;
console.log("cur_ver: " + cur_ver);

fetch("/" + project + "/pst-versions.json")
.then(function (response) {
return response.json();
})
.then(function (data) {
// Find matching version entry in PST version list
const entry = data[data.findIndex((obj) => obj.version == cur_ver)];

// Find out if matched version is latest
// and construct alert message
if (entry.is_latest != true) {
let rel_type;
if (cur_ver.includes("dev") || entry.is_prerelease == true) {
rel_type = "development/pre-release";
} else {
rel_type = "previous";
}

$.each(data.versions, function() {
if (this !== 'latest') {
const url = DOCUMENTATION_OPTIONS.URL_ROOT + '../' + this;
const name = this.startsWith('v') ? this.substring(1) : this;
$('#version-menu').append('<a class="dropdown-item" href="' + url + '">' + name + '</a>');
}
});
let msg =
`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>`;

// Create alert div and fill with message content
let content = document.createElement("div");
content.classList.add("alert", "alert-secondary", "alert-version");
content.setAttribute("role", "alert");
content.innerHTML = msg;

// Append alert div to banner div under navbar
document.querySelector("#banner").appendChild(content);
} else {
console.log("MetPy version latest.");
}
})
.catch(function (err) {
console.warn("Something went wrong.", err);
});
});

// Borrowed from Bokeh docs to look for a banner.html at the base of the docs repo and add that
// to the banner if present.
$(document).ready(function () {
$.get('/' + project + '/banner.html', function (data) {
if (data.length > 0) {
console.log(data);
$('#banner').prepend(data);
documentReady(function () {
fetch("/" + project + "/banner.html")
.then(function (response) {
return response.text();
})
.then(function (html) {
// If any banner.html exists, parse it and add to banner div
if (html.length > 0) {
let parser = new DOMParser();
let doc = parser.parseFromString(html.trim(), "text/html");

// Get all div elements from banner.html
// and prepend them to banner div under navbar
let divs = doc.getElementsByTagName("div");
for (let div of divs) {
document.querySelector("#banner").prepend(div);
}
} else {
console.log("Banner empty.");
}
})
})
.catch(function (err) {
return console.warn("Something went wrong.", err);
});
});
123 changes: 23 additions & 100 deletions docs/_static/theme-unidata.css
Original file line number Diff line number Diff line change
@@ -1,38 +1,36 @@
/* UCAR style heading towards use of Poppins font */
.header-style, h1, h2, h3, h4, h5, h6 {
font-family: Poppins, sans-serif;
}

/* Unidata header color */
.bg-unidata {
background-color: #06778F;
/* Define "Unidata Blue" RGB values */
:root {
--unidata-blue-rgb: 6, 119, 143;
}

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

.fa-github-square:before {
color: rgba(255, 255, 255, 0.5) !important;
font-weight: 400 !important;
/* Header colors */
.bd-header {
background: rgb(var(--unidata-blue-rgb)) !important;
}

.fa-twitter-square:before {
color: rgba(255, 255, 255, 0.5) !important;
font-weight: 400 !important;
.theme-switch-button {
border-color: rgb(var(--unidata-blue-rgb)) !important;
}

/* Override the default logo height */
.navbar-brand {
height: 50px;
.bd-header .navbar-nav>.nav-item>.nav-link,
.bd-header .dropdown-toggle,
.bd-header .fa-solid {
color: #fff !important;
}

.navbar-nav .dropdown-menu {
background-color: var(--pst-color-background);
}

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

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

.intro-card {
background: #d8e5e8;
border: none;
border-radius: 0;
padding: 30px 10px 10px 10px;
margin: 10px 0px;
}

.intro-card .card-text {
margin: 20px 0px;
}

.card-button {
background-color: #fafafa;
border: none;
color: #484848;
text-align: center;
text-decoration: none;
display: inline-block;
font-size: 0.9rem;
border-radius: 0.5rem;
max-width: 220px;
padding: 0.5rem 0rem;
margin-top: auto;
}

.card-button a {
color: #484848;
}

.card-button p {
margin-top: 0;
margin-bottom: 0rem;
color: #484848;
}

/* Tweaks to the appearance of the sidebars */
.bd-sidebar {
flex: 0 0 20%;
border-right: none;
}

.bd-toc .tocsection {
border-left: none;
}

.bd-toc .section-nav {
.bd-sidebar-secondary div {
border-left: none;
}

/* Can remove once theme releases new version */
/* xarray output display in bootstrap */
.xr-wrap[hidden] {
display: block !important;
}

.xr-var-data pre {
border: none;
box-shadow: none;
}


/* Styling the API Changes Table */
.api-table tr:nth-child(3n + 1){
background: #EEF5F5;
}

.api-table tr:nth-child(3n + 2){
opacity: 0.65;
}

code.literal:not(.xref) span.pre {
color: #000;
}

.api-table tr:nth-child(3n + 2)>td span:first-child::before{
content: url(old.png);
zoom: 0.25;
}

.api-table tr:nth-child(3n + 3)>td span:first-child::before{
content: url(new.png);
zoom: 0.21;
}
8 changes: 2 additions & 6 deletions docs/_templates/layout.html
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@
<style>
@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');
</style>
{{ super() }}
{% endblock %}

{% block extrahead %}
Expand All @@ -13,10 +12,7 @@
{% endblock %}

{% block docs_navbar %}
<nav class="navbar navbar-dark navbar-expand-lg bg-unidata fixed-top bd-navbar shadow" id="navbar-main">
{%- include "docs-navbar.html" %}
</nav>

{# Added to support a banner with an alert #}
{{ super() }}
{# Added to support a banner with an alert #}
<div class="container-fluid" id="banner"></div>
{% endblock %}
4 changes: 0 additions & 4 deletions docs/_templates/versions.html

This file was deleted.

22 changes: 16 additions & 6 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@
'sphinx.ext.mathjax',
'sphinx.ext.napoleon',
'sphinx.ext.viewcode',
'sphinx_design',
'sphinx_gallery.gen_gallery',
'matplotlib.sphinxext.plot_directive',
'myst_parser',
Expand Down Expand Up @@ -206,20 +207,28 @@
{
'name': 'GitHub',
'url': 'https://github.com/Unidata/MetPy',
'icon': 'fab fa-github-square',
'icon': 'fa-brands fa-github-square',
'type': 'fontawesome',
},
{
'name': 'Twitter',
'url': 'https://twitter.com/MetPy',
'icon': 'fab fa-twitter-square',
'icon': 'fa-brands fa-twitter-square',
'type': 'fontawesome',
}
],
'use_edit_page_button': False,
'google_analytics_id': 'UA-92978945-1',
'analytics': {'google_analytics_id': 'G-J48T2BG3J7'},
'navbar_align': 'left',
'navbar_start': ['navbar-logo'],
'navbar_start': ['navbar-logo', 'version-switcher'],
'navbar_center': ['navbar-nav'],
'navbar_end': ['search-field', 'navbar-icon-links'],
'header_links_before_dropdown': 6,
'navbar_persistent': ['search-button'],
'navbar_end': ['navbar-icon-links', 'theme-switcher'],
'switcher': {
'json_url': 'https://unidata.github.io/MetPy/pst-versions.json',
'version_match': 'dev' if 'dev' in version else f'v{version}',
},
}

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

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

# Custom sidebar templates, maps document names to template names.
html_sidebars = {
'**': ['versions', 'sidebar-nav-bs']
'**': ['sidebar-nav-bs']
}

# Additional templates that should be rendered to pages, maps page names to
Expand Down
6 changes: 3 additions & 3 deletions docs/doc-server.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,8 @@ def translate_path(self, path):
"""Translate a request path to the proper path into the built docs."""
if path == '/MetPy/banner.html':
return str(TEST_FILES_DIR / 'banner.html')
elif path == '/MetPy/versions.json':
return str(TEST_FILES_DIR / 'versions.json')
elif path == '/MetPy/pst-versions.json':
return str(TEST_FILES_DIR / 'pst-versions.json')
elif path.startswith('/MetPy/'):
path = posixpath.join('/', *path.split('/')[3:])
return super().translate_path(path)
Expand All @@ -33,7 +33,7 @@ def translate_path(self, path):

with socketserver.TCPServer(('', PORT), build_server) as httpd:
try:
print(f'Serving docs at: http://localhost:{PORT}/MetPy/v1.0')
print(f'Serving docs at: http://localhost:{PORT}/MetPy/dev')
httpd.serve_forever()
except KeyboardInterrupt:
sys.exit(0)
Loading

0 comments on commit 6467254

Please sign in to comment.