added simple tutorial to introduce the jupyterGIS GUI. by annefou · Pull Request #393 · geojupyter/jupytergis

annefou · 2025-01-27T19:01:41Z

Description

Resolves #313 e.g. added a simple tutorial to show how to use jupytergis with the GUI.

I added the tutorial (as discussed in #313) but I used markdown. Let me know if it is an issue. Also I noticed that some formatting do not work here (for instance {admonition}). Do you have any suggestions to fix these issues. Thanks!

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--393.org.readthedocs.build/en/393/
💡 JupyterLite preview: https://jupytergis--393.org.readthedocs.build/en/393/lite

github-actions · 2025-01-27T19:01:55Z

👈 Launch a Binder on branch annefou/jupytergis/add-tutorial

github-actions · 2025-01-27T19:12:11Z

Integration tests report: appsharing.space

docs/tutorials/intro.md

Co-authored-by: martinRenou <martin.renou@gmail.com>

annefou · 2025-01-28T13:30:52Z

Ok. I think I implemented all the requested changes and tried to fix all the checks but 2 are failing and I don't understand why.

martinRenou

LGTM!

Ok. I think I implemented all the requested changes and tried to fix all the checks but 2 are failing and I don't understand why.

The two failures are unrelated see #404 and #394

@mfisher87 would you like to give a look at this PR before we merge?

docs/tutorials/intro.md

to make sure we have dropdown for exercise solutions

mfisher87

Awesome work! Hope you don't mind my large number of comments. Tutorials are really hard, thank you so much for taking this on! Feel free to ignore any nitpick you disagree with.

docs/tutorials/intro.md

mfisher87 · 2025-01-29T18:36:03Z

docs/tutorials/intro.md

+
+We will explore the JupyterGIS user interface to help you become familiar with its menus, toolbars, map canvas, and layers list, which make up the core structure of the interface.
+
+**The objective of this lesson is to understand the fundamentals of the JupyterGIS user interface.**


Love this. Nitpick: Maybe we could use an admonition with the custom title "Lesson goal" instead of a bolded paragraph?

mfisher87 · 2025-01-29T18:38:46Z

docs/tutorials/intro.md

+
+1. The application Launcher helps you to select which application you want to start e.g. a Notebook, a Console, and another application such as a Terminal or open a GIS file (which can be either a JupyterGIS file or a QGIS file).
+2. GIS Layers List / Browser Panel
+3. Left Sidebar which contains a file browser, a list of tabs in the main work and of running kernels and terminals, the command palette, the table of contents, the extension manager, and the JupyterGIS extension which allows you to see the GIS layers list.


This would require editing the image, so I apologize, but what about reversing the order of 2 and 3? 3 currently explains that the GIS layers list in 2 is enabled because of the selected tab in 3, and it feels like that information should be given first.

mfisher87 · 2025-01-29T19:04:13Z

docs/tutorials/intro.md

+The order in which the layers have been loaded into the map is probably not logical at this stage. It’s possible that the road layer or/and the country layer are completely hidden because other layers are on top of it.
+
+For example, this layer order:
+![Wrong layer order](../assets/images/wrongLayerOrder.png)


I think we should only show layers in this screenshot, not sources. It's a bit confusing!

docs/tutorials/intro.md

mfisher87 · 2025-01-29T19:08:19Z

docs/tutorials/intro.md

+:label: Rename-layer
+```
+
+- Rename each **Custom Shapefile Layer** with a meaningful name e.g., **cb_2015_us_county_500k** for the US County Shapefile Layer and **nyc_roads** for the roads in New-York.


Layer names can have spaces in them, so I feel it would be valuable to write these as more human-readable names, like "NYC roads" and "US counties" instead of naming them after the input files. It might be useful to demonstrate renaming the sources to match the input file names!

docs/tutorials/intro.md

mfisher87 · 2025-01-29T19:13:19Z

docs/tutorials/intro.md

+
+Welcome to the first tutorial in the JupyterGIS series! This guide will introduce you to the basics of JupyterGIS and help you set up your environment, create your first map, and understand its key features.
+
+## Objectives


🤩 https://diataxis.fr/tutorials/#show-the-learner-where-they-ll-be-going

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

remove text from image but keep arrow add arrow to image JupyterGIS GUI with new numbering as requested

for more information, see https://pre-commit.ci

annefou · 2025-01-30T09:39:48Z

@mfisher87 Thanks for your detailed review. It is very helpful. I tried to implement all your suggestions, but please do not hesitate to provide any further feedback.

mfisher87

This looks so good! Amazing work, Anne!!!

docs/tutorials/intro.md

mfisher87 · 2025-01-30T18:12:29Z

docs/tutorials/intro.md

+:class: warning
+Did you notice in the figures above that in the list of sources, the source for 'US Counties' appears before the source for 'OpenStreetMap.Mapmik'? In contrast, you can see the reverse order in the list of Layers.
+The reason is that sources are ordered alphabetically, while layers are ordered based on the order in which they are added, with the top layer being the most recently added to your map.
+:::


Nice callout!!!

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

mfisher87 · 2025-01-31T14:30:44Z

The integration test failure is not one I've seen before. Previously it was a snapshot difference, but now:

tests/export.spec.ts:70:7 › #export › should display warnings
 ──────────────────────────────────

martinRenou

Discarding visual regression tests for now. I believe the export test is not passing but it's definitely not this PR. Thanks a ton Anne!

mfisher87 · 2025-01-31T17:07:19Z

Awesome work, @annefou !!

* added simple tutorial * ran pre-commit to fix issues * jlpm run lint * bug fix wrong quote was used. Co-authored-by: martinRenou <martin.renou@gmail.com> * fix colon_fence and add missing images * fix typo * add sphinx extension in environment-docs.yml * fix typo in env for docs * add sphinx extension in build.yml too * add missing sphinx-togglebutton package to make sure we have dropdown for exercise solutions * Update docs/tutorials/intro.md Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com> * Update docs/tutorials/intro.md Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com> * Update docs/tutorials/intro.md Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com> * Update docs/tutorials/intro.md Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com> * Update docs/tutorials/intro.md Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com> * Update docs/tutorials/intro.md Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com> * Update docs/tutorials/intro.md Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com> * Update docs/tutorials/intro.md Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com> * Update docs/tutorials/intro.md Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com> * implement requested changes remove text from image but keep arrow add arrow to image JupyterGIS GUI with new numbering as requested * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * introduce rename layers early in the tutorial * introduce renaming of layers/sources early * fix failure with jlpm run lint * Update docs/tutorials/intro.md Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com> * add prerequisites at the top --------- Co-authored-by: martinRenou <martin.renou@gmail.com> Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

annefou added 3 commits January 27, 2025 19:50

added simple tutorial

fcda4df

ran pre-commit to fix issues

b37f097

jlpm run lint

7c64993

mfisher87 added the documentation Improvements or additions to documentation label Jan 27, 2025

Merge branch 'main' into add-tutorial

fe8b832

martinRenou reviewed Jan 28, 2025

View reviewed changes

docs/tutorials/intro.md Outdated Show resolved Hide resolved

martinRenou reviewed Jan 28, 2025

View reviewed changes

docs/tutorials/intro.md Outdated Show resolved Hide resolved

annefou and others added 7 commits January 28, 2025 09:58

bug fix wrong quote was used.

073d17a

Co-authored-by: martinRenou <martin.renou@gmail.com>

fix colon_fence and add missing images

d9864ae

fix typo

152facf

Merge branch 'main' into add-tutorial

e1c1c41

add sphinx extension in environment-docs.yml

ec6b8f7

fix typo in env for docs

b6fd6bb

add sphinx extension in build.yml too

3b9bdd1

martinRenou approved these changes Jan 29, 2025

View reviewed changes

arjxn-py reviewed Jan 29, 2025

View reviewed changes

docs/tutorials/intro.md Show resolved Hide resolved

add missing sphinx-togglebutton package

a7b6898

to make sure we have dropdown for exercise solutions

mfisher87 reviewed Jan 29, 2025

View reviewed changes

mfisher87 mentioned this pull request Jan 29, 2025

Re-organize documentation top-level navigation #411

Closed

annefou and others added 8 commits January 29, 2025 20:22

Update docs/tutorials/intro.md

f8a8d63

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/tutorials/intro.md

73ddf89

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/tutorials/intro.md

7ffe482

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/tutorials/intro.md

5d01ea7

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/tutorials/intro.md

59860c6

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/tutorials/intro.md

ee50420

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/tutorials/intro.md

e3cdb7a

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

Update docs/tutorials/intro.md

b40e5f1

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

annefou and others added 6 commits January 29, 2025 20:35

Update docs/tutorials/intro.md

0e594be

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

implement requested changes

ea574c7

remove text from image but keep arrow add arrow to image JupyterGIS GUI with new numbering as requested

[pre-commit.ci] auto fixes from pre-commit.com hooks

c588349

for more information, see https://pre-commit.ci

introduce rename layers early in the tutorial

e7ddd49

introduce renaming of layers/sources early

feb7ae0

Merge branch 'main' into add-tutorial

7a7b21f

fix failure with jlpm run lint

67c2f3e

mfisher87 approved these changes Jan 30, 2025

View reviewed changes

annefou and others added 3 commits January 30, 2025 19:20

Update docs/tutorials/intro.md

471e05c

Co-authored-by: Matt Fisher <3608264+mfisher87@users.noreply.github.com>

add prerequisites at the top

b1de24b

Merge branch 'main' into add-tutorial

b583cf1

martinRenou approved these changes Jan 31, 2025

View reviewed changes

martinRenou merged commit ceb02cc into geojupyter:main Jan 31, 2025
13 of 14 checks passed

annefou deleted the add-tutorial branch February 9, 2025 14:14


		We will explore the JupyterGIS user interface to help you become familiar with its menus, toolbars, map canvas, and layers list, which make up the core structure of the interface.

		The objective of this lesson is to understand the fundamentals of the JupyterGIS user interface.


		Welcome to the first tutorial in the JupyterGIS series! This guide will introduce you to the basics of JupyterGIS and help you set up your environment, create your first map, and understand its key features.

		## Objectives

Conversation

annefou commented Jan 27, 2025 • edited by mfisher87 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

github-actions bot commented Jan 27, 2025

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

annefou commented Jan 28, 2025

Uh oh!

martinRenou left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mfisher87 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mfisher87 Jan 29, 2025

Choose a reason for hiding this comment

Uh oh!

mfisher87 Jan 29, 2025

Choose a reason for hiding this comment

Uh oh!

mfisher87 Jan 29, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mfisher87 Jan 29, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mfisher87 Jan 29, 2025

Choose a reason for hiding this comment

Uh oh!

annefou commented Jan 30, 2025

Uh oh!

mfisher87 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mfisher87 Jan 30, 2025

Choose a reason for hiding this comment

Uh oh!

mfisher87 commented Jan 31, 2025

Uh oh!

martinRenou left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mfisher87 commented Jan 31, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

annefou commented Jan 27, 2025 •

edited by mfisher87

Loading

github-actions bot commented Jan 27, 2025 •

edited

Loading