Contributor’s guide#

This guide provides advice on creating content for ESE Jupyter Material and its etiquette (style).

Adding notebooks#

In the github directory that creates the jupyter book, only directories with a file ‘intro.md’ or ‘intro.ipynb’ will be included in the book. The rest of the directories will be skipped, when creating the website.

Notes on notebooks

  • Each directory that includes ‘intro.md’ will be displayed in the Table of Contents by the first header from the ‘intro.md’ file. For header style guide, go to this section. Always check if your headers are consistent with other on the website!

  • If you want an automatically generated table of contents of your notebooks/directories within a specific section, then use directive:

```{tableofcontents}
```

  • Do not add Markdown tables of contents into your notebooks, the website will create one in top right corner.

  • Do not use colloquial language in the notebooks, keep your language professional.

  • Avoid referring to specific modules, e.g. do not use sentences “You will learn this in X module” or “You should know this from X module”. Instead, refer them to already existing notebooks within the primer.

  • Avoid using first person perspective and write impersonally or use pronoun “we”.

File naming#

Currently, the files are sorted with a natural sorting algorithm, meaning that files are not only sorted in alphabetical order, but also in a human order if numbers appear in the file name. This way, if you want your files to appear in the Table of Contents in a specified order, you can add integers at the begining of each file to sort them accordingly:

'1_basics.ipynb'
'2_sorting.ipynb'
...
'11_merging.ipynb'
'12_grouping.ipynb'

Notes on file naming style

  • Make your file names consistent and descriptive.

  • Use underscores instead of spaces in names.

  • Do not use brackets in your file names.

Headers in notebooks#

To make headers in Markdown cell you can use #:

# Header level 1
## Header level 2
### Header level 3
#### Header level 4
##### Header level 5
###### Header level 6

The first section title with a # in your notebook will produce the title that displays in the Table of Contents on the website. The name of the file is used for sorting purposes in the Table of Contents.

Notes on header style

  • Start your notebook with a single # header and do not make another one.

  • Please capitilise first letter of each header and leave the rest lowercase, unless it is a proper name.

Coding style#

The aim of the primer is to teach how programming can be used in mathematics, geosciences etc. It is crucial that the code on the website is of good quality and is easy to read for someone who does not have a lot of experience coding.

It is encouraged to use PEP 8 style, recommended by Python’s designer Guide van Rossum. Style guidelines involve recommendations such as naming conventions, commenting standards, line length, white space conventions etc. Adhering to these standards makes the code consistent and easier to follow for someone unfamiliar with your work.

Tips on how to make a good Python script

  • Create meaningful variable names, if used more than once. This makes the code easier to understand for other users.

  • Add only meaningful comments to your code. No need to explain what 1 + 2 does, but it is important to explain why last index is omitted from a loop.

  • “Simple is better than complex, but complex is better than complicated.” - a quote from Zen of Python which you can find here.

  • Use functions in your code - do not duplicate your code unnecessarily.

  • Try to keep things compact, but usually keep one statement per line.

  • Practice the principle of least astonishment - your code’s behaviour should not surprise other users. Write it in a way that it behaves in a way most users will expect it to behave.

  • Keep your lines shorter than the width of the website.

Cross-referencing notebooks/sections#

Sometimes it is useful to reference something from other notebook. For example, we would like to remind the user where to find a guide on writing maths in jupyter notebooks. The guide can be accessed from the maths section and the link takes us to the appropriate section. To make sure we can reference a section in a notebook, we need to label them first:

(this_is_a_label)=
# This is a section title that we want a label for

and then in text, you reference it as

This is some text and I want to reference my new label, {ref}`this_is_a_label` and a label is referenced

This method works for all labels within your jupyter book.

You can also use your own text instead of the name of the referenced section, e.g. you can find math style guide here. This can be produced with syntax

Some text here and then you can find it {ref}`here <this_is_a_label>`.

You can use cross-referencing to create customised tables of contents

  1. printing_intro

  2. Variables

  3. If statement

  4. While loops

Alternatively, use the directive described in the section above.

