diff --git a/content/index.md b/content/index.md index c006e63..f4ed8a0 100644 --- a/content/index.md +++ b/content/index.md @@ -66,7 +66,7 @@ them to own projects**. - 12:45-13:30 - Working with Notebooks - Notebooks and version control - Other tooling - - Sharing notebooks + - {doc}`notebooks/sharing` - 13:30-14:15 - Other useful tools for Python development - {doc}`good-practices` @@ -128,6 +128,7 @@ documentation collaboration dependencies testing +notebooks/sharing refactoring-concepts good-practices profiling diff --git a/content/notebooks/binder.jpg b/content/notebooks/binder.jpg new file mode 100644 index 0000000..d04c467 Binary files /dev/null and b/content/notebooks/binder.jpg differ diff --git a/content/notebooks/sharing.md b/content/notebooks/sharing.md new file mode 100644 index 0000000..963c78c --- /dev/null +++ b/content/notebooks/sharing.md @@ -0,0 +1,83 @@ +# Sharing notebooks + +:::{objectives} +- Know about good practices for notebooks to make them reusable +- Have a recipe to share a dynamic and reproducible visualization pipeline +::: + +[this lesson is adapted after ] + + +## Document dependencies + +- If you import libraries into your notebook, note down their versions. + Document the dependencies as discussed in section {doc}`../dependencies`. + +- Place either `environment.yml` or `requirements.txt` in the same folder as + the notebook(s). + +- If you publish the notebook as part of a publication, it is probably a good + idea to **pin the versions** of the libraries you use. + +- This is not only useful for people who will try to rerun this in future, it + is also understood by some tools (e.g. [Binder](https://mybinder.org/)) which we + will see later. + + +## Different ways to share a notebook + +We need to learn how to share notebooks. At the minimum we need +to share them with our future selves (backup and reproducibility). + +- You can enter a URL, GitHub repo or username, or GIST ID in [nbviewer](https://nbviewer.jupyter.org/) and view a rendered Jupyter notebook +- Read the Docs can render Jupyter Notebooks via the [nbsphinx package](https://nbsphinx.readthedocs.io/) +- [Binder](https://mybinder.org/) creates live notebooks based on a GitHub repository +- [EGI Notebooks](https://notebooks.egi.eu) (see also ) +- [JupyterLab](https://github.com/jupyterlab/jupyterlab) supports sharing and collaborative editing of notebooks via Google Drive. Recently + it also added support for [Shared editing with collaborative notebook model](https://github.com/jupyterlab/jupyterlab/pull/10118). +- [JupyterLite](https://jupyterlite.readthedocs.io/en/latest/) creates a Jupyterlab environment in the browser and can be hosted as a GitHub page. +- [Notedown](https://github.com/aaren/notedown), [Jupinx](https://github.com/QuantEcon/sphinxcontrib-jupyter) and [DocOnce](https://github.com/hplgit/doconce) can take Markdown or Sphinx files and generate Jupyter Notebooks +- [VoilĂ ](https://voila.readthedocs.io/en/stable/) allows you to convert a Jupyter Notebook into an interactive dashboard +- The `jupyter nbconvert` tool can convert a (`.ipynb`) notebook file to: + - python code (`.py` file) + - an HTML file + - a LaTeX file + - a PDF file + - a slide-show in the browser + + +The following platforms can be used free of charge but have **paid subscriptions** for +faster access to cloud resources: +- [CoCalc](https://cocalc.com/) (formerly SageMathCloud) allows collaborative editing of notebooks in the cloud +- [Google Colab](https://colab.research.google.com/) lets you work on notebooks in the cloud, and you can [read and write to notebook files on Drive](https://colab.research.google.com/notebooks/io.ipynb) +- [Microsoft Azure Notebooks](https://notebooks.azure.com/) also offers free notebooks in the cloud +- [Deepnote](https://deepnote.com/) allows real-time collaboration + + +## Sharing dynamic notebooks using [Binder](https://mybinder.org/) + +::::{challenge} Exercise/demo: Making your notebooks reproducible by anyone (15 min) +Instructor demonstrates this: +- First we look at the statically rendered version of the [example + notebook](https://github.com/workshop-material/classification-task/blob/main/example.ipynb) + on GitHub and also [nbviewer](https://nbviewer.jupyter.org/). +- Visit [https://mybinder.org](https://mybinder.org): + :::{figure} binder.jpg + :alt: Screenshot from mybinder.org user interface + ::: +- Check that your notebook repository now has a "launch binder" + badge in your `README.md` file on GitHub. +- Try clicking the button and see how your repository is launched + on Binder (can take a minute or two). Your notebooks can now be + explored and executed in the cloud. +- Enjoy being fully reproducible! +:::: + + +## How to get a digital object identifier (DOI) + +- [Zenodo](https://zenodo.org/) is a great service to get a + [DOI](https://en.wikipedia.org/wiki/Digital_object_identifier) for a notebook + (but **first practice** with the [Zenodo sandbox](https://sandbox.zenodo.org/)). +- [Binder](https://mybinder.org/) can also run notebooks from Zenodo. +- In the supporting information of your paper you can refer to its DOI.