Build docs and Lite deployment in ReadTheDocs (#275)

* [WIP] Attempt RTD build

* Try building for RTD in an isolated environment

* Restore docs/environment.yml, move docs dependencies to new file

* Upgrade the versions of conda and mamba in RTD build

* 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/

* Add JupyterLite badge and link to docs

* Automate exposing RTD preview link in PR description

Makes viewing PR previews more accessible!

* Make the RTD PR preview link richer

* Ignore the JupyterLite link in the link check automation

* Switch bash commands in YAML from folded to literal blocks

This feels significantly more intuitive to me.

* Format YAML

---------

Co-authored-by: Nicolas Brichet <[email protected]>

.github/workflows/build.yml

@@ -242,6 +242,8 @@ jobs:
       - uses: actions/checkout@v4
       - uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
       - uses: jupyterlab/maintainer-tools/.github/actions/check-links@v1
+        with:
+          ignore_links: 'lite/'
 
   build-docs-and-lite:
     name: Build docs with JupyterLite deployment
@@ -294,11 +296,6 @@ jobs:
           path: ./docs/dist
           retention-days: 30
 
-      - name: Save artifact data
-        uses: trungleduc/appsharingspace-pr-comment/.github/actions/save-artifact-link@v2
-        with:
-          artifact_link: 'https://github.com/${{ github.repository }}/actions/runs/${{github.run_id}}/artifacts/${{ steps.upload-docs-artifact.outputs.artifact_id }}'
-
   deploy:
     needs: build-docs-and-lite
     if: github.ref == 'refs/heads/main'

.github/workflows/comment-on-pr.yml

@@ -10,30 +10,6 @@ permissions:
   pull-requests: write
 
 jobs:
-  comment-preview:
-    runs-on: ubuntu-latest
-    if: >
-      ${{ github.event.workflow_run.event == 'pull_request' &&
-      github.event.workflow_run.conclusion == 'success' }}
-    steps:
-      - name: 'Comment APSS link on workflow'
-        uses: trungleduc/appsharingspace-pr-comment/.github/actions/pr-comment@v2
-        with:
-          comment_prefix: '**Preview using JupyterLite:**'
-          github_token: ${{ secrets.github_token }}
-          index_path: lite/lab/index.html
-  comment-docs-preview:
-    runs-on: ubuntu-latest
-    if: >
-      ${{ github.event.workflow_run.event == 'pull_request' &&
-      github.event.workflow_run.conclusion == 'success' }}
-    steps:
-      - name: 'Comment APSS link on workflow'
-        uses: trungleduc/appsharingspace-pr-comment/.github/actions/pr-comment@v2
-        with:
-          comment_prefix: '**Docs preview:**'
-          github_token: ${{ secrets.github_token }}
-          index_path: index.html
   comment-galata:
     runs-on: ubuntu-latest
     if: >

.github/workflows/pr-rtd-link.yml

@@ -0,0 +1,24 @@
+# The ReadTheDocs preview link is "hidden" within the GitHub "Checks"
+# interface. For users who don't know this, finding the preview link may be
+# very difficult or frustrating. This workflow makes the link more
+# findable by updating PR descriptions to include it.
+name: 'Add ReadTheDocs preview link to PR description'
+
+on:
+  pull_request_target:
+    types:
+      - 'opened'
+
+permissions:
+  pull-requests: 'write'
+
+jobs:
+  autolink-rtd-previews:
+    runs-on: 'ubuntu-latest'
+    steps:
+      - uses: 'readthedocs/actions/preview@v1'
+        with:
+          project-slug: 'jupytergis'
+          message-template: |
+            📚 Documentation preview: {docs-pr-index-url}
+            💡 JupyterLite preview: {docs-pre-index-url}/lite

.readthedocs.yaml

@@ -0,0 +1,53 @@
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+build:
+  os: "ubuntu-24.04"
+  tools:
+    nodejs: "20"
+  jobs:
+    # Install micromamba
+    pre_create_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:
+      - /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"
+
+      - |-
+        /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:
+        - |-
+          /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"

docs/environment-docs.yml

@@ -0,0 +1,18 @@
+name: jupytergis-docs
+channels:
+  - conda-forge
+  - nodefaults
+dependencies:
+  - python=3.10
+  - pip # Needed to install jupytergis wheels in RTD build
+
+  # Build docs & JupyterLite
+  - jupyterlite-core>=0.2.0,<0.3.0
+  - jupyterlite-xeus>=0.1.2,<0.2
+  - jupyterlite-sphinx
+  - sphinx
+  - sphinx-tabs
+  - pydata-sphinx-theme
+  - sphinx-autodoc-typehints
+
+  - xeus-python # TODO: Do we need this?

docs/index.rst

@@ -2,6 +2,10 @@
 JupyterGIS
 ==========
 
+.. image:: https://jupyterlite.rtfd.io/en/latest/_static/badge.svg
+   :alt: Try JupyterGIS now in JupyterLite!
+   :target: lite/
+
 JupyterGIS is a JupyterLab extension for collaborative GIS (Geographical Information System). It is designed to
 allow multiple people to work on the same geospatial project simultaneously, facilitating discussion and collaboration
 around map layers, spatial analyses, and other GIS data being developed.