diff --git a/README.rst b/README.rst index bcc62639df..a73b86efef 100644 --- a/README.rst +++ b/README.rst @@ -293,7 +293,7 @@ Contributing We welcome contributions for all uses of Py-ART, provided the code can be distributed under the BSD 3-clause license. A copy of this license is available in the **LICENSE.txt** file in this directory. For more on -contributing, see the `contributor's guide. `_ +contributing, see the `contributor's guide. `_ Testing ------- diff --git a/doc/environment.yml b/doc/environment.yml index 1f745ca931..b5eb0ef370 100644 --- a/doc/environment.yml +++ b/doc/environment.yml @@ -25,14 +25,15 @@ dependencies: - glpk - cftime - shapely + - open-radar-data + - myst-nb + - ablog + - pydata-sphinx-theme + - sphinx-gallery + - sphinx-design + - sphinx-copybutton + - nbsphinx - pip - pip: - - git+https://github.com/openradar/open-radar-data - - pydata-sphinx-theme<0.9.0 - - sphinx_gallery - - sphinx-copybutton - - myst_nb - - ablog - - nbsphinx - pooch - versioneer diff --git a/doc/source/_static/pyart-theme.css b/doc/source/_static/pyart-theme.css index 40c9760297..0614d87eac 100644 --- a/doc/source/_static/pyart-theme.css +++ b/doc/source/_static/pyart-theme.css @@ -1,146 +1,49 @@ +/* Define "ARM Blue" RGB values */ +:root { + --arm-blue-rgb: 18, 65, 117; +} + /* PyART style heading towards use of Poppins font */ .header-style, h1, h2, h3, h4, h5, h6 { font-family: Poppins, sans-serif; - } +} /* ARM header color */ - .bg-arm { - background-color: #182b55; + .bg-header { + background: rgb(var(--arm-blue-rgb)) } - :root { - --pst-color-navbar-link: 255, 255, 255; - --pst-color-text-base: 24, 43, 85; - --pst-color-h3: var(--pst-color-text-base); - --pst-color-h4: var(--pst-color-text-base); - --pst-color-h5: var(--pst-color-text-base); - --pst-color-h6: var(--pst-color-text-base); - --pst-color-paragraph: var(--pst-color-text-base); - } - -/* Override the default color set in the original theme for title */ -.navbar-brand>.title { - color: rgba(255, 255, 255) !important; - font-weight: 400 !important; - font-style: bold; + .theme-switch-button { + border-color: rgb(var(--arm-blue-rgb)) !important; } - /* Override the default color set in the original theme */ - .navbar-nav>.active>.nav-link { - color: rgba(255, 255, 255) !important; - font-weight: 400 !important; - font-style: italic; - } - - .fa-github-square:before { - color: rgba(255, 255, 255) !important; - font-weight: 400 !important; - } - - .fa-twitter-square:before { - color: rgba(255, 255, 255) !important; - font-weight: 400 !important; - } - - /* Override the default logo height */ - .navbar-brand { - height: 50px; - } - - /* 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 .alert-version, .alert-news { - margin: 1em; - padding: 0.5em; - font-family: "Work Sans", sans-serif; - 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; - } +.bd-header .navbar-nav>.nav-item>.nav-link, +.bd-header .dropdown-toggle, - .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 { - 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; - } + .navbar-nav .dropdown-menu { + background-color: var(--pst-color-background); +} - .api-table tr:nth-child(3n + 2){ - opacity: 0.65; - } +/* Increase contrast of links in code snippets */ +div[class^="highlight"] a { + background-color: rgb(var(--arm-blue-rgb), 0.2); + color: var(--pst-color-text-muted); +} - code.literal:not(.xref) span.pre { - color: #000; - } +/* Control the appearance of the version alert banner */ +#banner .alert-version, .alert-news { + margin: 1em; + padding: 0.5em; + font-family: "Work Sans", sans-serif; + font-weight: 600; font-size: 16px; +} - .api-table tr:nth-child(3n + 2)>td span:first-child::before{ - content: url(old.png); - zoom: 0.25; - } +/* Tweaks to the appearance of the sidebars */ +.bd-sidebar { + flex: 0 0 20%; + border-right: none; +} - .api-table tr:nth-child(3n + 3)>td span:first-child::before{ - content: url(new.png); - zoom: 0.21; - } +.bd-sidebar-secondary div { + border-left: none; +} diff --git a/doc/source/_templates/layout.html b/doc/source/_templates/layout.html index a5e99e6b02..adb4e32d52 100644 --- a/doc/source/_templates/layout.html +++ b/doc/source/_templates/layout.html @@ -1,17 +1,7 @@ -{% extends "!layout.html" %} +{% extends "pydata_sphinx_theme/layout.html" %} {% block fonts %} - {{ super() }} -{% endblock %} - -{% block docs_navbar %} - - -{# Added to support a banner with an alert #} - {% endblock %} diff --git a/doc/source/conf.py b/doc/source/conf.py index 4486acf3d5..b7656bc811 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -16,9 +16,12 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +import os +import sys +from pathlib import Path + +# cwd = Path.cwd().resolve() +# sys.path.insert(0, os.path.abspath('../../pyart')) # -- General configuration ------------------------------------------------ @@ -47,6 +50,7 @@ "sphinx_copybutton", "sphinx_gallery.gen_gallery", "sphinx_gallery.load_style", + "sphinx_design", "nbsphinx", "myst_nb", "ablog", @@ -71,6 +75,7 @@ autosummary_generate = True autosummary_imported_members = True +autodoc_typehints = "description" # Otherwise, the Return parameter list looks different from the Parameters list napoleon_use_rtype = False @@ -146,7 +151,7 @@ # documentation. # html_theme_options = { - "google_analytics_id": "G-JJEG3CV376", + "analytics": {"google_analytics_id": "G-JJEG3CV376"}, "github_url": "https://github.com/ARM-DOE/pyart", "twitter_url": "https://twitter.com/Py_ART", } @@ -188,7 +193,7 @@ } # Setup the blog portion -blog_baseurl = "mgrover1.github.io/pyart/" +blog_baseurl = "arm-doe.github.io/pyart/" blog_title = "PyART Blog" blog_path = "blog" fontawesome_included = True @@ -212,6 +217,7 @@ "github_user": "ARM-DOE", "github_repo": "pyart", "github_version": "main", + "default_mode": "light", } # -- Options for HTMLHelp output ------------------------------------------ diff --git a/doc/source/index.rst b/doc/source/index.rst index 613de8b1f4..7b1b20a424 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -16,6 +16,13 @@ The Python ARM Radar Toolkit - Py-ART API/index.rst +.. toctree:: + :maxdepth: 2 + :hidden: + :caption: Developer's Guide + + dev/index.rst + .. toctree:: :maxdepth: 2 :hidden: @@ -44,6 +51,54 @@ The Python ARM Radar Toolkit - Py-ART changelog.md +.. grid:: 1 2 2 2 + :gutter: 2 + + .. grid-item-card:: :octicon:`book;10em` + :link: https://projectpythia.org/radar-cookbook + :link-type: doc + :text-align: center + + **Radar Cookbook** + + The cookbook provides in-depth information on how + to use Py-ART (and other open radar packages), including how to get started. + This is where to look for general conceptual descriptions on how + to use parts of Py-ART, like its support for corrections and gridding. + + .. 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 Py-ART. 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: dev/index + :link-type: doc + :text-align: center + + **Developer Guide** + + Want to help make Py-ART better? Found something + that's not working quite right? You can find instructions on how to + contribute to Py-ART here. You can also find detailed descriptions on + tools useful for developing Py-ART. + + .. grid-item-card:: :octicon:`graph;10em` + :link: examples/index + :link-type: doc + :text-align: center + + **Example Gallery** + + Check out Py-ART's gallery of examples which contains + sample code demonstrating various parts of Py-ART's functionality. + What is Py-ART? =============== The Python ARM Radar Toolkit, Py-ART, is a Python module containing a