From c48f4065b679c8f83e1bb0c362762502aea46b4f Mon Sep 17 00:00:00 2001 From: Caspar Jungbacker <74240267+CasparJungbacker@users.noreply.github.com> Date: Mon, 24 Apr 2023 17:55:12 +0200 Subject: [PATCH 1/4] Change folders --- book/_toc.yml | 5 ++--- book/{ => installation-and-setup}/git-setup.md | 0 book/{ => installation-and-setup}/vscode-setup.md | 0 3 files changed, 2 insertions(+), 3 deletions(-) rename book/{ => installation-and-setup}/git-setup.md (100%) rename book/{ => installation-and-setup}/vscode-setup.md (100%) diff --git a/book/_toc.yml b/book/_toc.yml index 092df89..a673ee5 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -4,6 +4,5 @@ root: intro parts: - caption: Installation and Setup chapters: - - file: git-setup - - file: vscode-setup - - file: dummy + - file: installation-and-setup/git-setup + - file: installation-and-setup/vscode-setup diff --git a/book/git-setup.md b/book/installation-and-setup/git-setup.md similarity index 100% rename from book/git-setup.md rename to book/installation-and-setup/git-setup.md diff --git a/book/vscode-setup.md b/book/installation-and-setup/vscode-setup.md similarity index 100% rename from book/vscode-setup.md rename to book/installation-and-setup/vscode-setup.md From e0715435efce2ff650674d4879c8bc7f58fde7e6 Mon Sep 17 00:00:00 2001 From: Caspar Jungbacker <74240267+CasparJungbacker@users.noreply.github.com> Date: Tue, 25 Apr 2023 11:35:43 +0200 Subject: [PATCH 2/4] Add new chapter --- book/cookbook/recipes.md | 130 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 book/cookbook/recipes.md diff --git a/book/cookbook/recipes.md b/book/cookbook/recipes.md new file mode 100644 index 0000000..fda865f --- /dev/null +++ b/book/cookbook/recipes.md @@ -0,0 +1,130 @@ +# 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} .png/.jpg + --- + height/width: + name: + --- +
+ ``` + +You can find more documentation on including figures [here](https://jupyterbook.org/en/stable/content/figures.html). + +## 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 + + + ``` + +## 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: + +1. 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. + +2. 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](https://matplotlib.org/stable/tutorials/introductory/customizing.html); 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. + +3. 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. + +4. 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}`` `` +- For equations, use: ``{eq}`` `` +- For citations, use: ``{cite:p}`` `` for a citation between parenthesis, or ``{cite:t}`` `` 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](https://jupyterbook.org/en/stable/interactive/hiding.html?highlight=cell%20tag). 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](https://jupyterbook.org/en/stable/content/metadata.html#jupyter-cell-tags). + +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. From 930c93ffab78be48fe83fe0a54bf58a81c416060 Mon Sep 17 00:00:00 2001 From: Caspar Jungbacker <74240267+CasparJungbacker@users.noreply.github.com> Date: Fri, 28 Apr 2023 17:49:03 +0200 Subject: [PATCH 3/4] Delete dummy --- book/dummy.md | 1 - 1 file changed, 1 deletion(-) delete mode 100644 book/dummy.md diff --git a/book/dummy.md b/book/dummy.md deleted file mode 100644 index 8ae0569..0000000 --- a/book/dummy.md +++ /dev/null @@ -1 +0,0 @@ -# Test From 229aaa2c5bc85e1e8008137e733e55ed71ae80ac Mon Sep 17 00:00:00 2001 From: Caspar Jungbacker <74240267+CasparJungbacker@users.noreply.github.com> Date: Fri, 28 Apr 2023 17:50:01 +0200 Subject: [PATCH 4/4] Update toc --- book/_toc.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/book/_toc.yml b/book/_toc.yml index a673ee5..80ce531 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -6,3 +6,6 @@ parts: chapters: - file: installation-and-setup/git-setup - file: installation-and-setup/vscode-setup + - caption: Cookbook + chapters: + - file: cookbook/recipes.md \ No newline at end of file