From 419657b787fa8289d5473d429db00e273d8bb61d Mon Sep 17 00:00:00 2001 From: Ryan May Date: Sun, 9 Aug 2020 00:56:50 -0600 Subject: [PATCH 01/23] DOCS: Limit matplotlib plot formats When using the plot extension, the default is to make images as PNG, hires PNG, and PDF. Limit to just the PNG. --- docs/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.py b/docs/conf.py index c74b5798bdb..efa4605ef4f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -59,6 +59,7 @@ # Turn off code and image links for embedded mpl plots plot_html_show_source_link = False plot_html_show_formats = False +plot_formats = ['png'] # Set up mapping for other projects' docs intersphinx_mapping = { From 741b640d7e0a5144d8c980f04963a8b2f96e3f74 Mon Sep 17 00:00:00 2001 From: Ryan May Date: Sun, 9 Aug 2020 01:37:02 -0600 Subject: [PATCH 02/23] DOCS: Move to pydata-sphinx-theme This is a nice, clean bootstrap-based theme that is used by quite a few projects in the pydata ecosystem. --- docs/_static/theme-unidata.css | 142 +++++++++++++++++++++++++++++++ docs/_static/theme_override.css | 25 ------ docs/_templates/breadcrumbs.html | 30 ------- docs/_templates/footer.html | 14 --- docs/conf.py | 28 +++--- 5 files changed, 158 insertions(+), 81 deletions(-) create mode 100644 docs/_static/theme-unidata.css delete mode 100644 docs/_static/theme_override.css delete mode 100644 docs/_templates/breadcrumbs.html delete mode 100644 docs/_templates/footer.html diff --git a/docs/_static/theme-unidata.css b/docs/_static/theme-unidata.css new file mode 100644 index 00000000000..89d3182d7a5 --- /dev/null +++ b/docs/_static/theme-unidata.css @@ -0,0 +1,142 @@ +.summary { + color: #808080; + border-left: 5px solid #ED1951; + font-size:16px; +} + + +h3 {color: #ED1951; } +h4 {color: #808080; } + +.nav-tabs > li.active > a, .nav-tabs > li.active > a:hover, .nav-tabs > li.active > a:focus { + background-color: #06778F; /* was #248ec2 */ + color: white; +} + +.nav > li.active > a { + background-color: #034250; /* was #347DBE */ +} + +.nav > li > a:hover { + background-color: #06778F; /* was #248ec2 */ +} + +div.navbar-collapse .dropdown-menu > li > a:hover { + background-color: #034250; /* was #347DBE */ +} + +.nav li.thirdlevel > a { + background-color: #FAFAFA !important; + color: #06778F; /* was #248ec2 */ + font-weight: bold; +} + +a[data-toggle="tooltip"] { + color: #649345; + font-style: italic; + cursor: default; +} + +.navbar-inverse { + background-color: #06778F; + border-color: #034250; +} + +.navbar-inverse .navbar-nav > .open > a, .navbar-inverse .navbar-nav > .open > a:hover, .navbar-inverse .navbar-nav > .open > a:focus { + color: #034250; +} + +.navbar-inverse .navbar-nav > .open > a, .navbar-inverse .navbar-nav > .open > a:hover, .navbar-inverse .navbar-nav > .open > a:focus { + background-color: #034250; + color: #ffffff; +} + +/* not sure if using this ...*/ +.navbar-inverse .navbar-collapse, .navbar-inverse .navbar-form { + border-color: #248ec2 !important; +} + +.btn-primary { + color: #ffffff; + background-color: #034250; /* was #347DBE */ + border-color: #034250; /* was #347DBE */ +} + +.navbar-inverse .navbar-nav > .active > a, .navbar-inverse .navbar-nav > .active > a:hover, .navbar-inverse .navbar-nav > .active > a:focus { + background-color: #034250; /* was #347DBE */ +} + +.btn-primary:hover, +.btn-primary:focus, +.btn-primary:active, +.btn-primary.active, +.open .dropdown-toggle.btn-primary { + background-color: #06778F; /* was #248ec2 */ + border-color: #034250; /* was #347DBE */ +} + +.printTitle { + color: #034250 !important; +} + +body.print h1 {color: #034250 !important; font-size:28px !important;} +body.print h2 {color: #595959 !important; font-size:20px !important;} +body.print h3 {color: #E50E51 !important; font-size:14px !important;} +body.print h4 {color: #679DCE !important; font-size:14px; font-style: italic !important;} + +.anchorjs-link:hover { + color: #216f9b; +} + +div.sidebarTitle { + color: #034250; +} + +li.sidebarTitle { + margin-top:40px; + font-weight:normal; + font-size:130%; + color: #ED1951; + margin-bottom:10px; + margin-left: 5px; + +} +/* left-floated version menu */ /* DD 2020_04 */ +@media (min-width: 768px) { + ul.navbar-left > li#vermenu > a { + font-size: 18px; + font-weight: 600; + } +} + +/* Enhance the links to function docs in the gallery examples */ +div[class^="highlight"] a { + background-color: #EEEEEE; +} + +/* Control the appearance of the version alert banner */ +#banner .version-alert { + background-color: #D95B43; + padding: 1em; + color: #fff; + font-family: "Work Sans", sans-serif; + font-weight: 600; font-size: 16px; +} + +.version-alert a { + text-decoration: underline; + color: #ddd; +} + +/* Control the appearance of the news alert banner */ +#banner .news-alert { + background-color: #ECD078; + padding: 1em; + font-family: "Work Sans", sans-serif; + font-weight: 600; font-size: 16px; +} + +.news-alert a { + text-decoration: underline; + color: #444; +} \ No newline at end of file diff --git a/docs/_static/theme_override.css b/docs/_static/theme_override.css deleted file mode 100644 index e49459a7c30..00000000000 --- a/docs/_static/theme_override.css +++ /dev/null @@ -1,25 +0,0 @@ -div[class^="highlight"] a { - background-color: #E6E6E6; -} - -div[class^="highlight"] a:hover { - background-color: #ABECFC; -} - -.wy-nav-content { - max-width: 100% -} - -/* For the link to edit the page on Github */ -.source-link { - float: right; -} - -/* Don't let the edit link disappear on mobile. */ -@media screen and (max-width: 480px) { - .wy-breadcrumbs li.source-link { - float:none; - display: block; - margin-top: 20px; - } -} diff --git a/docs/_templates/breadcrumbs.html b/docs/_templates/breadcrumbs.html deleted file mode 100644 index 0bdbf6640a2..00000000000 --- a/docs/_templates/breadcrumbs.html +++ /dev/null @@ -1,30 +0,0 @@ -{# Extend the RTD template to include links to Github instead of "View page - source" #} -{% extends "!breadcrumbs.html" %} - - -{% block breadcrumbs_aside %} -
  • - {% if hasdoc(pagename) %} - {% if pagename.startswith(api_dir) %} - {% set title = "Suggested improvement for " + pagename %} - {% set body = "Please describe what could be improved about this page or the typo/mistake that you found:" %} - Improve this page - {% elif pagename.split("/")[0] in galleries %} - {% set gallery_path = gallery_dir[pagename.split("/")[0]] %} - {% set example_script = pagename|replace(pagename.split("/")[0], gallery_dir[pagename.split("/")[0]]) %} - {% if pagename.split("/")[-1] == "index" %} - {% set example_script = example_script|replace("index", "README.txt") %} - {% else %} - {% set example_script = example_script + ".py" %} - {% endif %} - Improve this page - {% else %} - Improve this page - {% endif %} - {% endif %} -
    • -{% endblock %} diff --git a/docs/_templates/footer.html b/docs/_templates/footer.html deleted file mode 100644 index 63e8248e479..00000000000 --- a/docs/_templates/footer.html +++ /dev/null @@ -1,14 +0,0 @@ -{% extends "!footer.html" %} -{% block extrafooter %} - {{ super() }} - - -{% endblock %} diff --git a/docs/conf.py b/docs/conf.py index efa4605ef4f..7bd6f15eb97 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -160,20 +160,23 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -# html_theme = 'default' -try: - import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] -except ImportError: - pass +html_theme = 'pydata_sphinx_theme' +html_theme_options = { + 'github_url': 'https://github.com/Unidata/MetPy', + 'twitter_url': 'https://twitter.com/MetPy', + 'external_links': [ + {'name': 'Release Notes', 'url': 'https://github.com/Unidata/MetPy/releases'}, + ], + 'use_edit_page_button': False, + 'google_analytics_id': 'UA-92978945-1', + 'search_bar_position': 'navbar', +# 'navbar_align': 'left' # Coming in next release of theme +} # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -html_theme_options = {'canonical_url': 'https://unidata.github.io/MetPy/latest/'} -if 'sphinx_rtd_theme' in vars() and sphinx_rtd_theme.__version__ == '0.2.5b1.post1': - html_theme_options['versions'] = {'latest': '../latest', 'dev': '../dev'} +# html_theme_options = {'canonical_url': 'https://unidata.github.io/MetPy/latest/'} # Extra variables that will be available to the templates. Used to create the # links to the Github repository sources and issues @@ -183,7 +186,8 @@ 'gallery_dir': dict(zip(sphinx_gallery_conf['gallery_dirs'], sphinx_gallery_conf['examples_dirs'])), 'api_dir': 'api/generated', - 'github_repo': 'Unidata/MetPy', + 'github_user': 'Unidata', + 'github_repo': 'MetPy', 'github_version': 'master', # Make changes to the master branch } @@ -211,7 +215,7 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -html_css_files = ['theme_override.css'] +html_css_files = ['theme-unidata.css'] html_js_files = ['pop_ver.js'] # Add any extra paths that contain custom files (such as robots.txt or From 4b58298a3cba53ee7ed2ca86b4904f44ceb457b4 Mon Sep 17 00:00:00 2001 From: Ryan May Date: Tue, 11 Aug 2020 02:04:57 -0600 Subject: [PATCH 03/23] DOCS: Add cleanall target Put clean back to only removing sphinx built docs and add a `cleanall` target to remove the output from sphinx-gallery. This allows a make clean to be a bit quicker when working on doc theming/style. --- docs/Makefile | 5 ++++- docs/make.bat | 5 +++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index 36ea4967c61..e0720354921 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -13,8 +13,11 @@ help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) # Sphinx doesn't know to clean out the debris from sphinx-gallery +cleanall: clean + rm -rf $(SOURCEDIR)/examples $(SOURCEDIR)/tutorials $(SOURCEDIR)/api/generated + clean: - rm -rf $(BUILDDIR)/* $(SOURCEDIR)/examples $(SOURCEDIR)/tutorials $(SOURCEDIR)/api/generated + rm -rf $(BUILDDIR)/* # Check that all functions in modules with template overrides are present in the doc file overridecheck: diff --git a/docs/make.bat b/docs/make.bat index 041d7bae5c7..ca6dc4a71e8 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -17,6 +17,11 @@ set SPHINXPROJ=MetPy if "%1" == "" goto help if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + goto end +) + +if "%1" == "cleanall" ( for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i rmdir /q /s %SOURCEDIR%\examples\ %SOURCEDIR%\tutorials\ %SOURCEDIR%\api\generated\ goto end From 2e3f520664729ea078e1dddc569d5d50e9453c47 Mon Sep 17 00:00:00 2001 From: Ryan May Date: Tue, 11 Aug 2020 02:07:25 -0600 Subject: [PATCH 04/23] DOCS: Cleanup conf.py a bit Use f-strings and clean up version/release parsing code. --- docs/conf.py | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 7bd6f15eb97..2c4e3bfcf5b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -11,6 +11,7 @@ from datetime import datetime import os +import re import sys import metpy @@ -89,6 +90,7 @@ # The encoding of source files. # source_encoding = 'utf-8-sig' +cur_date = datetime.utcnow() # The master toctree document. master_doc = 'index' @@ -96,26 +98,28 @@ # General information about the project. project = 'MetPy' # noinspection PyShadowingBuiltins -copyright = ('2008-2020, MetPy Developers. ' +copyright = (f'{cur_date:%Y}-2020, MetPy Developers. ' 'Development supported by National Science Foundation grants ' - 'AGS-1344155, OAC-1740315, and AGS-1901712.') + 'AGS-1344155, OAC-1740315, and AGS-1901712') # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # -# The short X.Y version. verinfo = metpy.__version__ -full_version = verinfo.split('+')[0] -version = full_version.rsplit('.', 1)[0] +parsed_version = re.search(r'(?P(?P\d+\.\d+)\.\d+\w*)', verinfo).groupdict() +# The short X.Y version. +version = parsed_version['base'] +if '+' in verinfo: + version += 'dev' # The full version, including alpha/beta/rc tags. -release = verinfo +release = parsed_version['full'] -rst_prolog = ''' -.. |cite_version| replace:: {0} -.. |cite_year| replace:: {1:%Y} -.. |access_date| replace:: {1:%d %B %Y} -'''.format(full_version, datetime.utcnow()) +rst_prolog = f''' +.. |cite_version| replace:: {release} +.. |cite_year| replace:: {cur_date:%Y} +.. |access_date| replace:: {cur_date:%d %B %Y} +''' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. From fc8496deb2ad4996daa01e62f3ba67e882b0cdce Mon Sep 17 00:00:00 2001 From: Ryan May Date: Tue, 11 Aug 2020 02:16:02 -0600 Subject: [PATCH 05/23] DOCS: Add version chooser to theme This requires tweaking the theme to add some elements, plus a version of our previous javascript to populate it based on json in the root of the docs repo. --- docs/_static/doc_shared.js | 43 ++++++++++++++++++++++ docs/_static/pop_ver.js | 17 --------- docs/_templates/docs-navbar.html | 62 ++++++++++++++++++++++++++++++++ docs/_templates/layout.html | 6 ++++ docs/conf.py | 2 +- 5 files changed, 112 insertions(+), 18 deletions(-) create mode 100644 docs/_static/doc_shared.js delete mode 100644 docs/_static/pop_ver.js create mode 100644 docs/_templates/docs-navbar.html create mode 100644 docs/_templates/layout.html diff --git a/docs/_static/doc_shared.js b/docs/_static/doc_shared.js new file mode 100644 index 00000000000..9c98fb7cd33 --- /dev/null +++ b/docs/_static/doc_shared.js @@ -0,0 +1,43 @@ +const proj = "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('/' + proj + '/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 = $('
    This documentation page is for a ' + msg + + ' version. For the latest release version, go to https://unidata.github.io/MetPy/latest/'); + $('#banner').append(content); + } + + $.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('' + name + ''); + } + }); + }); +}); + +// Borrowed from Bokeh docs to look for an alert.html at the base of the +// docs repo and add that to the banner if present. +$(document).ready(function () { + $.get('/' + proj + '/alert.html', function (data) { + if (data.length > 0) { + content = $('
    ' + data + '
    ') + $('#banner').prepend(content); + } + }) + }) diff --git a/docs/_static/pop_ver.js b/docs/_static/pop_ver.js deleted file mode 100644 index 8013f12aacb..00000000000 --- a/docs/_static/pop_ver.js +++ /dev/null @@ -1,17 +0,0 @@ -$(document).ready(function() { - var proj_end = document.baseURI.indexOf("MetPy") + 6; - var end = document.baseURI.indexOf("/", proj_end); - var cur_ver = document.baseURI.substring(proj_end, end); - var name = cur_ver.startsWith('v') ? cur_ver.substring(1) : cur_ver; - var mylist = $("#version-list"); - mylist.empty(); - mylist.append($("