Create new top-level "overview" section in docs #921

mfisher87 · 2025-09-10T18:54:41Z

Description

Front page
- The front page of our docs is pretty wordy! Extract long-form content to overview section, replace with quick-to-read highlights on the front page. Add some 🔥 emojis.
- Link to GeoJupyter website on docs front page
Overview section
- Add page: "What is JupyterGIS?"
- Move the "features" section from the user guide to the overview.
  - Move the "how-to setup up collaboration" instructions to a new how-tos section in the user guide. Cross-link.
Link to team compass in contributor guide

Future PR: Roadmap page in overview section

Checklist

PR has a descriptive title and content.
PR description contains references to any issues the PR resolves, e.g. Resolves #XXX.
PR has one of the labels: documentation, bug, enhancement, feature, maintenance
Checks are passing.
Failing lint checks can be resolved with:
- pre-commit run --all-files
- jlpm run lint

📚 Documentation preview: https://jupytergis--921.org.readthedocs.build/en/921/
💡 JupyterLite preview: https://jupytergis--921.org.readthedocs.build/en/921/lite

github-actions · 2025-09-10T18:54:51Z

👈 Launch a Binder on branch mfisher87/jupytergis/docs-overview-and-reorg

github-actions · 2025-09-10T19:07:32Z

Integration tests report: appsharing.space

stefanv

This looks good overall! I left some minor feedback.

stefanv · 2025-09-30T21:07:32Z

docs/overview/features/collab.md

+
+# 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**.


What does "interfaces" refer to here?

Good question, I didn't change this text, I only moved it, and I didn't write it originally :X I think what it means is the Python API in a Notebook or the actual JupyterGIS viewer, and the 2nd sentence is meant to explain that. Does that sound reasonable to you? Suggestions to clarify even further? Or do you prefer to workshop the text in a different PR?

stefanv · 2025-09-30T22:06:25Z

docs/overview/what-is-jgis.md

+
+### A reimplementation of traditional GIS paradigms
+
+```{figure} ./jupytergis-venn-diagram.svg


I find this diagram quite confusing, FWIW 👀 What is it meant to show the reader?

Well shit, that's not what I'm going for 😆

It's meant to communicate that "data analysis" is territory well-served by Notebooks, and JupyterGIS shouldn't try to "invade" that territory in the way that traditional desktop tools' "model builder" interfaces do. The right side defines two categories of things that serve analysis: the "viz/explore" layer which is similar to the functionality Notebook users might normally open QGIS to access; and the "utility" layer which connects the analysis environment and the "viz/explore" layer.

It's meant to communicate more clearly the shape of JupyterGIS as not a reimplementation of traditional GIS software in JupyterLab, instead it's an attempt to imagine a new interface that is shaped differently and tightly integrates with a Notebook as an analysis environment.

stefanv · 2025-09-30T22:08:16Z

docs/overview/what-is-jgis.md

+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


Perhaps this suggests that we need better in-memory bridges between QGIS and Jupyter as well; wonder if such things are feasible.

That's an interesting thought. At the moment we hadn't considered such a bridge, and envisioned JupyterGIS as the target viz environment instead. It would be really cool to enable an Xarray dataset to be opened directly in QGIS, but I also don't know how feasible that might be. 🤔

stefanv · 2025-09-30T22:09:17Z

docs/overview/what-is-jgis.md

+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


This sentence suggests that QGIS is still central to the analysis pipeline, since JupyterGIS does not want to duplicate all their functionality. Which sounds right, but how does that work?

I'm trying to describe the Notebook as the replacement for the QGIS / Arc "model builder" interfaces here. From interviews, many folks are very comfortable doing their analysis in a Notebook with Xarray or GeoPandas, but when it comes time to visualize the results or plan their analysis visually, they leave the Notebook to open QGIS. It sounds like I could do a much better job explaining this 😆 Ideas?

stefanv · 2025-09-30T22:10:30Z

docs/user_guide/how-tos/collab.md

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


Where will users find these cloud-based or network-accessible instances? If they don't know, I imagine this sentence could be rather intimidating.

This was another piece of content that I only moved, didn't edit or write originally. Perhaps we could suggest some existing Hubs like CryoCloud or other 2i2c community hubs?

stefanv · 2025-09-30T22:11:34Z

docs/build-on-change.sh

+set -e
+
+while inotifywait -e delete -e create -e close_write -r ${THIS_DIR}; do
+    ${THIS_DIR}/clean.sh


Need to clean each time?

I think so. But I'm not 100% sure. I copied this from another project that I worked on a few years back. Maybe it could be faster without a clean, but I imagine I learned a lesson the hard way that led to cleaning every time? Sorry I don't remember more :)

mfisher87 added the documentation Improvements or additions to documentation label Sep 10, 2025

geojupyter-pr-triage bot added this to JupyterGIS PR triage Sep 12, 2025

mfisher87 added 5 commits September 29, 2025 11:26

Add a documentation "watched" build script (Linux only)

ff1f45c

Extract long-form overview content from frontpage

f2d4507

Link to team compass in contributor guide

d3814b4

Move features descriptions into overview section

9600eb2

Move content on how to collaborate into user guide how-to

53127b2

mfisher87 force-pushed the docs-overview-and-reorg branch from 3154520 to 53127b2 Compare September 29, 2025 17:26

mfisher87 added 2 commits September 29, 2025 11:31

Offset TOC contents

e51d11f

Add "What is/not JupyterGIS" page

c1fbdd3

mfisher87 changed the title ~~Create new top-level "oveview" section in docs~~ Create new top-level "overview" section in docs Sep 29, 2025

mfisher87 requested review from stefanv, martinRenou and arjxn-py September 30, 2025 20:08

mfisher87 marked this pull request as ready for review September 30, 2025 20:10

mfisher87 added 4 commits September 30, 2025 14:11

Lint 🔔

7de7e61

Lint 🔔

9cab8d1

Replace absolute links with relative links 😩

d5ebc4c

Fixup incorrect link

c5eec53

stefanv reviewed Sep 30, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Create new top-level "overview" section in docs #921

Create new top-level "overview" section in docs #921

Uh oh!

mfisher87 commented Sep 10, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Sep 10, 2025

Uh oh!

github-actions bot commented Sep 10, 2025 •

edited

Loading

Uh oh!

stefanv left a comment

Uh oh!

stefanv Sep 30, 2025

Uh oh!

mfisher87 Sep 30, 2025 •

edited

Loading

Uh oh!

stefanv Sep 30, 2025

Uh oh!

mfisher87 Sep 30, 2025

Uh oh!

stefanv Sep 30, 2025

Uh oh!

mfisher87 Sep 30, 2025

Uh oh!

stefanv Sep 30, 2025

Uh oh!

mfisher87 Sep 30, 2025

Uh oh!

stefanv Sep 30, 2025

Uh oh!

mfisher87 Sep 30, 2025

Uh oh!

stefanv Sep 30, 2025

Uh oh!

mfisher87 Sep 30, 2025

Uh oh!

Uh oh!


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


		### A reimplementation of traditional GIS paradigms

		```{figure} ./jupytergis-venn-diagram.svg

Create new top-level "overview" section in docs #921

Are you sure you want to change the base?

Create new top-level "overview" section in docs #921

Uh oh!

Conversation

mfisher87 commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

github-actions bot commented Sep 10, 2025

Uh oh!

github-actions bot commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stefanv left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mfisher87 Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mfisher87 commented Sep 10, 2025 •

edited

Loading

github-actions bot commented Sep 10, 2025 •

edited

Loading

mfisher87 Sep 30, 2025 •

edited

Loading