Documentation API description

.github/workflows/documentation.yaml

@@ -1,5 +1,5 @@
 name: Docs
-on: [push, pull_request, workflow_dispatch]
+on: [pull_request, workflow_dispatch]
 permissions:
     contents: write
 jobs:
@@ -8,9 +8,47 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v3
-      - name: Install dependencies
+
+      - name: Set up Conda Environment
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          activate-environment: "pcmdi_metrics_dev"
+          miniforge-variant: Mambaforge
+          miniforge-version: latest
+          use-mamba: true
+          mamba-version: "*"
+          channel-priority: strict
+          auto-update-conda: true
+
+      # Used for refreshing the cache every 24 hours to avoid inconsistencies of package
+      # versions between the CI pipeline and local installations.
+      - name: Get Date
+        id: get-date
+        run: echo "today=$(/bin/date -u '+%Y%m%d')" >> $GITHUB_OUTPUT
+        shell: bash
+
+      - name: Cache Conda
+        uses: actions/cache@v3
+        with:
+          path: ${{ env.CONDA }}/envs
+          key:
+            conda-${{ runner.os }}--${{ runner.arch }}--${{
+            steps.get-date.outputs.today }}-${{
+            hashFiles('conda-env/dev.yml') }}-${{ env.CACHE_NUMBER}}
+        env:
+          # Increase this value to reset cache if conda/dev.yml has not changed in the workflow
+          CACHE_NUMBER: 0
+
+      - name: Update environment
+        run:
+          mamba env update -n pcmdi_metrics_dev -f conda-env/dev.yml
+        if: steps.cache.outputs.cache-hit != 'true'
+
+      - name: Install pcmdi_metrics
+        # Source: https://github.com/conda/conda-build/issues/4251#issuecomment-1053460542
         run: |
-          pip install sphinx sphinx_rtd_theme sphinx_book_theme
+            python -m pip install --no-build-isolation --no-deps -e .
+
       - name: Sphinx build
         run: |
           sphinx-build docs _build

conda-env/dev.yml

@@ -45,11 +45,13 @@ dependencies:
     # Documentation
     # ==================
     - sphinx
+    - sphinx-autosummary-accessors
     - sphinx-book-theme
     - sphinx-copybutton
     - sphinx_rtd_theme
     - nbsphinx
     - pandoc
+    - sphinx-design
     - ipython # Required for nbsphinx syntax highlighting
 
 prefix: /opt/miniconda3/envs/pmcdi_metrics_dev

docs/api.rst

@@ -0,0 +1,22 @@
+API Reference
+=============
+
+API Functions for Developpers
+-----------------------------
+
+Below is a list of some API functions that are available in ``pcmdi_metrics.utils`` for developpers.
+
+.. autosummary::
+    :toctree: generated/
+
+    check_daily_time_axis
+    check_monthly_time_axis
+    create_land_sea_mask
+    apply_landmask
+    apply_oceanmask
+    regrid
+
+.. automodule:: pcmdi_metrics.utils
+   :members: check_daily_time_axis, check_monthly_time_axis, create_land_sea_mask, apply_landmask, apply_oceanmask, regrid
+   :undoc-members:
+   :show-inheritance:

docs/conf.py

@@ -13,13 +13,19 @@
 import os
 sys.path.insert(0, os.path.abspath('../pcmdi_metrics/utils'))
 
-# import sphinx_autosummary_accessors
+import sphinx_autosummary_accessors
+from sphinx.application import Sphinx
+from sphinx.util import logging
 
-# -- Project information -----------------------------------------------------
+LOGGER = logging.getLogger("conf")
+
+import pcmdi_metrics
 
-project = 'PCMDI Metrics Package'
-copyright = '2024 PCMDI'
-author = 'PCMDI'
+# -- Project information -----------------------------------------------------
+# General information about the project.
+project = "PCMDI Metrics Package (PMP)"
+copyright = "2024, PMP Developers"
+author = "PMP Developers"
 
 # The version info for the project you're documenting, acts as replacement
 # for |version| and |release|, also used in various other places throughout
@@ -36,19 +42,29 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx_rtd_theme', 'sphinx.ext.napoleon']
+#extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx_rtd_theme', 'sphinx.ext.napoleon']
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx_autosummary_accessors",
+    "sphinx_copybutton",
+    "sphinx_rtd_theme",
+    "nbsphinx",
+    "sphinx_design",
+]
 
 # autosummary and autodoc configurations
-# autosummary_generate = True
-"""
+autosummary_generate = True
+
 autodoc_member_order = "bysource"
 autodoc_default_options = {
     "members": True,
     "undoc-members": True,
     "private-members": True,
 }
 autodoc_typehints = "none"
-"""
 
 # Napoleon configurations
 napoleon_google_docstring = False
@@ -57,9 +73,13 @@
 napoleon_use_rtype = False
 napoleon_preprocess_types = True
 
+# sphinx-copybutton configurations
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True
+
 # Add any paths that contain templates here, relative to this directory.
-# templates_path = ['_templates', sphinx_autosummary_accessors.templates_path]
-templates_path = ['_templates']
+templates_path = ["_templates", sphinx_autosummary_accessors.templates_path]
+# templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -80,7 +100,12 @@
 # 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 = []
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "demos/1-25-23-cwss-seminar/xsearch-xcdat-example.ipynb",
+]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'

docs/resources.rst

@@ -7,5 +7,5 @@ Resources
 .. toctree::
    :maxdepth: 1
 
-   utils
-   resources_legacy
+   api
+   resources_legacy