Resolve docs warnings (#1367)

* lexer ipython2 -> ipython3

to address these warnings:

uxarray/docs/getting-started/quick-overview.ipynb:20002: WARNING: Pygments lexer name 'ipython2' is not known

also removed `|` from end of heading

* navbar_footer_text unsupported

maybe from Furo?

WARNING: unsupported theme option 'navbar_footer_text' given

* Suppress unknown MIME type warning

otherwise we get a lot of these from the HoloViews plots

For example:

uxarray/docs/getting-started/quick-overview.ipynb:150002: WARNING: skipping unknown output mime type: application/vnd.holoviews_load.v0+json [mystnb.unknown_mime_type] [mystnb.unknown_mime_type]

* Resolve not included in toctree

docs/contributing.rst: WARNING: document isn't included in any toctree
docs/examples/template.ipynb: WARNING: document isn't included in any toctree
docs/user-guide/custom-grid.ipynb: WARNING: document isn't included in any toctree
docs/user-guide/spatial-hashing.ipynb: WARNING: document isn't included in any toctree
docs/user-guide/template.ipynb: WARNING: document isn't included in any toctree

* api.rst

for example:

docs/api.rst:180: WARNING: Title underline too short.

* contributing.rst

uxarray/docs/contributing.rst:518: WARNING: Bullet list ends without a blank line; unexpected unindent. [docutils]
docs/contributing.rst:544: WARNING: Bullet list ends without a blank line; unexpect
uxarray/docs/contributing.rst:70: WARNING: Failed to create a cross reference. A title or caption not found: 'examples' [ref.ref]
uxarray/docs/contributing.rst:604: WARNING: undefined label: 'index' [ref.ref]

* Fix warnings in docstrings

mainly bullet list issue

* Add title (h1) to gradients nb

uxarray/docs/user-guide/gradients.ipynb.rst:10002: WARNING: Document headings start at H2, not H1 [myst.header]

* Switch to tip

as it was, they were just not showing up

docs/user-guide/data-structures.ipynb.rst:280008: WARNING: Unknown directive type: 'info' [myst.directive_unknown]
docs/user-guide/data-structures.ipynb.rst:370008: WARNING: Unknown directive type: 'info' [myst.directive_unknown]
https://myst-parser.readthedocs.io/en/stable/syntax/admonitions.html#admonition-types

* this one too

* Add holoviews mime note

* sp

* Fix part 7 heading

* Fix the open docstring examples

* Fix other non-consec heading increases

Author: zmoon

docs/api.rst

@@ -177,7 +177,7 @@ Constructors
    UxDataArray.from_healpix
 
 Grid Accessor
-~~~~~~~~~~~
+~~~~~~~~~~~~~
 
 .. autosummary::
    :toctree: generated/
@@ -200,7 +200,7 @@ Constructors
    UxDataset.from_healpix
 
 Grid Accessor
-~~~~~~~~~~~
+~~~~~~~~~~~~~
 
 .. autosummary::
    :toctree: generated/

docs/conf.py

@@ -61,6 +61,11 @@ def __getattr__(cls, name):
     "sphinx_copybutton",
 ]
 
+suppress_warnings = [
+    # mystnb doesn't recognize MIME type 'application/vnd.holoviews_load.v0+json'
+    # from the holoviews plots and otherwise spams the build with warnings
+    "mystnb.unknown_mime_type",
+]
 
 # nbsphinx_execute = "never"
 # jupyter_execute_notebooks = "off"
@@ -137,7 +142,15 @@ def __getattr__(cls, name):
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "**.ipynb_checkpoints"]
+exclude_patterns = [
+    "_build",
+    "**.ipynb_checkpoints",
+    # Not included (yet)
+    "examples/template.ipynb",
+    "user-guide/custom-grid.ipynb",
+    "user-guide/spatial-hashing.ipynb",
+    "user-guide/template.ipynb",
+]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
@@ -173,7 +186,7 @@ def __getattr__(cls, name):
     "use_repository_button": True,
     "use_issues_button": True,
     "home_page_in_toc": False,
-    "navbar_footer_text": "",
+    # "navbar_footer_text": "",
     # "extra_footer": "<p></p>",
     "logo": {
         "image_light": "_static/images/logos/uxarray_logo_h_dark.svg",

docs/contributing.rst

@@ -69,8 +69,9 @@ Some important UXarray resources are as follows:
 
 * `UXarray documentation <https://uxarray.readthedocs.io/>`_
   houses significant documentation such as :ref:`quickstart`, :ref:`installation`,
-  :ref:`contributing` (i.e. this document), :ref:`examples`, :ref:`tutorials`,
-  and :ref:`api`.
+  :ref:`contributing` (i.e. this document),
+  examples (:ref:`gallery` or :ref:`userguide`),
+  :ref:`tutorials`, and :ref:`api`.
 
 * `UXarray Milestones <https://github.com/UXARRAY/uxarray/milestones>`_ and
   `UXarray Roadmap <https://github.com/orgs/UXARRAY/projects/2/views/17>`_ shows
@@ -515,24 +516,24 @@ as follows:
   into your Conda environment for UXarray development).
 
 * Test scripts themselves are not intended to use ``pytest`` through implementation.
