Merge pull request #130 from zmoon/docs

Update docs config

.github/workflows/ci.yml

@@ -45,3 +45,26 @@ jobs:
 
       - name: Test with pytest
         run: pytest -v
+
+  docs:
+    name: Check docs build
+    runs-on: ubuntu-latest
+    if: github.repository == 'noaa-oar-arl/monet'
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python (micromamba)
+        uses: mamba-org/provision-with-micromamba@v15
+        with:
+          environment-file: docs/environment-docs.yml
+          cache-env: true
+
+      - name: linkcheck
+        run: sphinx-build -b linkcheck docs docs/_build/linkcheck
+
+      - name: sphinx-build -W
+        run: sphinx-build -b html -W docs docs/_build/html

.gitignore

@@ -5,6 +5,7 @@
 .DS_Store
 docs/_build/
 monet_xesmf_regrid_file.nc
+docs/api/
 
 
 # Default GitHub .gitignore for Python below:

.readthedocs.yaml

@@ -1,22 +1,16 @@
 version: 2
 
 build:
-  image: latest
+  os: "ubuntu-20.04"
+  tools:
+    python: "mambaforge-4.10"
 
-# Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
 
+conda:
+  environment: docs/environment-docs.yml
+
 formats:
   - epub
   - pdf
-#conda:
-#  environment: docs/environment.yml
-
-# Optionally set the version of Python and requirements required to build your docs
-python:
-  version: 3.6
-  # setup_py_install: false
-
-  install:
-    - requirements: docs/requirements.txt

docs/api.rst

@@ -1,24 +1,123 @@
 
-Get in touch
+Get in Touch
 ------------
 
 Ask questions, suggest features or view source code `on GitHub`_.
 
-If an issue arrises please post on the `GitHub` issues.
+If an issue arrises please post on the
+`GitHub issues <https://github.com/noaa-oar-arl/monet/issues>`__.
 
 
 API
 ---
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. module:: monet
 
-.. toctree::
-    :maxdepth: 4
 
-    source/monet
-    source/modules
+Top-level functions
+~~~~~~~~~~~~~~~~~~~
 
+.. autosummary::
+   :toctree: api/
+   :recursive:
 
-.. _on GitHub: https://github.com/noaa-oar-arl/MONET
+   monet.dataset_to_monet
+   monet.rename_to_monet_latlon
+   monet.rename_latlon
+
+
+Modules
+~~~~~~~
+
+.. autosummary::
+   :toctree: api/
+   :recursive:
+
+   monet.met_funcs
+   monet.plots
+   monet.util
+
+
+.. _xarray-accessors:
+
+DataArray Accessor
+~~~~~~~~~~~~~~~~~~
+
+.. currentmodule:: xarray
+
+.. autosummary::
+   :toctree: api/
+   :template: autosummary/accessor_method.rst
+
+   DataArray.monet.wrap_longitudes
+   DataArray.monet.tidy
+   DataArray.monet.is_land
+   DataArray.monet.is_ocean
+   DataArray.monet.cftime_to_datetime64
+   DataArray.monet.structure_for_monet
+   DataArray.monet.stratify
+   DataArray.monet.window
+   DataArray.monet.interp_constant_lat
+   DataArray.monet.interp_constant_lon
+   DataArray.monet.nearest_ij
+   DataArray.monet.nearest_latlon
+   DataArray.monet.quick_imshow
+   DataArray.monet.quick_map
+   DataArray.monet.quick_contourf
+   DataArray.monet.remap_nearest
+   DataArray.monet.remap_xesmf
+   DataArray.monet.combine_point
+
+
+Dataset Accessor
+~~~~~~~~~~~~~~~~
+
+.. currentmodule:: xarray
+
+.. autosummary::
+   :toctree: api/
+   :template: autosummary/accessor_method.rst
+
+   Dataset.monet.wrap_longitudes
+   Dataset.monet.tidy
+   Dataset.monet.is_land
+   Dataset.monet.is_ocean
+   Dataset.monet.cftime_to_datetime64
+   Dataset.monet.stratify
+   Dataset.monet.window
+   Dataset.monet.interp_constant_lat
+   Dataset.monet.interp_constant_lon
+   Dataset.monet.nearest_ij
+   Dataset.monet.nearest_latlon
+   Dataset.monet.remap_nearest
+   Dataset.monet.remap_nearest_unstructured
+   Dataset.monet.remap_xesmf
+   Dataset.monet.combine_point
+
+
+.. _pandas-accessors:
+
+DataFrame Accessor
+~~~~~~~~~~~~~~~~~~
+
+.. currentmodule:: pandas
+
+.. autosummary::
+   :toctree: api/
+   :template: autosummary/accessor_method.rst
+
+   DataFrame.monet.to_ascii2nc_df
+   DataFrame.monet.to_ascii2nc_list
+   DataFrame.monet.rename_for_monet
+   DataFrame.monet.get_sparse_SwathDefinition
+   DataFrame.monet.remap_nearest
+   DataFrame.monet.cftime_to_datetime64
+
+.. autosummary::
+   :toctree: api/
+   :template: autosummary/accessor_attribute.rst
+
+   DataFrame.monet.center
+
+
+.. _on GitHub: https://github.com/noaa-oar-arl/monet

docs/conf.py

@@ -15,6 +15,8 @@
 import sys
 from unittest.mock import MagicMock
 
+import sphinx_autosummary_accessors
+
 
 class Mock(MagicMock):
     @classmethod
@@ -50,22 +52,43 @@ def __getattr__(cls, name):
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinx_autosummary_accessors",
 ]
 # exclude_patterns = ['_build', '**.ipynb_checkpoints']
 
 extlinks = {
-    "issue": ("https://github.com/noaa-oar-arl/MONET/issues/%s", "GH"),
-    "pull": ("https://github.com/noaa-oar-arl/MONET/pull/%s", "PR"),
+    "issue": ("https://github.com/noaa-oar-arl/monet/issues/%s", "GH"),
+    "pull": ("https://github.com/noaa-oar-arl/monet/pull/%s", "PR"),
 }
 
-autosummary_generate = True
+autosummary_generate = True  # default in Sphinx v4
+autodoc_default_options = {
+    "members": True,
+    "special-members": "__init__",
+}
+autodoc_member_order = "groupwise"
 numpydoc_class_members_toctree = True
 napoleon_google_docstring = False
 napoleon_use_param = False
 napoleon_use_ivar = False  # True
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "xarray": ("https://docs.xarray.dev/en/stable/", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "monetio": ("https://monetio.readthedocs.io/en/stable/", None),
+}
+
+
+linkcheck_ignore = [
+    "https://glossary.ametsoc.org/wiki/",  # currently a cert issue
+    "https://doi.org/10.1029/2000WR900033",  # 403 at Wiley
+]
+
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+templates_path = ["_templates", sphinx_autosummary_accessors.templates_path]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:

docs/environment-docs.yml

@@ -0,0 +1,33 @@
+name: monet-docs
+channels:
+  - conda-forge
+  - nodefaults
+dependencies:
+  - python=3.9
+  - ipykernel
+  - ipython
+  #
+  # core
+  - cartopy
+  - dask
+  - matplotlib
+  - netcdf4
+  - numpy
+  - pandas>=1.0
+  - pydecorate
+  - seaborn
+  - xarray
+  #
+  # optional
+  - pyresample
+  #
+  # docs
+  - nbsphinx
+  - sphinx=4.*
+  - sphinx-autobuild
+  - sphinx-autosummary-accessors
+  - sphinx_rtd_theme>=0.4
+  #
+  - pip>=21.1
+  - pip:
+      - "-e ../"