OpenSenseAction / OPENSENSE_sandbox

Collection of runable examples with software packages for processing opportunistic rainfall sensors
BSD 3-Clause "New" or "Revised" License
13 stars 16 forks source link

Add index notebook for all notebooks (for navigation on binder) and improve readme.md #15

Closed cchwala closed 1 year ago

cchwala commented 2 years ago

Summary

We have to make the navigation of the (growing) interactive content of the sandbox easier, in particular for users that are not experienced with github repos and/or jupyter notebooks.

There are two main things that we should improve:

  1. The README, which is the main "landing page" for people that discover the sandbox, should be improved.
  2. We should add a "index" notebook that can be used for easy navigation when the binder instance is launched (we do not want people to click through the folders and files to find the relevant notebooks).

Potential improvements of the README

Potential index notebook for navigation in binder

As shown in the ipython-in-depth repo one can use a "index.ipynb" (note that here, they have a separate notebook in the subdir binder) that will be launched when a binder instance is created. The notebook that is displayed after startup can be configured with something like https://mybinder.org/....?filepath=binder/Index.ipynb in the URL behind the binder launch button.

The links in the markdown part of this notebook are relative links to other notebooks in the same repo. As far as I can see these links are automatically resolved so that they launch the linked notebook when running the repo on binder.

E.g. the following markdown code

This repo contains an introduction to [Jupyter](https://jupyter.org) and [IPython](https://ipython.org).

Outline of some basics:

* [Notebook Basics](../examples/Notebook/Notebook%20Basics.ipynb)
* [IPython - beyond plain python](../examples/IPython%20Kernel/Beyond%20Plain%20Python.ipynb)
* [Markdown Cells](../examples/Notebook/Working%20With%20Markdown%20Cells.ipynb)
* [Rich Display System](../examples/IPython%20Kernel/Rich%20Output.ipynb)
* [Custom Display logic](../examples/IPython%20Kernel/Custom%20Display%20Logic.ipynb)
* [Running a Secure Public Notebook Server](../examples/Notebook/Running%20the%20Notebook%20Server.ipynb#Securing-the-notebook-server)
* [How Jupyter works](../examples/Notebook/Multiple%20Languages%2C%20Frontends.ipynb) to run code in different languages.

is behind the first cell of the notebook which looks like this

Bildschirmfoto 2022-10-12 um 18 31 43

The link to the first notebook, when running on binder, is

https://hub.gke2.mybinder.org/user/ipython-ipython-in-depth-zjbry779/notebooks/examples/Notebook/Notebook%20Basics.ipynb

⚠️ ⚠️ ⚠️ Important note: I am not sure if this approach also works when running jupyterlab in binder. The shown example is using jupyter-notebooks, which works when opening a new browser tab after clicking a link. With jupyterlab this might not work because it is meant to run completely within one browser tab, having its own tabs for different notebooks. ⚠️ ⚠️ ⚠️

cchwala commented 2 years ago

index notebook is now shown as the starting page, see #34

We still have to polish things (README and index notebook) a bit more.

cchwala commented 1 year ago

The index notebook has been iterated and improved. The README sees gradual improvements, too. I close this issue in favor of specific issues, e.g. #61 and #63 .