Getting Started

Step-by-step Guide¶

1. Ask to be added as a member of the TU Wien GitLab group TU Cookbooks by one of the administrators.

2. Create a New project.

3. Select from Create from template.

4. Select template from Group.

5. Select the custom template relevant for your cookbook. At the time of writing only the TU Cookbook Python template exists.

6. Choose the name and settings relevant to your cookbook. For now we use a naming convention that follows <Topic> Cookbook, where one needs to replace <Topic> with the intended topic of your cookbook.

Standardization with templates¶

GitLab template projects are used to ensure a coherence among the different cookbook. The templates are designed in such a way that the following aspects are standardized.

1. Code clarity

At the heart of the TU Cookbook lay of course the Jupyter Notebook. The examples should consist of clear and well contrived code. The power of Jupyter Notebook lies in the combination of code, prose, and other multimedia that can enrich real-world programming examples. A good balance between code and text should be strived for. If code becomes to dense and complex, it might be wise to abstract away some logic.

2. Code quality

Teaching by example means that the code should be of high quality. As a bare minimum we try to produce code that adheres to conventional styling guides. For example for Python code we will follow the official style guide PEP 8.

3. Dependencies

A minimal reproducibility of the Jupyter Notebooks starts with good dependency management. We should therefore keep track of external packages and their version that ensure that the code functions as intended.

4. Code testing

From the latter follows that we should ensure that a notebook can be executed without error. Unless the code example is intended to produce an error. We use the myst framework to build the cookbooks. Conveniently, building the book with myst build --execute is an easy way to see whether the notebooks intended for publication can be run in its entirety. We use GitLab Continuos Integration and Delivery (CI/CD) to build the book whenever you push to the main branch of the GitLab project, make a merge request, and every night. The status of the latter “Nightly build” can be checked by looking at the Nightly Badge in the README of the GitLab Project.

5. Attribution

We facilitate attribution of our own work by clearly stating under which license the code and the other content is created.

6. Citing

Another example of leading by example is citing work. When using images and or other resources always cite them. This is made easy with the myst framework, one can just add <doi:10.5281/zenodo.6476040> or [](doi:10.5281/zenodo.6476040) to the markdown cells. In turn, we will make cookbooks citable by minting a DOI for each release. To be developed.

7. Reviewing

We facilitate reviewing and collaboration by using git and remote store the commit history on the TU Wien GitLab group TU Cookbooks. Bug fixes and features should ideally follow through Merge requests and with clear commit messages describing the changes. We will propose a commit message standardization scheme and branching model in the near future.

8. Packaging

We propose packaging the Cookbooks as Docker images, which we will store at the DataLab registry. This has a dual purpose: 1) it allows for users to locally reproduce your cookbook, and 2) it provides an easy infrastructure to check if the notebook run in a clean environment which is equivalent to the DataLab JupyterHub.

1. Start Jupyter Lab from a Docker container:

   docker compose up

2. Copy Jupyter Lab URL to web browser:

Stop and remove the container

1. Stop Docker container with CTRL + C

2. Remove container:

   docker compose down

Again we use GitLab CI/CD to automatize packaging of your cookbook, where the pipeline gets triggered whenever you make a GitLab release with semantic versioning.

9. Publication

As already outlined myst is used for integrating the Jupyter notebooks as a TU Cookbook. It is important to understand the usage of the myst.yml which contains the structure of the book. A comprehensive guide can be found here. At the moment we have not yet thought about conventions used for the book structure. Besides building the book locally, pushing commits to the main branch triggers an automated process of building an publishing the cookbook as a GitLab page. At the moment, we, however, need to manually add the cookbook to the landing page as a new card for the gallery.

In the following chapter the design of the different templates are explained in more detail.