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 sphinx_autosummary_accessors sphinx-copybutton sphinx-design nbsphinx
+            python -m pip install --no-build-isolation --no-deps -e .
+
       - name: Sphinx build
         run: |
           sphinx-build docs _build