Use Micromamba instead of one of the out-of-the-box tool options

Creating multiple environments with mamba exposed lots of problems:

* RTD's default machinery expects a single environment YAML file when
  using conda/mamba. Injecting a 2nd environment into the normal build
  process gets confusing.
* Other hidden assumptions in the default RTD build machinery; I don't
  remember all the problems I ran in to, but getting a working build
  required an unsustainable amount of trial-and-error.
* Default-installed mamba is too old to support 'emscripten' platform,
  needs to be upgraded. When upgrading mamba, ran in to a weird issue
  where the build.html step could not find the python interpreter.

It's possible to fully override build steps, but this is an
_undocumented feature_.

See: readthedocs/readthedocs.org#11551

Instead of overriding build steps, perhaps it will be best long-term to
override the entire build with `build.commands`.

See: https://blog.readthedocs.com/build-customization/

Author: mfisher87

.readthedocs.yaml

@@ -4,40 +4,50 @@ version: 2
 build:
   os: "ubuntu-24.04"
   tools:
-    # https://docs.readthedocs.io/en/stable/config-file/v2.html#build-tools-python
-    python: "mambaforge-latest"
     nodejs: "20"
   jobs:
-    # We need new versions to support the 'emscripten' platform
+    # Install micromamba
     pre_create_environment:
-      - conda install -n base -c conda-forge "conda>=24.11.2"
-    # Before building the docs, build JupyterGIS in an isolated environment,
+      # The recommended syntax in the micromamba docs is process substitution.
+      # RTD's default shell chokes on it, so we're doing it in multiple steps
+      # instead.
+      - curl -L micro.mamba.pm/install.sh > /tmp/micromamba-install.sh
+      - chmod +x /tmp/micromamba-install.sh
+      # For some reason, SHELL is not set. The install script requires it.
+      - SHELL=/bin/bash /bin/bash /tmp/micromamba-install.sh
+
+    # Override the create_environment step (undocumented feature) to create
+    # multiple environments.
+    create_environment:
+      # 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 yarn=3 hatch pip python=3.10"
+      - /bin/bash --login -c "micromamba run -n jupytergis-build pip install -r requirements-build.txt"
+
+    # 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:
-      - mamba create -n jupytergis-build -c conda-forge yarn=3 hatch pip python=3.10
-      - mamba run -n jupytergis-build pip install -r requirements-build.txt
-      - mamba run -n jupytergis-build yarn install
-      - mamba run -n jupytergis-build yarn dev
-      - mamba run -n jupytergis-build jupyter labextension list 2>&1 | grep -ie "jupytergis-core.*OK"
-      - mamba run -n jupytergis-build jupyter labextension list 2>&1 | grep -ie "jupytergis-lab.*OK"
+      - /bin/bash --login -c "micromamba run -n jupytergis-build yarn install"
+      - /bin/bash --login -c "micromamba run -n jupytergis-build yarn dev"
+      - /bin/bash --login -c "micromamba run -n jupytergis-build jupyter labextension list 2>&1 | grep -ie 'jupytergis-core.*OK'"
+      - /bin/bash --login -c "micromamba run -n jupytergis-build jupyter labextension list 2>&1 | grep -ie 'jupytergis-lab.*OK'"
+      - /bin/bash --login -c "micromamba run -n jupytergis-build yarn build:packages"
 
-      - mamba run -n jupytergis-build yarn build:packages
-
-      # Install the wheels into the main docs environment, which is activated
-      # automatically:
       - >-
+        /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)
-
-
-sphinx:
-  configuration: "docs/conf.py"
-  # There doesn't seem to be a way to turn on nitpicky mode.
-  # This is equivalent to `-W --keep-going`.
-  # TODO: Enable after merging https://github.com/geojupyter/jupytergis/pull/273/
-  # fail_on_warning: True
+        $(ls ./python/jupytergis_qgis/dist/jupytergis*.whl)"
 
-conda:
-  environment: "docs/environment-docs.yml"
+    build:
+      html:
+        - >-
+          /bin/bash --login -c "cd docs && micromamba run -n jupytergis-docs
+          python -m sphinx -T -b html -d _build/doctrees -D language=en .
+          $READTHEDOCS_OUTPUT/html"