From 45eb47735019c9129b6b7c6c8dcd38b2baa07d11 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 31 Mar 2023 12:56:54 +0000 Subject: [PATCH 01/12] CI: (deps): Bump pydata-sphinx-theme from 0.8.1 to 0.13.3 in /ci Bumps [pydata-sphinx-theme](https://github.com/pydata/pydata-sphinx-theme) from 0.8.1 to 0.13.3. - [Release notes](https://github.com/pydata/pydata-sphinx-theme/releases) - [Commits](https://github.com/pydata/pydata-sphinx-theme/compare/v0.8.1...v0.13.3) --- updated-dependencies: - dependency-name: pydata-sphinx-theme dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] --- ci/doc_requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ci/doc_requirements.txt b/ci/doc_requirements.txt index 224b7370ee1..9397f5aae08 100644 --- a/ci/doc_requirements.txt +++ b/ci/doc_requirements.txt @@ -1,5 +1,5 @@ sphinx==4.5.0 -pydata-sphinx-theme==0.8.1 +pydata-sphinx-theme==0.13.3 sphinx-gallery==0.13.0 myst-parser==0.18.1 netCDF4==1.6.3 From 360ab32e3ae3c1bb7c57f833d542eb08ef23f910 Mon Sep 17 00:00:00 2001 From: Drew Camron Date: Mon, 8 May 2023 17:12:12 -0600 Subject: [PATCH 02/12] DOC: Update for new PST config Change analytics config keys for newer pydata-sphinx-theme version. Switch to search button in prep for style changes. --- docs/conf.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 71ad84b84e5..3720b0c7285 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -215,11 +215,13 @@ } ], 'use_edit_page_button': False, - 'google_analytics_id': 'UA-92978945-1', + 'analytics': {'google_analytics_id': 'UA-92978945-1'}, 'navbar_align': 'left', 'navbar_start': ['navbar-logo'], '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 options are theme-specific and customize the look and feel of a theme From 8d3752c67bf69021a1ec5fcbdf5459ec02be9439 Mon Sep 17 00:00:00 2001 From: Drew Camron Date: Tue, 9 May 2023 10:17:31 -0600 Subject: [PATCH 03/12] DOC: update home cards Switch to sphinx-design to define grid of clickable card links for home layout. Enables responsive layout and theme inheritance. --- docs/conf.py | 1 + docs/index.rst | 128 +++++++++++++++++++------------------------------ 2 files changed, 50 insertions(+), 79 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 3720b0c7285..5d2e88bd1d2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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', diff --git a/docs/index.rst b/docs/index.rst index 773d81045ba..488ad4a118d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,85 +19,55 @@ with weather data. MetPy supports Python >= 3.8 and is freely available under a If you're new to MetPy, check out our :doc:`Getting Started ` guide. -.. raw:: html - -
-
-
-
- -
-
User Guide
-

The user guide provides in-depth information on how - to use MetPy, including how to get started. This is where to look for - general conceptual descriptions on how to use parts of MetPy, like its - support for XArray or units.

- -.. container:: card-button - - :doc:`To the user guide` - -.. raw:: html - -
-
-
-
-
- -
-
Reference Guide
-

The reference guide contains detailed descriptions on - every function and class within MetPy. This is where to turn to understand - how to use a particular feature or where to search for a specific tool.

- -.. container:: card-button - - :doc:`To the reference guide` - -.. raw:: html - -
-
-
-
-
- -
-
Developer Guide
-

Want to help make MetPy better? Found something - that's not working quite right? You can find instructions on how to - contribute to MetPy here. You can also find detailed descriptions on - tools useful for developing MetPy.

- -.. container:: card-button - - :doc:`To the development guide` - -.. raw:: html - -
-
-
-
-
- -
-
Examples
-

Check out MetPy's gallery of examples which contains - sample code demonstrating various parts of MetPy's functionality.

- -.. container:: card-button - - :doc:`To the example gallery` - -.. raw:: html - -
-
-
-
-
+ +.. grid:: 1 2 2 2 + :gutter: 2 + + .. grid-item-card:: :octicon:`book;10em` + :link: userguide/index + :link-type: doc + :text-align: center + + **User Guide** + + The user guide provides in-depth information on how + to use MetPy, including how to get started. This is where to look for + general conceptual descriptions on how to use parts of MetPy, like its + support for XArray or units. + + .. grid-item-card:: :octicon:`list-unordered;10em` + :link: api/index + :link-type: doc + :text-align: center + + **Reference Guide** + + The reference guide contains detailed descriptions on + every function and class within MetPy. This is where to turn to understand + how to use a particular feature or where to search for a specific tool + + .. grid-item-card:: :octicon:`terminal;10em` + :link: devel/index + :link-type: doc + :text-align: center + + **Developer Guide** + + Want to help make MetPy better? Found something + that's not working quite right? You can find instructions on how to + contribute to MetPy here. You can also find detailed descriptions on + tools useful for developing MetPy. + + .. grid-item-card:: :octicon:`graph;10em` + :link: examples/index + :link-type: doc + :text-align: center + + **Example Gallery** + + Check out MetPy's gallery of examples which contains + sample code demonstrating various parts of MetPy's functionality. + Our up-to-date references for grants and funding can be found `here `_. From 6b5c2662caabb9af633fc224aac6bce8e0494079 Mon Sep 17 00:00:00 2001 From: Drew Camron Date: Tue, 9 May 2023 10:20:42 -0600 Subject: [PATCH 04/12] DOC: update theme overrides Trim css and html overrides to reduce possible breaks with theme updates. Play better with PST css variables for color and fonts. Modify config for better icon support. --- docs/_static/theme-unidata.css | 123 ++++++--------------------------- docs/_templates/layout.html | 12 +--- docs/conf.py | 7 +- 3 files changed, 29 insertions(+), 113 deletions(-) diff --git a/docs/_static/theme-unidata.css b/docs/_static/theme-unidata.css index 000522e6fc1..c6f6c796a3a 100644 --- a/docs/_static/theme-unidata.css +++ b/docs/_static/theme-unidata.css @@ -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 */ @@ -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; -} diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html index 2020c97cd0a..ba429708c47 100644 --- a/docs/_templates/layout.html +++ b/docs/_templates/layout.html @@ -1,22 +1,12 @@ -{% extends "!layout.html" %} +{% extends "pydata_sphinx_theme/layout.html" %} {% block fonts %} - {{ super() }} {% endblock %} {% block extrahead %} {{ super() }} {% endblock %} - -{% block docs_navbar %} - - -{# Added to support a banner with an alert #} - -{% endblock %} diff --git a/docs/conf.py b/docs/conf.py index 5d2e88bd1d2..2bac0e75e0f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -207,12 +207,14 @@ { '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, @@ -241,6 +243,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. From eef32ace737e42b2357f7b688663d1d7d8e5997a Mon Sep 17 00:00:00 2001 From: Drew Camron Date: Tue, 9 May 2023 10:28:40 -0600 Subject: [PATCH 05/12] Update test-server setup Change local docs testing setup to support new version file format and name. Remove old version spec. --- docs/doc-server.py | 6 +++--- docs/test-server/pst-versions.json | 30 ++++++++++++++++++++++++++++++ docs/test-server/versions.json | 4 ---- 3 files changed, 33 insertions(+), 7 deletions(-) create mode 100644 docs/test-server/pst-versions.json delete mode 100644 docs/test-server/versions.json diff --git a/docs/doc-server.py b/docs/doc-server.py index bae0fdf36d2..1224d71b399 100755 --- a/docs/doc-server.py +++ b/docs/doc-server.py @@ -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) @@ -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) diff --git a/docs/test-server/pst-versions.json b/docs/test-server/pst-versions.json new file mode 100644 index 00000000000..1ef26eb1f92 --- /dev/null +++ b/docs/test-server/pst-versions.json @@ -0,0 +1,30 @@ +[ + { + "version": "dev", + "url": "https://unidata.github.io/MetPy/dev/" + }, + { + "version": "latest", + "url": "https://unidata.github.io/MetPy/latest/" + }, + { + "name": "v1.5", + "version": "1.5", + "url": "https://unidata.github.io/MetPy/v1.5/" + }, + { + "name": "v1.4", + "version": "1.4", + "url": "https://unidata.github.io/MetPy/v1.4/" + }, + { + "name": "v1.3", + "version": "1.3", + "url": "https://unidata.github.io/MetPy/v1.3/" + }, + { + "name": "v1.2", + "version": "1.2", + "url": "https://unidata.github.io/MetPy/v1.2/" + } +] \ No newline at end of file diff --git a/docs/test-server/versions.json b/docs/test-server/versions.json deleted file mode 100644 index a02cfa93991..00000000000 --- a/docs/test-server/versions.json +++ /dev/null @@ -1,4 +0,0 @@ -{"versions":["latest","dev","v0.1","v0.10","v0.11","v0.12","v0.2","v0.3","v0.4","v0.5","v0.6","v0.7","v0.8","v0.9","v1.0"], -"latest": "v0.12", -"prereleases": ["v1.0"] -} From 1a5afcccbdc0f41caa9e390bd2d72bbc91b974ab Mon Sep 17 00:00:00 2001 From: Drew Camron Date: Tue, 9 May 2023 10:33:19 -0600 Subject: [PATCH 06/12] DOC: use PST version switcher Accompanies new pst-versions.json on gh-pages. Move version switcher to navbar and use template provided by PST for consistent themeing and maintainability. Remove old switcher. --- CONTRIBUTING.md | 15 +++++++++++++++ docs/_static/doc_shared.js | 31 ------------------------------- docs/_templates/versions.html | 4 ---- docs/conf.py | 10 +++++++--- 4 files changed, 22 insertions(+), 38 deletions(-) delete mode 100644 docs/_templates/versions.html diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 387196c84ce..e13f6279c2a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 diff --git a/docs/_static/doc_shared.js b/docs/_static/doc_shared.js index 40c2e66a4d9..700d95a392d 100644 --- a/docs/_static/doc_shared.js +++ b/docs/_static/doc_shared.js @@ -1,36 +1,5 @@ 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 = $('