From 4de650aef08aa6a27ce45740e834e32dc137d1bd Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 10 Sep 2025 12:29:42 -0600 Subject: [PATCH 01/16] Add a documentation "watched" build script (Linux only) --- docs/build-on-change.sh | 23 +++++++++++++++++++++++ docs/build.sh | 3 ++- docs/clean.sh | 5 +++++ 3 files changed, 30 insertions(+), 1 deletion(-) create mode 100755 docs/build-on-change.sh create mode 100755 docs/clean.sh diff --git a/docs/build-on-change.sh b/docs/build-on-change.sh new file mode 100755 index 000000000..b4650f534 --- /dev/null +++ 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 index d8f1494eb..5db958527 100755 --- 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 new file mode 100755 index 000000000..4aea5574c --- /dev/null +++ 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" From 8453242b93d240245527ffa9e6db01f0ad976602 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 10 Sep 2025 12:50:23 -0600 Subject: [PATCH 02/16] Extract long-form overview content from frontpage --- docs/index.md | 49 +++++++++++++++++++++++++++++++----------- docs/overview/index.md | 25 +++++++++++++++++++++ 2 files changed, 61 insertions(+), 13 deletions(-) create mode 100644 docs/overview/index.md diff --git a/docs/index.md b/docs/index.md index 4e35867cc..12a50780a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,31 +1,54 @@ # JupyterGIS +JupyterGIS is a **collaborative** Geographical Information System (GIS) environment in +JupyterLab. + +```{raw} html +
+``` + ```{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. +```{raw} html +
+
+``` + +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 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/index.md b/docs/overview/index.md new file mode 100644 index 000000000..8f8902427 --- /dev/null +++ b/docs/overview/index.md @@ -0,0 +1,25 @@ +# 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. From e650ee81a72da659f4314d27f716423b7fdff363 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 10 Sep 2025 12:57:24 -0600 Subject: [PATCH 03/16] Link to team compass in contributor guide --- docs/contributor_guide/index.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/contributor_guide/index.md b/docs/contributor_guide/index.md index 40faf28cc..677db64df 100644 --- 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)! From a22aa4836fd2fa38050b1e471e93f02e80b87fd3 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Fri, 12 Sep 2025 11:44:20 -0600 Subject: [PATCH 04/16] Move features descriptions into overview section --- docs/{user_guide => overview}/features/collab.md | 0 docs/{user_guide => overview}/features/extension.md | 0 docs/{user_guide => overview}/features/index.md | 0 docs/overview/index.md | 9 +++++++++ docs/user_guide/index.md | 1 - docs/user_guide/tutorials/02-collaboration/index.md | 2 +- 6 files changed, 10 insertions(+), 2 deletions(-) rename docs/{user_guide => overview}/features/collab.md (100%) rename docs/{user_guide => overview}/features/extension.md (100%) rename docs/{user_guide => overview}/features/index.md (100%) diff --git a/docs/user_guide/features/collab.md b/docs/overview/features/collab.md similarity index 100% rename from docs/user_guide/features/collab.md rename to docs/overview/features/collab.md diff --git a/docs/user_guide/features/extension.md b/docs/overview/features/extension.md similarity index 100% rename from docs/user_guide/features/extension.md rename to docs/overview/features/extension.md diff --git a/docs/user_guide/features/index.md b/docs/overview/features/index.md similarity index 100% rename from docs/user_guide/features/index.md rename to docs/overview/features/index.md diff --git a/docs/overview/index.md b/docs/overview/index.md index 8f8902427..3f7850dd5 100644 --- a/docs/overview/index.md +++ b/docs/overview/index.md @@ -23,3 +23,12 @@ Python users can further extend JupyterGIS workflows by integrating with Python 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. + +```{toctree} +:titlesonly: +:maxdepth: 2 +:glob: + +*/index +* +``` diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index 4f21468e7..3f0cb3d0e 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -18,6 +18,5 @@ JupyterGIS offers: install 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 index fe7462851..f621e7651 100644 --- 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](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](/overview/features/collab.md) for more context. ::: --- From ac06985e33327c9f71288dee5918a115ffeead4d Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Fri, 12 Sep 2025 12:00:06 -0600 Subject: [PATCH 05/16] Move content on how to collaborate into user guide how-to --- docs/overview/features/collab.md | 19 +------------------ docs/user_guide/how-tos/collab.md | 23 +++++++++++++++++++++++ docs/user_guide/how-tos/index.md | 8 ++++++++ docs/user_guide/index.md | 1 + 4 files changed, 33 insertions(+), 18 deletions(-) create mode 100644 docs/user_guide/how-tos/collab.md create mode 100644 docs/user_guide/how-tos/index.md diff --git a/docs/overview/features/collab.md b/docs/overview/features/collab.md index 7e4ad72d2..c5d165cb9 100644 --- a/docs/overview/features/collab.md +++ b/docs/overview/features/collab.md @@ -4,24 +4,7 @@ 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 - -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. - -1. Hosting a local server using VSCode (Microsoft) or PyCharm (Jetbrains) enables real-time collaboration without exposing your server to the Internet. - - To use VSCode's Live Share, you can follow the steps [here](https://learn.microsoft.com/en-us/visualstudio/liveshare/use/share-server-visual-studio-code#share-a-server). - - To use PyCharm's Code With Me, first you can enable [Code With Me](https://www.jetbrains.com/help/pycharm/code-with-me.html), then set up [port forwarding](https://www.jetbrains.com/help/pycharm/code-with-me.html#port_forwarding). - - 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). - - [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). - - [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. +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/user_guide/how-tos/collab.md b/docs/user_guide/how-tos/collab.md new file mode 100644 index 000000000..ea62f8fdf --- /dev/null +++ b/docs/user_guide/how-tos/collab.md @@ -0,0 +1,23 @@ +(how-to-collab)= +# 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. + +1. Hosting a local server using VSCode (Microsoft) or PyCharm (Jetbrains) enables real-time collaboration without exposing your server to the Internet. + - To use VSCode's Live Share, you can follow the steps [here](https://learn.microsoft.com/en-us/visualstudio/liveshare/use/share-server-visual-studio-code#share-a-server). + - To use PyCharm's Code With Me, first you can enable [Code With Me](https://www.jetbrains.com/help/pycharm/code-with-me.html), then set up [port forwarding](https://www.jetbrains.com/help/pycharm/code-with-me.html#port_forwarding). + + 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). + - [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). + - [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. diff --git a/docs/user_guide/how-tos/index.md b/docs/user_guide/how-tos/index.md new file mode 100644 index 000000000..175471a20 --- /dev/null +++ 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 index 3f0cb3d0e..47984fac6 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -17,6 +17,7 @@ JupyterGIS offers: :maxdepth: 2 install +how-tos/index tutorials/index python_api ``` From 163a15e970359d471fa4bd1f977e42b0c34b0f0e Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Mon, 29 Sep 2025 11:31:18 -0600 Subject: [PATCH 06/16] Offset TOC contents --- docs/overview/index.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/overview/index.md b/docs/overview/index.md index 3f7850dd5..72bebf40a 100644 --- a/docs/overview/index.md +++ b/docs/overview/index.md @@ -24,6 +24,9 @@ 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 From afb2bed9159944ef92df0e3b4a02735b0504c160 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Mon, 29 Sep 2025 14:14:48 -0600 Subject: [PATCH 07/16] Add "What is/not JupyterGIS" page --- docs/overview/jupytergis-venn-diagram.svg | 4 ++ docs/overview/what-is-jgis.md | 47 +++++++++++++++++++++++ 2 files changed, 51 insertions(+) create mode 100644 docs/overview/jupytergis-venn-diagram.svg create mode 100644 docs/overview/what-is-jgis.md diff --git a/docs/overview/jupytergis-venn-diagram.svg b/docs/overview/jupytergis-venn-diagram.svg new file mode 100644 index 000000000..84f4e52d9 --- /dev/null +++ b/docs/overview/jupytergis-venn-diagram.svg @@ -0,0 +1,4 @@ + + +NotebooksJupyterGISData analysisUtility layerExploration/viz layersearchdiscoveraccesstransferAOIsassist w/codingprogrammaticvizvalidatelink w/non-geo vizidentifypatternsdraw/calculateAOIsshare✨update mapwhen data changes diff --git a/docs/overview/what-is-jgis.md b/docs/overview/what-is-jgis.md new file mode 100644 index 000000000..d54b18258 --- /dev/null +++ b/docs/overview/what-is-jgis.md @@ -0,0 +1,47 @@ +# 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. From 4d6f1a8c8aceaafb730d0987c10c53a0b6436cb4 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Tue, 30 Sep 2025 14:11:38 -0600 Subject: [PATCH 08/16] Lint :bell: --- docs/overview/index.md | 1 - docs/overview/what-is-jgis.md | 1 - docs/user_guide/how-tos/collab.md | 1 + 3 files changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/overview/index.md b/docs/overview/index.md index 72bebf40a..5816d0ca2 100644 --- a/docs/overview/index.md +++ b/docs/overview/index.md @@ -24,7 +24,6 @@ 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} diff --git a/docs/overview/what-is-jgis.md b/docs/overview/what-is-jgis.md index d54b18258..cc70aa431 100644 --- a/docs/overview/what-is-jgis.md +++ b/docs/overview/what-is-jgis.md @@ -17,7 +17,6 @@ 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 diff --git a/docs/user_guide/how-tos/collab.md b/docs/user_guide/how-tos/collab.md index ea62f8fdf..ba0fbbcde 100644 --- a/docs/user_guide/how-tos/collab.md +++ b/docs/user_guide/how-tos/collab.md @@ -1,4 +1,5 @@ (how-to-collab)= + # Create Collaborative JupyterGIS Sessions :::{important} From d0a45bc5ea68c21e72276934a6490086fbb7b08c Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Tue, 30 Sep 2025 15:20:59 -0600 Subject: [PATCH 09/16] Lint :bell: --- docs/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 12a50780a..9e2244f94 100644 --- a/docs/index.md +++ b/docs/index.md @@ -23,7 +23,6 @@ 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) From a0b8941d2404f54e993dc53e5ff29b4b8a5ef152 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Tue, 30 Sep 2025 15:36:10 -0600 Subject: [PATCH 10/16] Replace absolute links with relative links :weary: --- docs/user_guide/how-tos/collab.md | 4 ++-- docs/user_guide/tutorials/02-collaboration/index.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/user_guide/how-tos/collab.md b/docs/user_guide/how-tos/collab.md index ba0fbbcde..987055145 100644 --- a/docs/user_guide/how-tos/collab.md +++ b/docs/user_guide/how-tos/collab.md @@ -14,11 +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. 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](../user_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. diff --git a/docs/user_guide/tutorials/02-collaboration/index.md b/docs/user_guide/tutorials/02-collaboration/index.md index f621e7651..3e4338936 100644 --- 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](/overview/features/collab.md) for more context. +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](../../../overview/features/collab.md) for more context. ::: --- From 24231bf872587dc6e794e57f6f18053cff9a5d96 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Tue, 30 Sep 2025 15:42:12 -0600 Subject: [PATCH 11/16] Fixup incorrect link --- docs/user_guide/how-tos/collab.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/how-tos/collab.md b/docs/user_guide/how-tos/collab.md index 987055145..18676fd0e 100644 --- a/docs/user_guide/how-tos/collab.md +++ b/docs/user_guide/how-tos/collab.md @@ -20,5 +20,5 @@ If you are using a local installation, your JupyterLab instance is not available ``` 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. From 841c6fb2ebf95900c14c3c7044a8ed8b93902687 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 29 Oct 2025 09:59:34 -0600 Subject: [PATCH 12/16] Replace web link with internal reference --- docs/user_guide/tutorials/02-collaboration/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/tutorials/02-collaboration/index.md b/docs/user_guide/tutorials/02-collaboration/index.md index 3e4338936..eb7de9653 100644 --- 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](../../../overview/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. ::: --- From f9765ba6f5a0e518f8de503f13c434cb333c1ff3 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 29 Oct 2025 10:15:59 -0600 Subject: [PATCH 13/16] Add link to list of 2i2c hubs --- docs/user_guide/how-tos/collab.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/how-tos/collab.md b/docs/user_guide/how-tos/collab.md index 18676fd0e..92bf1f8f8 100644 --- a/docs/user_guide/how-tos/collab.md +++ b/docs/user_guide/how-tos/collab.md @@ -14,7 +14,7 @@ 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](../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 ``` From 3c8664ad740fbee54cdc38a71a4711ca18bdf0ef Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 29 Oct 2025 10:29:49 -0600 Subject: [PATCH 14/16] Update Venn diagram and description --- docs/overview/jupytergis-venn-diagram.svg | 4 ++-- docs/overview/what-is-jgis.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/overview/jupytergis-venn-diagram.svg b/docs/overview/jupytergis-venn-diagram.svg index 84f4e52d9..d8fe58a57 100644 --- a/docs/overview/jupytergis-venn-diagram.svg +++ b/docs/overview/jupytergis-venn-diagram.svg @@ -1,4 +1,4 @@ -NotebooksJupyterGISData analysisUtility layerExploration/viz layersearchdiscoveraccesstransferAOIsassist w/codingprogrammaticvizvalidatelink w/non-geo vizidentifypatternsdraw/calculateAOIsshare✨update mapwhen data changes +NotebooksJupyterGISData analysis& processingUtility layerExploration/viz layersearchdiscoveraccesstransferAOIsassist w/codingprogrammaticvizvalidatelink w/non-geo vizidentifypatternsdraw/calculateAOIsshare✨update mapwhen data changesNOT JupyterGIS' focus diff --git a/docs/overview/what-is-jgis.md b/docs/overview/what-is-jgis.md index cc70aa431..43cd367de 100644 --- a/docs/overview/what-is-jgis.md +++ b/docs/overview/what-is-jgis.md @@ -43,4 +43,4 @@ 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. +functionality that **supports and streamlines** analysis done in a Notebook environment. From 1fb99ad9a4bc3af2c65b296da33e5c2ac5d25c22 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 29 Oct 2025 10:30:49 -0600 Subject: [PATCH 15/16] Mention collaboration in Python API --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 9e2244f94..23d6d1e6b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -29,7 +29,7 @@ We'd love to hear from you at a 🔄 Basic support for importing/exporting [QGIS](https://www.qgis.org) project files -🐍 Python API and integration with Jupyter Notebook workflows +🐍 Python API and integration with collaborative Jupyter Notebook workflows For more details, check out the [project overview](overview/index.md)! From 91c3bb3f75004e3a8ac7baad6b0ee4b9cee8f539 Mon Sep 17 00:00:00 2001 From: Matt Fisher Date: Wed, 29 Oct 2025 10:35:12 -0600 Subject: [PATCH 16/16] Note lack of support for collab in JLite --- docs/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/index.md b/docs/index.md index 23d6d1e6b..0b6405246 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,6 +12,8 @@ JupyterLab. :new_tab_button_text: Try it with JupyterLite! ``` +_Please note that JupyterLite is local-only and thus does not support collaboration._ + ```{raw} html