Create new top-level "overview" section in docs, note lack of collab support in JupyterLite (geojupyter#921)

mfisher87 · nakul-py · commit 043da2e4d42c · 2025-11-05T15:52:14.000+05:30
diff --git a/docs/build-on-change.sh b/docs/build-on-change.sh
@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# NOTE: Requires `inotify-tools`. e.g. `apt install inotify-tools`.
+# TODO: MacOS support?
+set -euo pipefail
+
+THIS_DIR="$( cd "$(dirname "$0")"; pwd -P )"
+cd "${THIS_DIR}"
+HTML_PATH="./_build/html/index.html"
+
+${THIS_DIR}/clean.sh
+
+set +e
+${THIS_DIR}/build.sh
+xdg-open "${HTML_PATH}"
+set -e
+
+while inotifywait -e delete -e create -e close_write -r ${THIS_DIR}; do
+    ${THIS_DIR}/clean.sh
+
+    set +e
+    ${THIS_DIR}/build.sh
+    set -e
+done
diff --git a/docs/build.sh b/docs/build.sh
@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
+set -euo pipefail
 
 THIS_DIR="$( cd "$(dirname "$0")"; pwd -P )"
 
 # Build can fail if certain artifacts exist here:
-rm -rf "${THIS_DIR}/_build"
+${THIS_DIR}/clean.sh
 
 python -m sphinx \
     --nitpicky --show-traceback \
diff --git a/docs/clean.sh b/docs/clean.sh
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+THIS_DIR="$( cd "$(dirname "$0")"; pwd -P )"
+rm -rf "${THIS_DIR}/_build"
diff --git a/docs/contributor_guide/index.md b/docs/contributor_guide/index.md
@@ -2,6 +2,11 @@
 
 We're thrilled you're ready to contribute to JupyterGIS!
 
+This documentation will help you get started with the technical aspects of contribution
+to this project.
+To learn more about the social aspects (meeting notes, policies, roles), please view the
+[GeoJupyter team compass](https://compass.geojupyter.org/).
+
 To chat with other contributors, please
 [join us on Zulip](https://jupyter.zulipchat.com/#narrow/channel/471314-geojupyter)!
 
diff --git a/docs/index.md b/docs/index.md
@@ -1,31 +1,55 @@
 # JupyterGIS
 
+JupyterGIS is a **collaborative** Geographical Information System (GIS) environment in
+JupyterLab.
+
+```{raw} html
+<center>
+```
+
 ```{jupyterlite}
 :new_tab: True
 :new_tab_button_text: Try it with JupyterLite!
 ```
 
-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.
+_Please note that JupyterLite is local-only and thus does not support collaboration._
+
+```{raw} html
+</center>
+<br />
+```
+
+JupyterGIS is the flagship project of the user-centric and open
+[GeoJupyter community](https://geojupyter.org), which aims to enable more people to
+confidently engage with geospatial data.
+We'd love to hear from you at a
+[community meeting](https://geojupyter.org/calendar.html)!
+
+## ✨ Highlights ✨
+
+🤝 Work simultaneously with your colleagues on the same GIS project (like Google Docs)
 
-JupyterGIS provides basic support for [QGIS](https://www.qgis.org) project files, allowing users to import and export
-projects seamlessly between QGIS and JupyterLab.
-This compatibility preserves layer styles, data sources, and project settings, enabling smooth transitions between GIS work
-in QGIS and collaborative, cloud-based work in JupyterLab.
+🔄 Basic support for importing/exporting [QGIS](https://www.qgis.org) project files
 
-Beyond QGIS project support, JupyterGIS offers a range of features tailored specifically for collaborative geospatial analysis.
-Users can edit, visualize, and analyze spatial data together in real-time, share map layers, and annotate directly within the
-JupyterLab environment, fostering efficient teamwork on GIS projects.
+🐍 Python API and integration with collaborative Jupyter Notebook workflows
 
-Python users can further extend JupyterGIS workflows by integrating with Python geospatial libraries, such as GeoPandas, Xarray
-and Rasterio, to perform custom analyses and automate processes. Together, these features make JupyterGIS a powerful tool for
-both collaborative mapping and in-depth geospatial analysis.
+For more details, check out the [project overview](overview/index.md)!
 
 ```{image} ../jupytergis.png
 :alt: JupyterGIS application
 ```
 
+## Overview
+
+High-level information about the project.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+overview/index
+```
+
 ## User guide
 
 Information about using JupyterGIS.
diff --git a/docs/overview/features/collab.md b/docs/overview/features/collab.md
@@ -0,0 +1,11 @@
+(collab)=
+
+# Collaborative Features
+
+One of the standout features of JupyterGIS is its shared editing functionality, which **seamlessly connects users across different interfaces within the JupyterGIS ecosystem**. Whether collaborators are using the JupyterLab GIS extension, or working with the Python API in a Notebook, **any changes made to a shared document are instantly reflected for all users**.
+
+For more details, please read our how-to document: [](#how-to-collab).
+
+:::{important}
+Note that currently, real-time collaboration is not supported in [JupyterLite](https://jupytergis.readthedocs.io/en/latest/lite/lab/index.html).
+:::
diff --git a/docs/overview/features/extension.md b/docs/overview/features/extension.md
diff --git a/docs/overview/features/index.md b/docs/overview/features/index.md
diff --git a/docs/overview/index.md b/docs/overview/index.md
@@ -0,0 +1,36 @@
+# Overview
+
+## 🤝 Real-time collaboration
+
+JupyterGIS 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.
+
+Users can edit, visualize, and analyze spatial data together in real-time, share map
+layers, and annotate directly within the JupyterLab environment, fostering efficient
+teamwork on GIS projects.
+
+## 🔄 QGIS project file support
+
+JupyterGIS provides basic support for [QGIS](https://www.qgis.org) project files, allowing users to import and export
+projects seamlessly between QGIS and JupyterLab.
+This compatibility preserves layer styles, data sources, and project settings, enabling smooth transitions between GIS work
+in QGIS and collaborative, cloud-based work in JupyterLab.
+
+## 🐍 Python integration
+
+Python users can further extend JupyterGIS workflows by integrating with Python geospatial libraries, such as GeoPandas, Xarray
+and Rasterio, to perform custom analyses and automate processes.
+Together, these features make JupyterGIS a powerful tool for
+both collaborative mapping and in-depth geospatial analysis.
+
+## ✨ And more...
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+:glob:
+
+*/index
+*
+```
diff --git a/docs/overview/jupytergis-venn-diagram.svg b/docs/overview/jupytergis-venn-diagram.svg
diff --git a/docs/overview/what-is-jgis.md b/docs/overview/what-is-jgis.md
@@ -0,0 +1,46 @@
+# What is JupyterGIS? What is it _not_?
+
+## What is JupyterGIS?
+
+### A reimagination of traditional GIS paradigms
+
+JupyterGIS is exploring new territory at the intersection of desktop GIS and
+cloud-native geospatial.
+Our goal is to bring modern, desktop-like GIS workflows to the cloud, meeting
+researchers where they already work: JupyterLab.
+
+Pre-existing desktop GIS tools like the legendary [QGIS](https://qgis.org) were
+conceived in a different era.
+Geospatial is a fast-moving domain and today, new opportunities exist to make GIS
+workflows less stressful and more joyful, and it's our goal to take advantage of those
+opportunities by rethinking what GIS can be.
+For example, JupyterGIS is designed from the ground up with real-time collaboration and
+integration with Jupyter Notebooks in mind.
+
+## What is JupyterGIS _not_?
+
+### A reimplementation of traditional GIS paradigms
+
+```{figure} ./jupytergis-venn-diagram.svg
+:alt: A Venn diagram of our vision of JupyterGIS' relationship to Jupyter Notebooks. The overlapping section between the two reads "Data analysis" and has an orange background, to indicate that this is territory that is already served well by Jupyter Notebooks. The JupyterGIS section contains two regions -- the "Exploration/viz layer" region which contains elements "share", "search", "discover", "draw/calculate AOIs", "identify patterns", "link w/ non-geo data", "validate"; and the "Utility layer" region contains elements "programmatic viz", "assist w/ coding", "transfer AOIs", "access", and "update map when data changes". The "Utility layer" sits between the "Exploration/viz layer" region and the "Data analysis" overlap region. An orange two-sided arrow connects the "Data analysis layer" and the "Exploration/viz layer" via the "Utility layer".
+
+A Venn diagram of our vision of JupyterGIS' relationship to Jupyter Notebooks.
+```
+
+As JupyterGIS is built for integration with Jupyter Notebooks, it's important to
+consider how the traditional desktop GIS paradigm might conflict with that integration.
+
+For example, traditional desktop GIS tools offer "processing" or "geoprocessing" tools
+which can be pipelined to produce unique analyses.
+For many practitioners that we've interviewed, the Jupyter Notebook ecosystem and the
+Scientific Python ecosystem serve that data analysis need very well.
+As the _data analysis_ part of their workflow is where their expertise lies, these
+geospatial researchers find integration of visualization into their workflow to be a
+much larger challenge, and this is often a reason for them to leave their Notebook
+environment and open up QGIS.
+While QGIS serves this need very well, the friction and mental context switching
+introduced by working in two disjoint applications presents a definite challenge.
+
+With these lessons in mind, we feel that our primary focus on JupyterGIS should _not_ be
+on reimplimenting "geoprocessing" toolboxes, and that we should instead focus on utility
+functionality that **supports and streamlines** analysis done in a Notebook environment.
diff --git a/docs/user_guide/how-tos/collab.md b/docs/user_guide/how-tos/collab.md
@@ -1,10 +1,10 @@
-(collab)=
+(how-to-collab)=
 
-# Collaborative Features
+# Create Collaborative JupyterGIS Sessions
 
-One of the standout features of JupyterGIS is its shared editing functionality, which **seamlessly connects users across different interfaces within the JupyterGIS ecosystem**. Whether collaborators are using the JupyterLab GIS extension, or working with the Python API in a Notebook, **any changes made to a shared document are instantly reflected for all users**.
-
-## Create Collaborative JupyterGIS Sessions
+:::{important}
+Please note that currently, real-time collaboration is not supported in [JupyterLite](https://jupytergis.readthedocs.io/en/latest/lite/lab/index.html).
+:::
 
 If you are using a local installation, your JupyterLab instance is not available to the Internet by default, thus collaborators cannot join your session directly. Here are two techniques to facilitating collaboration in such instances.
 
@@ -14,15 +14,11 @@ If you are using a local installation, your JupyterLab instance is not available
 
    In both cases, you should forward the port of the JupyterLab instance. The default port is `8888`.
 
-2. For a more scalable alternative, consider hosting JupyterGIS on a cloud-based or network-accessible instance. This setup allows multi-user cooperation with authentication and access restriction, without requiring a local installation. Once the instance is created using any of the options below, JupyterGIS needs to be installed on the created instance by opening a terminal window and following [the installation guide](/user_guide/install.md).
+2. For a more scalable alternative, consider hosting JupyterGIS on a cloud-based or network-accessible instance (or using an [existing cloud deployment](https://infrastructure.2i2c.org/reference/hubs/). This setup allows multi-user cooperation with authentication and access restriction, without requiring a local installation. Once the instance is created using any of the options below, JupyterGIS needs to be installed on the created instance by opening a terminal window and following [the installation guide](../install.md).
    - [JupyterHub](https://jupyter.org/hub): You can follow [the JupyterHub documentation](https://jupyter.org/hub#deploy-a-jupyterhub) for setup instructions. By default, JupyterHub creates isolated environments for each user. To enable real-time collaboration on the same environment, you can follow [this guide](https://jupyterhub.readthedocs.io/en/5.2.1/reference/sharing.html#sharing-reference).
    - [Binder](https://mybinder.readthedocs.io/en/latest/index.html): Check out [this tutorial](https://book.the-turing-way.org/communication/binder/zero-to-binder) to start using Binder. Note that when you share the link with a collaborator, they will be asked to enter the password or token to access the session. You can find out the token by opening a terminal window and running the command
      ```
      jupyter notebook list --json | python3 -c 'import json; import sys; print(json.load(sys.stdin)["token"])'
      ```
-     Note that if you have added JupyterGIS to the `requirements.txt` file, it will be installed automatically when you create the Binder instance. In this case you do not need to follow [the installation guide](/user_guide/install.md).
+     Note that if you have added JupyterGIS to the `requirements.txt` file, it will be installed automatically when you create the Binder instance. In this case you do not need to follow [the installation guide](../install.md).
    - [Amazon SageMaker AI](https://aws.amazon.com/sagemaker-ai): If you prefer to use Amazon SageMaker AI, you can follow [this tutorial](https://docs.aws.amazon.com/sagemaker/latest/dg/onboard-quick-start.html) to set up your environment. After opening SageMaker Studio, create a JupyterLab space, and make sure choosing `Share with my domain` option to enable access for your collaborators.
-
-:::{important}
-Note that currently, real-time collaboration is not supported in [JupyterLite](https://jupytergis.readthedocs.io/en/latest/lite/lab/index.html).
-:::
diff --git a/docs/user_guide/how-tos/index.md b/docs/user_guide/how-tos/index.md
@@ -0,0 +1,8 @@
+# How-tos
+
+```{toctree}
+:maxdepth: 1
+:glob:
+
+*
+```
diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md
@@ -17,7 +17,7 @@ JupyterGIS offers:
 :maxdepth: 2
 
 install
+how-tos/index
 tutorials/index
-features/index
 python_api
 ```
diff --git a/docs/user_guide/tutorials/02-collaboration/index.md b/docs/user_guide/tutorials/02-collaboration/index.md
@@ -19,7 +19,7 @@ By following this tutorial, you will be able to:
 
 :::{admonition} Prerequisites
 :class: warning
-Before beginning this tutorial, JupyterGIS must be installed on your computer (see [Installation instructions](https://jupytergis.readthedocs.io/en/latest/user_guide/install.html)). Alternatively, you can use an online installation of JupyterGIS. Your choice may have implications for collaboration, so please read our [collaboration feature overview](/user_guide/features/collab.md) for more context.
+Before beginning this tutorial, JupyterGIS must be installed on your computer (see [installation instructions](../../install.md)). Alternatively, you can use an online installation of JupyterGIS. Your choice may have implications for collaboration, so please read our [collaboration feature overview](../../../overview/features/collab.md) for more context.
 :::
 
 ---