Notes on cross-referencing style

  • Make labels descriptive.

  • Do not make simple labels in your notebooks, e.g. “introduction”, “basics”. This way we will avoid double referencing and pointing to wrong notebooks. For example, if you are working on numerical methods, add all labels with “nm_” prefix

  • The official website provides extra syntax for referencing documents:

    {doc}`path/to/doc’

Be careful when using this style, as files may move/change names. Better to keep a label for the main header in the notebook, as it is more to remain unchanged.

Maths and equations#

In-line equations#

If you would like to include in-line equation in the Markdown text, e.g. to explain that area \(A=\pi r^2\), you should follow this syntax:

Your text goes here $A = \pi r^2$ and more text here.

Equations use standard LaTeX syntax. For some examples how to write equations in LaTeX, look here. For a comprehensive list with math symbols look here.

Math blocks#

If you would like your equation to display in the next line and centred, e.g. the area of a circle is

\[A=\pi r^2,\]

follow this syntax:

Your text goes here and then:

$$A=\pi r^2,$$

more of your text goes here.

For multiple line equations, e.g. $\(A=\pi r^2,\\ r = 15 \implies A = 706.5.\)$

use two backslashes to create the next line:

$$A=\pi r^2,\\
r = 15 \implies A = 706.5.$$

You may wish to use special LaTeX blocks, e.g. to create a matrix

\[\begin{split} \begin{pmatrix} 1 & 2\\ 5 & 6 \end{pmatrix} \end{split}\]

you can use LaTeX macros, however, remember to use backslashes to create new-lines within the macro:

$$
\begin{pmatrix}
1 & 2\\
5 & 6
\end{pmatrix}
$$

Notes on equation style

  • Please use appropriate punctuation around equations, do not forget to put a full stop when equation ends a sentence.

  • Break down long equations into more lines.

  • Do not copy special characters from other websites, find a LaTeX symbol that can be used to create such a character.

  • Default to using the $$ ... $$ syntax, as while Jupyter notebook is robust at rendering maths in different forms, the Jupyter book tends to behave more nicely with the $$...$$ environments.

Hiding and removing code cells#

If you want to hide or remove some parts of the notebook from the website, you can add tags to code cells. To enable tags in a jupyter notebook, go to View -> Cell Toolbar -> Tags. In the right hand corner of each cell you will be able to enter a tag.

Tag types

  • hide-input tag - hides the code but the user can toggle it to see

  • hide-output tag - hides the output but the user can toggle it to see

  • hide-cell tag - hides code and output but the user can toggle it to see

  • remove-input tag - will remove the code but the output will stay on display

  • remove-output tag - will keep the code but the remove the output from display

  • remove-cell tag - will remove both the code and output and user won’t see it on the website

Notes on hiding and removing cells

  • It is best to hide cells with code for plotting unless it is crucial to explain the type of plot used.

  • Hide cells with importing libraries.

  • Hide cells with exercises so that users can attempt them before the answer is revealed.

Adding module badges#

If you are working on some content closely related to a specific module taught at the university, you may wish to include a custom module badge.

To create a badge, you will need to choose a colour and a badge short code. The convention for the short code is to create a tag module-shortcode. For example, you would like to create a badge for Maths Methods 1 in hex colour #009fff with shortcode module-mm1. To do that, you will need to edit a file _static/custom.css and add following lines at the end:

.module-mm1 {
  background-color: #009fff;
}

This will create a tag, that when inserted into a cell in a notebook will automatically add a colour badge above that cell and will make a reference to that cell in the a_modules/intro page.

Special content blocks#

Jupyter Book website provides an excellent guide for creating special content blocks.

Most commonly use special content block is a blue admonition box is:

Title

text

which can be created with this syntax:

```{admonition} Title
text
```

You can hide your box, using following syntax:

```{admonition} Title
:class: dropdown
text
```

which will display as:

Title

text

Adding index#

To attach an index to a section in your notebook, use syntax:

```{index} index name
```

Notes on index style

  • Make index with capital letter first.

  • If you are referring to e.g. merging in Pandas, make index “Pandas: merging”.

  • Try to be concise.

Figures#

Figures from github repository (does not work locally!)#

To add figure from github repository, use following syntax:

```{figure} path/to/figure
:width: 100px
```
../_images/logo.png

See Jupyter Book website for more options when creating figures.

Figures from websites#

Use following syntax for figures found on websites:

<img src="https://upload.wikimedia.org/wikipedia/commons/d/d4/Gladiator_frog_Osa.JPG" width="200px">

Source: Wikimedia Commons

If you want a centred figure, follow this syntax:

<p style="text-align:center;"><img src="https://upload.wikimedia.org/wikipedia/commons/d/d4/Gladiator_frog_Osa.JPG" width="200px"></p>

Notes on figures

  • Make sure to reference the source of the figure, e.g. a website or lecture content.

Margin content#

Sometimes you want to add extra content that is useful, but it does not fit in the main text. You can use right margin for that with syntax:

``` {margin} Title
Some text in the margin
```

You can also make admonitions in the margins using a nested syntax:

````{margin}
```{admonition} Title
Some text in the margin within an admonition.
```
````

Lists#

Ordered list#

Syntax:

1. First item
2. Second item
    3. First subitem

to create

  1. First item

  2. Second item 3. First subitem

Unordered list#

Syntax:

* First item
* Second item
  * First subitem

to create

  • First item

  • Second item

    • First subitem

Tables#

Syntax:

| Header1    | Header2    |
| :--------- | ---------: |
| Row2Col1   | Row2Col2   |

to create

Header1

Header2

Row2Col1

Row2Col2

If you prefer, use Markdown table generator and copy the text.

Inline code#

To use code in line with regular text use, you should follow this syntax:

Some text and we want some code, then `code` goes into here.

Inserting code outputs into page content#

Jupyter Book website provides an excellent guide on how to glue outputs of your code into the Markdown syntax.