Build docs and Lite deployment in ReadTheDocs

.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.