Add documentation build script, fix build warning, and update docs on building docs

.readthedocs.yaml

@@ -22,29 +22,20 @@ build:
     create_environment:
       # Pin micromamba
       - /bin/bash --login -c "micromamba self-update --version 2.0.7"
-      # Create the env for building the docs
-      - /bin/bash --login -c "micromamba env create -n jupytergis-docs -f docs/environment-docs.yml"
       # Create the isolated env for building JupyterGIS
       - /bin/bash --login -c "micromamba create -n jupytergis-build -c conda-forge nodejs hatch pip python=3.13"
       - /bin/bash --login -c "micromamba run -n jupytergis-build pip install 'jupyterlab==4.3' 'datamodel-code-generator>=0.23.0'"
+      # Build JupyterGIS Javascript packages; required for building the docs env
+      - /bin/bash --login -c "micromamba run -n jupytergis-build jlpm install"
+      - /bin/bash --login -c "micromamba run -n jupytergis-build jlpm build"
+      - /bin/bash --login -c "micromamba run -n jupytergis-build jlpm build:packages"
+      # Create the env for building the docs
+      - /bin/bash --login -c "micromamba env create -n jupytergis-docs -f docs/environment-docs.yml"
 
     # Override the install step to do nothing - we already created the envs
     install:
       - "echo 'Skipping! We already have the environments we need.'"
 
-    # Before building the docs, build JupyterGIS in its isolated environment,
-    # then install the wheels into the docs environment.
-    pre_build:
-      - /bin/bash --login -c "micromamba run -n jupytergis-build jlpm install"
-      - /bin/bash --login -c "micromamba run -n jupytergis-build jlpm build"
-      - /bin/bash --login -c "micromamba run -n jupytergis-build jlpm build:packages"
-      - |-
-        /bin/bash --login -c "micromamba run -n jupytergis-docs \
-          python -m pip install \
-          $(ls ./python/jupytergis_core/dist/jupytergis*.whl) \
-          $(ls ./python/jupytergis_lab/dist/jupytergis*.whl) \
-          $(ls ./python/jupytergis_qgis/dist/jupytergis*.whl)"
-
     build:
       html:
         - |-

docs/build.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+THIS_DIR="$( cd "$(dirname "$0")"; pwd -P )"
+
+# Build can fail if certain artifacts exist here:
+rm -rf "${THIS_DIR}/_build"
+
+python -m sphinx \
+    --nitpicky --show-traceback \
+    --fail-on-warning --keep-going \
+    --builder html --doctree-dir _build/doctrees --define language=en \
+   . \
+   ./_build/html

docs/contributor_guide/docs.md

@@ -1,8 +1,24 @@
 # Building JupyterGIS documentation locally
 
-To install a conda environment with **([Micromamba](https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html))**, run the following command inside `docs/`:
+:::{important}
+Navigate to the `docs/` directory before starting any of these steps!
+:::
 
-## 1. Create the environment from `environment-docs.yml`
+:::{tip}
+You can use `conda` or `mamba` as drop-in replacements for `micromamba` in the steps
+below, but they will not be as fast.
+:::
+
+## 0. Build JupyterGIS JavaScript packages
+
+Follow the [development environment setup instructions](./development_setup.rst).
+From the root of the repo, run `jlpm build`.
+
+## 1. Create the docs environment from `environment-docs.yml`
+
+:::{important}
+Ensure all other environments are deactivated first!
+:::
 
 ```
 micromamba create -f environment-docs.yml
@@ -16,24 +32,24 @@ micromamba activate jupytergis-docs
 
 ## 3. Build the documentation
 
+:::{note}
+You may experience failure at this step. Carefully read the last message. Did the build
+fail due to warnings? You may need to search the full log output for "WARNING" to find
+the cause.
+:::
+
 ```
-make html
+./build.sh
 ```
 
 ## 4. Open the documentation
 
-Once the build is complete, open:
+Once the build is successful, open:
 
 ```
-docs/build/index.html
+_build/html/index.html
 ```
 
-## 5. Make changes and rebuild
-
-After making docs edits, rerun:
-
-```
-make html
-```
+## 5. Repeat!
 
-to regenerate the updated documentation.
+Every time you make edits to documentation, repeat steps 3 and 4.

docs/environment-docs.yml

@@ -4,7 +4,6 @@ channels:
   - nodefaults
 dependencies:
   - python=3.12
-  - pip # Needed to install jupytergis wheels in RTD build
 
   # Build docs & JupyterLite
   - jupyterlite-core
@@ -18,3 +17,11 @@ dependencies:
   - sphinx-togglebutton
   - myst-parser
   - xeus-python # TODO: Do we need this?
+
+  - pip
+  - pip:
+      # Install JupyterGIS so we can autodoc.
+      # IMPORTANT: You must do `jlpm build` at the root of the repo before this can work.
+      # See: https://github.com/geojupyter/jupytergis/issues/585
+      - ../python/jupytergis_core
+      - ../python/jupytergis_lab