Markdown and Notebook recipes for the MUDE Jupyter Book

Figures

To add a figure, just copy the figure to the correct directory. Then, in your markdown file, include the figure as follows:

```{figure} <figurename>.png/.jpg
---
height/width: <height or width in pixels>
name: <name of the figure>
---
<Figure caption>
```

You can find more documentation on including figures here.

Videos

MUDE videos are uploaded to the YouTube channel. To embed them in the Jupyter Book, first obtain the embedding link of the video. In order to do so, go to the YouTube page of the video (so not the Brightspace page), then click share in the description box. There should be a button embed, click that. Copy the HTML code that appears in the panel. Then, to embed the video, use the following

```{eval-rst}
.. raw:: html

<paste the HTML code here>
```

Equations

Equations can be included in two ways: inline or display mode. To make an inline equation, just put the LaTeX equation between $-signs. For example, $F = m \cdot a$ produces: F = m \cdot a.

Display mode equations (the ones that take up a whole line), can be inserted using double $-signs, like this:

$$
    F = m \cdot a
$$

which will produce:

F = m \cdot a

Warning

Make sure there is a blank line before the display mode equations, otherwise it will render as inline and display the outer set of $ symbols. Also, the Euro symbol is not included in MathJax (see note below) and must be specified using \unicode{0x20AC} (note that it displays incorrectly in some Markdown renderers like VS Code).

To number the equations and refer in text, you need to provide a label to the equation. Just put the label between brackets and place it after the last $$, like this:

$$
    F = m \cdot a
$$ (newtons_second_law)

Note

The Jupyter Book uses MathJax to display equations, which provides some LaTeX-like functionality, but not all! For example, the Euro symbol is missing, and packages like siunitx are not available (hint, use \textrm{} and \textrm{}). When something is not working, it's useful to search for MathJax-specific solutions (hint, include "mathjax" in your Google search).

Code blocks that produce figures

This can be done with notebooks, but it's not easy to make references to figures in notebooks. You can also place the code that produces and saves the figure in a separate .py file, and include that in a markdown file. Let's say we want to make a simple sine wave:

Place the code of the figure in a .py file. In this case, sinewave.py produces our figure. The code looks like this:

 import numpy as np
 import matplotlib.pyplot as plt

 x = np.linspace(0, 2*np.pi, endpoint=True)
 y = np.sin(x)

 plt.figure()
 plt.plot(x, y)
 plt.title('$y=\sin(x)$')
 plt.xlabel('$x$')
 plt.ylabel('$y$')
 plt.savefig('sinewave.svg')

Warning

It is important that the name of the saved figure is exactly the same as the name of the Python script that generates it. Otherwise, the figure will not be generated by the Runner.

Test your code and make sure that the figure looks good. When you are ready to commit, place your code file in book/code.

The book uses a Matplotlib style sheet; to see what this looks like on your local machin you will have to run plt.style.use('../../config/matplotlibrc') after importing Matplotlib. This should be done outside of the *.py file you are creating. Note that the example style sheet path assumes you are working in the book/code directory. It is recommended to preserve a list of figures using a notebook in code_checks, where there are also working examples. It is not necessary to commit *.svg files as these are cleaned when the book is generated.

Now include the code file by using the following directives:

 ````{toggle}
 ```{eval-rst}
 .. literalinclude:: ../sinewave.py
    :language: python
 ```
 ````

Note

the outer most directive needs an extra tick mark for nested cases.

Include the figure as described above. Remember that figures are saved in the book/figures directory. We also use a naming convention of *_py.svg for figures generated from code, to easily include them in .gitignore, since they are built in the CI/CD pipeline.

References

To make references to figures, equations et cetera, use the following syntax:

For figures, use: {numref}`<name of the figure>`
For equations, use: {eq}`<equation label>`
For citations, use: {cite:p}`<bibtex_entry>` for a citation between parenthesis, or {cite:t}`<bibtex_entry>` for an inline citation.

Code

There are two ways main ways to include code: directly within a Markdown file or as a Jupyter notebook. More methods are available, but we don't include them here. The first option is great for including simple calculations, or generating simple figures when an image file is not practical. More will be added later.

Note that if you are using a *.ipynb file or including a code snippet in a *.md file, including a blank line between the text and the closing three tick marks will generate an empty code box of one line in the Jupyter Book.

Notebooks

When making notebooks for the Book, you might want to hide certain cells from the reader. For example, when including a simple figure generated from code or making a JupyterQuiz, we have to execute a code cell that generates the quiz. This code cell is ugly and distracting, so we do not want to render this in the final book.

We can change how the compiler treats notebook cells by using cell tags. You can find a detailled explanation on cell tags here. Specifically, have a look at the sections on hiding cell inputs and removing cell inputs.

The workflow of editing cell tags depends on your editor. If you're using Jupyter Lab, you can find instructions here.

For example, the following tag is used to convert the code input into either a drop-down (hide-input) or make it invisible (replace hide-input with remove-input). Replace input with output to do the same with the cell output:

{
    "tags": [
        "remove-input"
    ]
}

Once a correctly typed tag is added to the notebook it will appear in the buttons at the top and can be added to other cells. Multiple tags can be added to the same cell, in which case the tags are separated by commas.

6.7 KiB Raw Blame History