Add a custom environment file for building docs on CI (#626)

Change how we install packages to build docs in Actions: instead of
gathering the dependencies from the requirements files, create a new
environment file that used only for that purpose. This removes the need
to rename some packages that have different names in PyPI and Conda
(like `build` and `python-build`), and also allows us to have more
control over pinned versions of some packages, specially if some new
version broke something in our workflow.

Author: santisoler

.github/environment.yml

@@ -0,0 +1,42 @@
+# Conda environment to build the docs in Actions.
+# Don't use this environment for development. This environment is solely used
+# by GitHub Actions to create an environment to build the documentation that
+# gets pushed to GitHub Pages.
+name: harmonica-docs
+channels:
+  - conda-forge
+dependencies:
+  - numpy>=1.23
+  - pandas>=1.4
+  - scipy>=1.9
+  - scikit-learn>=1.1
+  - numba>=0.57
+  - xarray>=2022.03
+  - verde>=1.8.1
+  - xrft>=1.0
+  - choclo>=0.1
+  - boule>=0.4.1
+  # Build
+  - python-build
+  - twine
+  # Docs
+  - sphinx==7.2.*
+  - numpydoc==1.7.*
+  - sphinx-book-theme==1.1.*
+  - sphinx-gallery==0.15.*
+  - sphinx-design==0.5.*
+  - sphinx-copybutton==0.5.*
+  - jupyter-sphinx==0.5.*
+  - ipykernel
+  - boule
+  - pyproj
+  - ensaio>=0.5.*
+  - netcdf4
+  - matplotlib
+  - pyvista
+  - vtk==9.4.*
+  - pygmt
+  - gmt
+  - gdal
+  - ipykernel
+  - trame

.github/workflows/docs.yml

@@ -35,7 +35,6 @@ jobs:
   build:
     runs-on: ubuntu-latest
     env:
-      REQUIREMENTS: env/requirements-build.txt env/requirements-docs.txt
       PYTHON: "3.12"
       ENSAIO_DATA_FROM_GITHUB: true
 
@@ -58,47 +57,21 @@ jobs:
       - name: Fetch git tags
         run: git fetch origin 'refs/tags/*:refs/tags/*'
 
+      - name: Setup caching for conda packages
+        uses: actions/cache@v5
+        with:
+          path: ~/conda_pkgs_dir
+          key: conda-${{ env.PYTHON }}-${{ hashFiles('.github/environment.yml') }}
+
       - name: Setup Miniforge
         uses: conda-incubator/setup-miniconda@835234971496cad1653abb28a638a281cf32541f
         with:
           python-version: ${{ env.PYTHON }}
           miniforge-version: latest
           channels: conda-forge
           conda-remove-defaults: "true"
-
-      - name: Collect requirements
-        run: |
-          echo "Install Dependente to capture dependencies:"
-          conda install dependente==0.3.0 -c conda-forge
-          echo ""
-          echo "Capturing run-time dependencies:"
-          dependente --source install > requirements-full.txt
-          echo "Capturing dependencies from:"
-          for requirement in $REQUIREMENTS
-          do
-            echo "  $requirement"
-            cat $requirement >> requirements-full.txt
-          done
-          echo ""
-          echo "Collected dependencies:"
-          cat requirements-full.txt
-
-      - name: Rename conda-forge packages
-        run: |
-          echo "Rename conda-forge packages in requirements-full.txt"
-          # Replace "build" for "python-build"
-          sed -s --in-place 's/^build$/python-build/' requirements-full.txt
-          echo "Renamed dependencies:"
-          cat requirements-full.txt
-
-      - name: Setup caching for conda packages
-        uses: actions/cache@v5
-        with:
-          path: ~/conda_pkgs_dir
-          key: conda-${{ runner.os }}-${{ env.PYTHON }}-${{ hashFiles('requirements-full.txt') }}
-
-      - name: Install requirements
-        run: conda install --quiet --file requirements-full.txt python=$PYTHON
+          activate-environment: harmonica-docs
+          environment-file: .github/environment.yml
 
       - name: List installed packages
         run: conda list