GitLab Commit is coming up on August 3-4. Learn how to innovate together using GitLab, the DevOps platform. Register for free: gitlabcommitvirtual2021.com

developer-guide.md 4.3 KB
Newer Older
1
# Developer Guide
2
3
4

This is a style guide explains how create and edit deep.TEACHING notebooks in a concise way.

5

6
## General Guidelines
7
8
9
10
11
12

- Create small and topic focused notebooks. Before your teaching material gets to complex, think about how you can split it up.
- Describe the requirement to understand the lesson as accurately as possible.
- Offer exercises to practice
- Does your notebook require program code that is not directly related to the teaching material, such as extensiv data preprocessing, use the related Python Module: [Deep Teaching Commons](https://gitlab.com/deep.TEACHING/deep-teaching-commons) to provide it.

13

14
15
## Git Branches

Christoph Jansen's avatar
Christoph Jansen committed
16
17
18
First of all, please do not make changes in the `master` branch.

Create your pull request for the `dev` branch. As soon as it is merged into `dev`, the website will be rebuilt and deployed under [dev.deep-teaching.org](https://dev.deep-teaching.org) as part of the Continuous Integration (CI) pipeline. The main purpose of the `dev` branch is to identify breaking changes in the website build process or in the HTML rendering.
19

20
We will merge `dev` into `master` at some point, which will then trigger an update for [www.deep-teaching.org](https://www.deep-teaching.org/).
21

Christoph Jansen's avatar
Christoph Jansen committed
22
23
If you don't want unfinished notebooks to appear on [dev.deep-teaching.org](https://dev.deep-teaching.org) or [www.deep-teaching.org](https://www.deep-teaching.org/) you should consider creating a feature branch for the notebook. You can merge your feature branch into `dev` as soon as it's ready.

24

25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
## Git Folder Structure

If you contribute to that repository, please follow this folder structure:

    .
    ├── media
    │   ├── new_developer       # Create a your own media folder and declare under which license your materials may be used.
    ├── notebooks               #
    │   ├── topic A             #
    │   │   ├── my_new_notebook # Create your teaching notebook under a appropriate topic or create a new one. Your notebook name should indicate the teaching content.
    │   │   └── ...
    │   ├── topic B
    │   └── ...
    └── ...

40

41
42
## Notebook Structure

Patrick Baumann's avatar
Patrick Baumann committed
43
All notebooks have the same structure, so that all deep.TEACHING materials have a similar design. To maintain consistency we offer a [blueprint](notebooks/uncategorized/blueprint.ipynb) notebook that should be used to create your own teaching materials. The reference implementatition [notebooks/sequence-learning/exercise-bi-gram-language-model.ipynb](notebooks/sequence-learning/exercise-bi-gram-language-model.ipynb) serves as an example.
44

45
46
47
48
49
50

## Coding Style

Be compliant with the [PEP8 - Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/)


51
52
## Links

53
Links are required to comply with linking behavior in Jupyter Lab, which means that all links from file A to file B are relative to the path of file A.
54

55
Consider this directory structure:
56
57

```no-highlight
58
59
60
61
62
63
.
├── foo.md
├── notebooks
│   ├── bar.ipynb
├── media
│   ├── baz.png
64
65
```

66
The following links will work:
67
68

```
69
70
71
[link from bar.ipynb to foo.md](../foo.md)
[link from foo.md to bar.ipynb](notebooks/bar.ipynb)
![embedding image in foo.md](media/baz.png)
72
73
74
75
76
77
78
79
80
81
82
83
84
85
```

It is possible to reference a section within a `*.md` markdown file.

```no-highlight
[Section Links](#Links)
```

An external link works as expected.

```no-highlight
[Educational Materials on Gitlab](https://gitlab.com/deep.TEACHING/educational-materials)
```

86
## Jupyter Lab
87

Christoph Jansen's avatar
Christoph Jansen committed
88
We are using Jupyter Lab, not Jupyter Notebook Server, as a development platform. Ensuring compatibility with Jupyter Lab is **first priority**. Making sure that the HTML version on [www.deep-teaching.org](https://www.deep-teaching.org/) renders correctly is considered a **sencond priority** and must be adressed without breaking Jupyter Lab compatibility. As of version 0.31.12, Jupyter Lab does not provide a way to use CSS styles in notebooks, therefore no custom CSS is used.
89

90
91
92
93

## Citation Style

Citation of literature is based on the [IEEE editorial style manual](https://www.ieee.org/conferences_events/conferences/publishing/style_references_manual.pdf). Only in the case of in-text citations we deviate from these specifications. Instead of a reference number we use the first three letters of the surname of the main author and the last two numbers of the publication year.