Getting Started

Quick Start¶

Before you start writing your cookbook have a quick read over these cookbook and notebook considerations.

After reading the considerations you should:

1. Install the copier tool

2. Render a local repository from a template (see here)

3. Create a remote repository (see here)

4. Create a Git repository from the local template (see here)

5. Upload (push) the local repository to TU Wien GitLab (see here)

Use the Appropriate Template¶

Choose a template depending on the programming language of your Choice.

Currently available are:

• TU Cookbook Python Template

Once that is done follow the instructions in the Template’s Documentation for the technical setup of a cookbook. Use a name for the template that ends with “Cookbook”, like “Networks Cookbook”.

Turn it into a Cookbook¶

We use myst as the book building framework. The most important file is the myst.yml. Here you can add your notebooks which will become the chapters of your cookbook.

Table of contents:

project:
  toc:
    - file: root.md
    - file: first-child.ipynb
    - file: second-child.md

But also configuration, front matter and metadata are included in this file.

title: My First Article
date: 2022-05-11
authors:
  - name: Mason Moniker
    affiliations:
      - University of Europe

The easiest way is to use Jupyter notebooks as chapters. But it is possible to use exclusively markdown text files by adding code cells to markdown files, like so:

```{code-cell} python
hello = "hello"
there = "there"
phrase = f"{hello}, {there}!"
print(phrase)
```

Myst has rich features for scientific reporting, such as, citing academic work, e.g., [](doi:10.5281/zenodo.6476040). Have a look at the extensive mystmd guide for more inspiration.

GitLab Repository Setup¶

1. Open the Browser and go to the TU GitLab

2. Create a new repository in the private Group. Ask the admins to be added as a maintainer to this group if you do not have access yet.

3. Make sure the GitLab repo does NOT contain any files (no automatic readme generation)

Local Repository Setup¶

1. Initialize a Git repository

   git init

2. Configure git user email to match your TU GitLab account (command can be copied from the empty GitLab repo you created)

   git config --local user.email <YOUR-EMAIL>

3. Commit all files

   git add .
   git commit -m "initial commit"

Push your Changes¶

1. Add the GitLab repo as a remote to the local repo (can be copied from the GitLab repo as well)

   git remote add origin <URL>

2. Push the repo to GitLab (should be included when copying the previous command from GitLab)

   git push

   Now the TU Cookbook will automatically build as static GitLab pages and as as a BinderHub image.

🚀🚀 Check out your new TU Cookbook 🚀🚀