STY: Update docs template to PyData theme

.github/workflows/python-package.yml

@@ -20,7 +20,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.9", "3.10"]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
         os: [macOS, ubuntu, Windows]
 
     steps:

.gitignore

@@ -5,3 +5,4 @@ __pycache__
 .idea
 *.pyc
 *.pyx
+docs/build

docs/environment_docs.yml

@@ -0,0 +1,14 @@
+name: pysp2-docs
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - act-atmos
+  - xarray
+  - pip:
+      - sphinx
+      - sphinx_gallery
+      - sphinx-copybutton
+      - pydata-sphinx-theme<0.9.0
+      - sphinx_design
+      - nbsphinx

docs/source/_static/default.css

@@ -0,0 +1,146 @@
+/* ACT 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;
+ }
+
+ :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;
+}
+
+ /* 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;
+ }
+
+ .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;
+ }
+
+ .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;
+ }

docs/source/_static/doc_shared.js

@@ -0,0 +1,12 @@
+const project = "ACT";
+
+// 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);
+        }
+    })
+ })

docs/source/_templates/autosummary/base.rst

@@ -0,0 +1,5 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/source/_templates/autosummary/class.rst

@@ -0,0 +1,33 @@
+{% extends "!autosummary/class.rst" %}
+
+{% block methods %}
+{% if methods %}
+.. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+
+.. autosummary::
+   :toctree:
+
+{% for item in all_methods %}
+{%- if not item.startswith('_') or item in ['__call__'] %}
+   ~{{ name }}.{{ item }}
+{%- endif -%}
+{%- endfor %}
+
+{% endif %}
+{% endblock %}
+
+{% block attributes %}
+{% if attributes %}
+.. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+
+.. autosummary::
+   :toctree:
+
+{% for item in all_attributes %}
+{%- if not item.startswith('_') %}
+   ~{{ name }}.{{ item }}
+{%- endif -%}
+
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/source/_templates/autosummary/module.rst

@@ -0,0 +1,29 @@
+{{ fullname | escape | underline }}
+
+.. rubric:: Description
+
+.. automodule:: {{ fullname }}
+
+.. currentmodule:: {{ fullname }}
+
+{% if classes %}
+.. rubric:: Classes
+
+.. autosummary::
+    :toctree: .
+    {% for class in classes %}
+    {{ class }}
+    {% endfor %}
+
+{% endif %}
+
+{% if functions %}
+.. rubric:: Functions
+
+.. autosummary::
+    :toctree: .
+    {% for function in functions %}
+    {{ function }}
+    {% endfor %}
+
+{% endif %}

docs/source/_templates/dev_template.rst

@@ -0,0 +1,32 @@
+{% extends "!autosummary/class.rst" %}
+{% block methods %}
+{% if methods %}
+   .. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
+      .. autosummary::
+         :toctree:
+      {% for item in all_methods %}
+         {%- if not item.startswith('_') or item in ['__call__'] %}
+         {{ name }}.{{ item }}
+         {%- endif -%}
+      {%- endfor %}
+
+   |
+
+   **Private methods**
+
+   .. autosummary::
+       :toctree:
+
+    {% for item in all_methods %}
+         {%- if item.startswith('_') %}
+         ~{{ name }}.{{ item }}
+         {%- endif -%}
+      {%- endfor %}
+
+   {% endif %}
+{% endblock %}
+
+{% block attributes %}
+{% if attributes %}
+{% endif %}
+{% endblock %}

docs/source/_templates/layout.html

@@ -0,0 +1,17 @@
+{% extends "!layout.html" %}
+
+{% block fonts %}
+<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 docs_navbar %}
+  <nav class="navbar navbar-dark navbar-expand-lg bg-arm fixed-top bd-navbar shadow" id="navbar-main">
+    {%- include "docs-navbar.html" %}
+  </nav>
+
+{# Added to support a banner with an alert #}
+    <div class="container-fluid" id="banner"></div>
+{% endblock %}

docs/source/conf.py

@@ -42,8 +42,10 @@
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
-    'numpydoc',
+    'sphinx.ext.napoleon',
     'sphinx.ext.autosummary',
+    'sphinx_copybutton',
+    'sphinx_design',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -59,14 +61,40 @@
     'gallery_dirs': 'source/auto_examples'
 }
 
+# Generate the API documentation when building
+autoclass_content = 'both'
+autosummary_generate = True
+autosummary_imported_members = True
+
+# Otherwise, the Return parameter list looks different from the Parameter list
+napoleon_use_rtype = False
+napoleon_use_ivar = True
+napoleon_include_init_with_doc = False
+napoleon_use_param = False
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'pydata_sphinx_theme'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+
+html_css_files = ['default.css']
+
+html_js_files = ['doc_shared.js']
+
+html_sidebars = {
+    'contributors_guide': ['searchbox.html', 'sidebar-nav-bs.html'],
+    'developers_guide': ['searchbox.html', 'sidebar-nav-bs.html'],
+    'users_guide': ['searchbox.html', 'sidebar-nav-bs.html'],
+    'examples': ['searchbox.html', 'sidebar-nav-bs.html'],
+    'notebook-gallery': ['searchbox.html', 'sidebar-nav-bs.html']}
+