Merge branch 'main' into 'publish'

Small changes

See merge request interactivetextbooks-citg/jupyter-book-manual!10

book/_config.yml

@@ -1,6 +1,6 @@
 title: Intro to Git, VS Code and Jupyter Books
 author: Caspar Jungbacker
-logo: images/MUDE_Logo-small.png
+logo: images/TUDelft_logo_rgb.png
 
 execute:
   execute_notebooks: auto

book/_toc.yml

@@ -4,6 +4,9 @@ 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
+    - file: installation-and-setup/jupyter-book-setup
+  - caption: Cookbook
+    chapters:
+    - file: cookbook/recipes.md

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} <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](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
+    
+    <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:
+
+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}`<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](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.

book/dummy.md

@@ -1 +0,0 @@
-# Test

book/git-setup.md

@@ -1,67 +0,0 @@
-# Git
-
-
-## Installation
-
-First, we need to install Git itself. 
-
-````{tab} Windows
-1. Go to [this webpage](https://git-scm.com/download/win) and download the correct version of Git for your system.
-2. Execute the installer and go through it. You can leave all options to the default values, **but make sure the option "Git from the command line and also from 3rd-party software" is selected**. Without this option, we won't be able to use Git from VS Code.
-3. Once the installation is finished, check if everything works. Open a command prompt, and execute the command `git`. If Git is installed correctly, you should see some sort of help page. If it outputs an error, then something may went wrong with the installation (you may have selected a wrong option).
-````
-````{tab} MacOS
-Open up a terminal window. Then, type the command `git`. If Git has been installed already, it will output some help. If Git has not been installed, you will get a pop-up that looks something like this:
-
-```{figure} images/install-Xcode-CLT.png
-```
-
-Click on `install`. The installation may take a couple of minutes. Once it's finished, check if everything has been installed correctly by exectuting `git` again.
-````
-
-## Setting up SSH-keys
-
-When we want to visit the MUDE repositories on GitLab, we need to log in. The same holds if we want to interact with these repositories with Git from VS Code. This means that everytime we make a commit, pull, et cetera, we need to provide our password which becomes very tedious. Alternatively, we can provide GitLab with an SSH-key of our sytem, so that GitLab knows it is indeed us that are making the changes to the repository, removing the need to provide a password. 
-
-1. Open up a terminal window (Git Bash on Windows). Next, type (or copy and paste) the following command:
-
-        ssh-keygen -t ed25519 -C "GitLab"
-
-2. You will get output that looks something like this:
-    
-        Generating public/private ed25519 key pair.
-        Enter file in which to save the key (/Users/<user>/.ssh/id_ed25519):
-
-    Press enter to use the default path. Keep note of this path, as we will need to visit it later on.
-
-3. You will now be asked to enter a passphrase. You can give one, but you will be asked for it everytime you make a commit, so it's better to leave this field emtpy and use this key only for GitLab. After the command is done executing, it will generate two files: `id_ed25519` and `id_ed25519.pub`. The `.pub` file is the public part of the SSH-Key which we need.
-
-
-4. Go to [GitLab](https://gitlab.tudelft.nl) and log in. Click on your profile icon on the top-right of the page, then go to Preferences. In the menu on the left, go to SSH-Keys. You are now greeted with a screen that looks like this:
-
-```{figure} images/gitlab-ssh-screen.png
-```
-
-5. Open the `id_ed25519.pub` file that we generated in step 2. Copy its contents and paste it in the 'Key' field of SSH-Keys menu. Give the key a Title and click 'Add key'. 
-
-    ```{note}
-    On MacOS, the `.ssh/` folder is hidden by default, so you won't be able to find it in finder. To show hidden files and folders, press **Command + Shift + .**
-    ```
-
-6. Now test the connection. Go to the terminal (Git Bash on windows) and type:
-
-        ssh -vT git@gitlab.tudelft.nl
-
-    You should get a huge output, but somewhere in that output it should say something like:
-
-        Welcome to GitLab, <netid>!
-
-## Updating the local Git environment
-
-The final step is to provide a username and email address to Git, so our commits can be identified. To do this, type in the following command for the username:
-
-    git config --global user.name "<first name> <last name>"
-
-And type the following command to set the email address:
-
-    git config --global user.email "<your TU Delft email>"

book/installation-and-setup/git-setup.md

@@ -0,0 +1,67 @@
+# Git
+
+
+## Installation
+
+First, we need to install Git itself. 
+
+````{tab} Windows
+1. Go to [this webpage](https://git-scm.com/download/win) and download the correct version of Git for your system.
+2. Execute the installer and go through it. You can leave all options to the default values, **but make sure the option "Git from the command line and also from 3rd-party software" is selected**. Without this option, we won't be able to use Git from VS Code.
+3. Once the installation is finished, check if everything works. Open the start menu, then type `git`. From the search results, open the application `Git Bash`. This will open a terminal window, in which you can execute commands. Type in the command `git`, and execute it by pressing enter. If Git is installed correctly, you should see some sort of help page. If it outputs an error, then something may went wrong with the installation (you may have selected a wrong option).
+````
+````{tab} MacOS
+Open up a terminal window (*Command + Space*, type in `terminal`). Then, type the command `git`. If Git has been installed already, it will output some help. If Git has not been installed, you will get a pop-up that looks something like this:
+
+```{figure} ../images/install-Xcode-CLT.png
+```
+
+Click on `install`. The installation may take a couple of minutes. Once it's finished, check if everything has been installed correctly by exectuting `git` again.
+````
+
+## Setting up SSH-keys
+
+When we want to visit repositories on GitLab, we need to log in. The same holds if we want to interact with these repositories with Git from VS Code. This means that everytime we make a commit, pull, et cetera, we need to provide our password, which becomes very tedious. Alternatively, we can provide GitLab with an SSH-key of our sytem, so that GitLab knows it is indeed us that are making the changes to the repository, removing the need to provide a password. 
+
+1. Open up a terminal window (Git Bash on Windows). Next, type (or copy and paste) the following command:
+
+        ssh-keygen -t ed25519 -C "GitLab"
+
+2. You will get output that looks something like this:
+    
+        Generating public/private ed25519 key pair.
+        Enter file in which to save the key (/Users/<user>/.ssh/id_ed25519):
+
+    Press enter to use the default path (the one between parenthesis). Keep note of this path, as we will need to visit it later on.
+
+3. You will now be asked to enter a passphrase. You can give one, but you will be asked for it everytime you make a commit, so it's better to leave this field emtpy and use this key only for GitLab. After the command is done executing, it will generate two files: `id_ed25519` and `id_ed25519.pub`. The `.pub` file is the public part of the SSH-Key which we need.
+
+
+4. Go to [GitLab](https://gitlab.tudelft.nl) and log in using your NetID. Click on your profile icon on the top-right of the page, then go to Preferences. In the menu on the left, go to SSH-Keys. You are now greeted with a screen that looks like this:
+
+```{figure} ../images/gitlab-ssh-screen.png
+```
+
+5. Navigate to the `id_ed25519.pub` file that we generated in step 2. Open the file with a text editor (Notepad on Windows, textEdit on Mac). Copy its contents and paste it in the 'Key' field of SSH-Keys menu. Give the key a Title and click 'Add key'. 
+
+    ```{note}
+    On MacOS, the `.ssh/` folder is hidden by default, so you won't be able to find it in finder. To show hidden files and folders, press **Command + Shift + .**
+    ```
+
+6. Now test the connection. Go to the terminal (Git Bash on windows) and type:
+
+        ssh -vT git@gitlab.tudelft.nl
+
+    You should get a huge output, but somewhere at the end of that output it should say something like:
+
+        Welcome to GitLab, <netid>!
+
+## Updating the local Git environment
+
+The final step is to provide a username and email address to Git, so our commits can be identified. To do this, in the terminal (Git Bash on Windows) type in the following command for the username:
+
+    git config --global user.name "<first name> <last name>"
+
+And type the following command to set the email address:
+
+    git config --global user.email "<your TU Delft email>"

book/installation-and-setup/jupyter-book-setup.md

@@ -0,0 +1,7 @@
+# Jupyter Book
+
+Jupyter Book is just a regular Python package, so it can be installed by using `pip` or `conda`: 
+
+    pip install jupyter-book
+
+Nevertheless, it's always a good idea make a fresh `conda` environment when starting a new project.