How to format notebooks
This issue is used to collect our formatting rules for each notebook.
Notebook sections
Each notebook has to be separated into sections separated by markdown headers.
We allow 4 levels of headers:
Level 1 (#)
Level 2 (##)
Level 3 (###)
Level 4 (####)
Each subsection of the notebook needs to be at level 2, with subsections of level 2 being level 3 and so on.
Each subsection and its subsections have to be numbered:
Notebook Title
1 - Subsection 1
1.1 - Sub-Subsection 1
1.1.1 - Sub-Sub-Subsection
1.2 - Sub-Subsection 2
2 - Subsection 2
If a subsection at level 2 has a subsection it has to be underlined with a line of 2px thickness:
<hr style="border:2px solid black"> </hr>
If a subsection at level 3 has a subsection it has to be underlined with a line of 1px thickness:
<hr style="border:1px solid black"> </hr>
The only exception to this rule is the first subsection.
Fixed cells
- The first cell of the notebook has to be a hidden init cell containing required inputs for other init cells. (See input cells for more info)
- The second cell of the notebook contains only the underlined title.
- The title of the notebooks needs to be at level 1 with no other header being allowed to be at this level.
- The title of the notebook is underlined with a line of 2px thickness:
<hr style="border:2px solid black"> </hr>
The first subsection of a notebook needs to be a description:
## 1 - Description
Separation lines
After each section of levels 2 and 3, a separation line has to be inserted:
___
as a markdown cell
This cell should not contain any other text.
In level 4 the sections are not separated by a line.
Input cells
- Each input cell has to be an init cell. For this, the
Initialization cells
nbextesion is needed. - Each input cell has to be colored blue. This is done by importing
from sctoolbox.utils import bgcolor
and adding%bgcolor PowderBlue
at the top of each cell. - The bgcolor import has to be in the first cell of the notebook. This notebook cell needs to be hidden. This can be done with the runtools nbextension. The hidden cell also needs to be an init cell.
- Before each input cell a markdown cell containing
<h1><center>⬐ Fill in input data here ⬎</center></h1>
has to be placed. - After each input cell a separation line (Markdown cell containing
___
) has to be placed.
Locked cells
Each cell has to be locked using the runtools
nbextension except for the input cells.