admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-13 14:55:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Restructuring before importing from MUDE book

Browse source
This commit is contained in:
Tom van Woudenberg 2024-02-26 09:00:26 +01:00
parent 78349a40a1
commit eaae618d88
16 changed files with 245 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

65
book/features/grasple.md Normal file
View file

@ -0,0 +1,65 @@
# Embedding Grasple question
[Grasple](https://app.grasple.com/) gives you an embed code for each exercise which looks like this, which can be added cirectly to your markdown-file.
```html
<iframe height="560" src="https://embed.grasple.com/exercises/767782d5-023a-4b49-a1f3-874fca626c8e?id=79907" title="Grasple Exercise 79907" width="100%" allow="clipboard-read; clipboard-write"></iframe>
```
The embed link is created for an exercise under 'More'- 'Embed Exercise'
This iframe can be embedded into your Jupyter book.
```{admonition} Note
:class: tip
This feature doesn't display in a book that is viewed locally via your browser, unless you set up a local webserver (instructions [here](setup-local-server)).
```
The code shown above gives:
<iframe height="560" src="https://embed.grasple.com/exercises/767782d5-023a-4b49-a1f3-874fca626c8e?id=79907" title="Grasple Exercise 79907" width="100%" allow="clipboard-read; clipboard-write"></iframe>
More information on Grasple and the support of TU Delft can be found on: [Teaching Support - Educational Tools - Grasple](https://www.tudelft.nl/en/teaching-support/educational-tools/grasple)
## Replace iframe by QR code for printed version
Dani Balague Guardia created an [extension](https://github.com/dbalague/sphinx-grasple) which allows you to easily add Grasple question with some formatting and, more importantly, the creation of QR codes in the PDF version of the page. This leads to the source link of the iframe.
This extension can be installed by running
`pip install git+https://github.com/dbalague/sphinx-grasple`
The grasple exercise as shown above can now be added as follows in your markdown file:
```markdown
::::{grasple}
:url: https://embed.grasple.com/exercises/767782d5-023a-4b49-a1f3-874fca626c8e?id=79907
:label: grasple_exercise_1
:dropdown:
:description: Example of exercise which goes along
::::
```
This leads to the following html in the Jupyter book. Remark: again, the iframe doesn't locally in VScode or in the build file, only on the hosted version.
<div class="grasple admonition" id="grasple_exercise_1">
<p class="admonition-title"><span class="caption-number">Grasple Exercise 1 </span></p>
<div class="section" id="admonition-content">
<div class="side-by-side docutils container">
<div class="description-container docutils container">
<p></p><p>Example of exercise which goes along</p>
<p></p>
</div>
</div>
<details class="dropdown"><summary>Show/Hide Content</summary><iframe src="https://embed.grasple.com/exercises/767782d5-023a-4b49-a1f3-874fca626c8e?id=79907" width="100%" height="400px"></iframe></details></div>
</div>
In the PDF this leads to:
```{figure} ../images/Grasple_pdf.png
```
The extension requires an extension of the `config.yml` file:
```markdown
extra_extensions:
- sphinx_grasple
- sphinx.ext.imgconverter
```
The extension should be installed both locally and on the server.

31
book/features/h5p.md Normal file
View file

@ -0,0 +1,31 @@
# Adding interactive h5p elements
## Instruction
H5p elements are interactive HTML-blocks which can be imbeded in a Jupyter Book using an iframe. H5p element can be created in the [TU Delft portal on the H5p website](https://tudelft.h5p.com/content) (sign in via Brightspace to H5p required first). The iframe code can be copied at Edit - Publish - Public - Embed code. This html code can be directly added to your markdown file:
```html
<iframe src="https://tudelft.h5p.com/content/.../embed" aria-label="..." width="1088" height="200" frameborder="0" allowfullscreen="allowfullscreen" allow="autoplay *; geolocation *; microphone *; camera *; midi *; encrypted-media *"></iframe><script src="https://tudelft.h5p.com/js/h5p-resizer.js" charset="UTF-8"></script>
```
A full list of all available interactive elements is available on the website of [H5p](https://h5p.org/content-types-and-applications), these include among others:
- Multiple choice questions
- Fill in the blanks
- Drag and drop
- Interactive video
- Image hotspot
More information on H5p: [Teaching Support - Educational Tools - H5P](https://www.tudelft.nl/teaching-support/educational-tools/h5p)
## Example
Truss structures are modelled as rigid bars (so elements which cannot deform) connected by hinges (so elements can rotate with respect to one each other). In our model, hinges are indicate with a circle, and bars with a line. For example, the structure you've seen in the second example (with two diagonal bars removed) is modelled as follows:
```{figure} ../images/Truss1.svg
:name: truss structure
Bars and hinges in truss structure
```
Now that you've been introduced to truss structures, answer the following question:
<iframe src="https://tudelft.h5p.com/content/1291910926067816717/embed" aria-label="Modelling truss structures" width="1088" height="200" frameborder="0" allowfullscreen="allowfullscreen" allow="autoplay *; geolocation *; microphone *; camera *; midi *; encrypted-media *"></iframe><script src="https://tudelft.h5p.com/js/h5p-resizer.js" charset="UTF-8"></script>

40
book/features/jupyterlite/configuration.md Normal file
View file

@ -0,0 +1,40 @@
# Configuration
In order to use Jupyterlite, we need to update the configuration of our book a bit. First, make sure you have the correct packages installed. These are:
jupyterlite-sphinx
jupyterlite-xeus-python
You can install these using `pip`. Make sure these are also defined in the `requirement.txt`!
## Configuring the kernel
There are multiple Python kernels available that work in the browser. Two popular ones are [Pyodide] and [`Xeus-Python`]. The latter allows you to install packages from `conda-forge` during build time, making them immediately available on your website. In this example, `Xeus-Python` will be used.
When you have installed `jupyterlite-xeus-python`, the kernel will automatically be included in the build without any configuration. However, the default kernel only comes with `numpy`, and we want to make sophisticated interactive content, for example with `matplotlib` and `ipywidgets`. `Xeus-Python` can install these packages itself with `conda`. All we need to do is give it a list of the packages we want installed. To this end, we need to make a configuration file for `jupyterlite` containing settings that will be passed to `Xeus-Python`. The configuration file needs to be in JSON format, and needs to be placed in the root directory of your repository (where `requirements.txt` and `.gitlab-ci.yml` live). In this file, we can specify which packages need to be installed in the kernel as follows:
{
"XeusPythonEnv": {
"packages": [
"numpy",
"matplotlib",
"ipywidgets"
]
}
}
## Updating the Jupyter Book `_config.yml`
Since `jupyterlite-sphinx` is a Sphinx extension, we need to tell Jupyter Book to include it in the build process and specify the name of the `jupyterlite` configuration file. To do so, create a new entry in `_config.yml` like this:
sphinx:
extra_extensions:
- jupyterlite-sphinx
config:
jupyterlite_config: jupyterlite-config.json
Of course, change `jupyterlite-config.json` to the name of your configuration file.
## Building
When everything is configured correctly, a `Xeus-Python` kernel will be built when you build your book via `jupyter book build`. You can check this by keeping an eye on the output in the terminal: you should see a lot of extra lines mentioning `JupyterLite`.

108
book/features/jupyterlite/including-jupyterlite.md Normal file
View file

@ -0,0 +1,108 @@
# Adding `JupyterLite` to a page
There are three different `JupyterLite` directives that you can include in your web page:
1. `retrolite`: this embeds the old Jupyter Notebook environment in your page. This is a good one if you want students to program things on you page, since it allows students to edit and execute cells.
2. `jupyterlite`: this embeds a JupyterLab environment in your page.
3. `replite`: this variant provides an environment similar to the regular `IPython` kernel.
Below are examples demonstrating how to include each variant. Note that the `jupyterlite-sphinx extension` is designed for use with `.rst` files (Restructured Text). Luckily, `MyST` provides a convenient directive that allows us to include Restructured Text content in a regular `.md` file.
```{admonition} Note
:class: tip
This feature doesn't display in a book that is viewed locally via your browser, unless you set up a local webserver (instructions [here](setup-local-server)).
```
## `retrolite`
To embed a Jupyter Notebook environment in your book, include the following directive:
```{eval-rst}
.. retrolite::
```
You can also include you own notebook for students to work with. To do so, add it to the directive like this:
```{eval-rst}
.. retrolite:: wave.ipynb
```
Finally, there are some formating options available:
```{eval-rst}
.. retrolite:: wave.ipynb
:width: 100% # The width of the box
:height: 500px # The height of the box
:prompt: Click me! # Instead of loading the kernel immediately, show a button
that activates the kernel on clicking.
:prompt_color: #00aa42 # Color of the prompt button
```
Here is the final result of the directive above:
```{eval-rst}
.. retrolite:: wave.ipynb
:width: 100%
:height: 500px
:prompt: Click me!
:prompt_color: #00aa42
```
## `jupyterlite`
To embed a JupyterLab environment in your book, simply change out `retrolite` for `jupyterlite`:
```{eval-rst}
.. jupyterlite::
:width: 100%
:height: 500px
:prompt: Click me!
:prompt_color: #00aa42
```
Here is the final result:
```{eval-rst}
.. jupyterlite::
:width: 100%
:height: 500px
:prompt: Click me!
:prompt_color: #00aa42
```
## `replite`
The `replite` directive provides a REPL environment (Read-Evaluate-Print-Loop) that is very similar to `IPython` in the terminal. Here's how you can include it:
```{eval-rst}
.. replite::
:width: 100%
:height: 500px
:prompt: Click me!
:prompt_color: #00aa42
```
You can't include a notebook in a `replite` environment, but you can pass it some code that executes once the kernel is loaded:
```{eval-rst}
.. replite::
:width: 100%
:height: 500px
:prompt: Click me!
:prompt_color: #00aa42
print("Hello, world!")
```
Here's what it looks like:
```{eval-rst}
.. replite::
:width: 100%
:height: 500px
:prompt: Click me!
:prompt_color: #00aa42
print("Hello, world!")
```

91
book/features/jupyterlite/interactive-wave.ipynb Normal file
View file

File diff suppressed because one or more lines are too long

11
book/features/jupyterlite/jupyterlite-gallery.md Normal file
View file

@ -0,0 +1,11 @@
# Gallery
On this page, you can find some example usage of `JupyterLite`. The reader is invited to contribute to this gallery with their own interesting examples.
## Interactive plot
```{eval-rst}
.. retrolite:: interactive-wave.ipynb
:width: 100%
:height: 600px
```

23
book/features/jupyterlite/jupyterlite.md Normal file
View file

@ -0,0 +1,23 @@
# Interactive elements with JupyterLite-Sphinx
By popular demand: how to include interactive pieces of code in your Jupyter Book. We can do this by using the [JupyterLite](https://github.com/jupyterlite) app, which allows you to run a Jupyter Lab session and execute Python code entirely in-browser. Jupyterlite can be embedded in a Jupyter Book with the [`JupyterLite-Sphinx`](https://github.com/jupyterlite/jupyterlite-sphinx) extension.
## An example
You can try JupyterLite below. It has `numpy`, `matplotlib` and `scipy` installed.
```{eval-rst}
.. replite::
:width: 100%
:height: 600px
```
## What you can and can't do
JupyterLite is ideal for including small interactive pieces of content on a page. For example, you may want to include a `matplotlib` plot with some sliders to play with. Or you may have a small model that requires a student to provide some input parameters and then gives some output. It is important to note that JupyterLite makes use of the browser cache for memory, meaning that the state of a JupyterLite element is lost when the user leaves a page. Hence, it may not be a good idea to ask student to code a lot by hand, as they loose all of their progress when the page is closed.
It is possible to install packages in the kernel that will be shipped with your book. However, there are some strict limitations to what packages can be installed. For once, they should be listed on `conda-forge`. In addition, the package needs to be a [`noarch`](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/packages.html#noarch-packages) package. In theory, you can install your own packages if it meets those two requirements, but we have no experience in doing that (feel free to try it out yourself, so that we can add instructions to the manual!).
```{warning}
Including JupyterLite in your book imposes some requirements on the Docker image that is used in the CI/CD pipeline. Specifically, you need to have access to Anaconda. If you know what you're doing, have a look at the [`.gitlab-ci.yml`](https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual/-/blob/main/.gitlab-ci.yml) of this repository.
```

108
book/features/jupyterlite/wave.ipynb Normal file
View file

File diff suppressed because one or more lines are too long

130
book/features/recipes.md Normal file
View file

@ -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.