-Instead, ``pytest`` should be used only for running test scripts as follows::
+  Instead, ``pytest`` should be used only for running test scripts as follows::
 
     $ pytest test/<test_script_name>.py
 
-, or::
+  , or::
 
     $ python -m pytest test/<test_script_name>.py
 
-, the latter of which will also add the current directory to ``sys.path``.
+  , the latter of which will also add the current directory to ``sys.path``.
 
-Not using ``pytest`` for implementation allows the unit tests to be also run
-by using (a number of benefits/conveniences coming from using ``pytest`` can be
-seen `here <https://docs.pytest.org/en/7.1.x/how-to/unittest.html#how-to-use-unittest-based-tests-with-pytest>`_
-though)::
+  Not using ``pytest`` for implementation allows the unit tests to be also run
+  by using (a number of benefits/conveniences coming from using ``pytest`` can be
+  seen `here <https://docs.pytest.org/en/7.1.x/how-to/unittest.html#how-to-use-unittest-based-tests-with-pytest>`_
+  though)::
 
     $ python -m unittest test/<test_script_name>.py
 
-Also, all of the test scripts can be run at once with the following command::
+  Also, all of the test scripts can be run at once with the following command::
 
     $ pytest test
 
@@ -541,7 +542,7 @@ Also, all of the test scripts can be run at once with the following command::
   the test scripts.
 
 * Reference results (i.e. expected output or ground truth for not all but the most cases)
-should not be magic values (i.e. they need to be justified and/or documented).
+  should not be magic values (i.e. they need to be justified and/or documented).
 
 * Recommended, but not mandatory, implementation approach is as follows:
 
@@ -602,7 +603,7 @@ The docstrings must contain:
 ~~~~~~~~~~~~~~~~~~~~~~
 
 As we mentioned a few times throughout this guide, UXarray has a static `documentation
-<https://uxarray.readthedocs.io/>`_ :ref:`index` page that is being generated automatically from the
+<https://uxarray.readthedocs.io/>`_ page that is being generated automatically from the
 repository's code structure. However, there needs to be some manual additions to the
 proper documentation index file(s) for the automation to work.
 

docs/gallery.rst

@@ -1,8 +1,6 @@
 .. currentmodule:: uxarray
 
-.. _examples:
-
-.. math::
+.. _gallery:
 
 Gallery
 =======

docs/getting-started/quick-overview.ipynb

@@ -52,7 +52,7 @@
     "collapsed": false
    },
    "source": [
-    "## Opening a Dataset|"
+    "## Opening a Dataset"
    ]
   },
   {
@@ -322,7 +322,7 @@
    "mimetype": "text/x-python",
    "name": "python",
    "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython2",
+   "pygments_lexer": "ipython3",
    "version": "2.7.6"
   }
  },

docs/index.rst

@@ -112,6 +112,7 @@ around the `UGRID <http://ugrid-conventions.github.io/ugrid-conventions/>`_ conv
     GitHub Discussions <https://github.com/UXARRAY/uxarray/discussions>
     GitHub Issues <https://github.com/UXARRAY/uxarray/issues>
     UGRID Conventions <https://ugrid-conventions.github.io/ugrid-conventions/>
+    contributing
 
 .. raw:: html
 

docs/user-guide/advanced-plotting.ipynb

@@ -48,7 +48,7 @@
    "mimetype": "text/x-python",
    "name": "python",
    "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython2",
+   "pygments_lexer": "ipython3",
    "version": "2.7.6"
   }
  },

docs/user-guide/area_calc.ipynb

@@ -1843,7 +1843,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# 7. Demonstrate the Need for Area Correction During Zonal Averaging Calculations Etc.\n",
+    "## 7. Demonstrate the Need for Area Correction During Zonal Averaging Calculations Etc.\n",
     "\n",
     "When performing zonal averaging, it is common practice to calculate the intersection of faces with lines of constant latitude and longitude. \n",
     "\n",

docs/user-guide/data-structures.ipynb

@@ -410,7 +410,7 @@
     "\n",
     "The `UxDataset` class is used for pairing one or more data variables with an unstructured grid. It operates similarly to a `xarrary.Dataset`, with the addition of unstructured-grid specific functionality and is linked to an instance of a `Grid`.\n",
     "\n",
-    "```{info}\n",
+    "```{tip}\n",
     "More information about `xarray.Dataset` can be found [here](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html).\n",
     "```\n"
    ]
@@ -544,7 +544,7 @@
     "\n",
     "While a `UxDataset` represents one or more data variables linked to some unstructured grid, a `UxDataArray` represent a single data variable. Alternatively, one can think of a `UxDataset` as a collection of one or more `UxDataArray` instances.\n",
     "\n",
-    "```{info}\n",
+    "```{tip}\n",
     "More information about `xarray.DataArray` can be found [here](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html).\n",
     "```\n",
     "\n",

docs/user-guide/gradients.ipynb

@@ -5,6 +5,8 @@
    "id": "c51bdab8875e6859",
    "metadata": {},
    "source": [
+    "# Gradients\n",
+    "\n",
     "## Gradients\n",
     "\n",
     "This user-guide notebook showcases how to compute the gradient of a data variable."