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

Merge branch 'main' into user_type_3

Browse source
This commit is contained in:
Tom van Woudenberg 2024-10-22 17:21:43 +02:00
commit 4d79f6ef2d
16 changed files with 36 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

3
.gitmodules vendored
View file

@ -16,3 +16,6 @@
[submodule "book/external/TeachBooks"]
path = book/external/TeachBooks
url = https://github.com/TeachBooks/TeachBooks.git
[submodule "book/external/Sphinx-Image-Inverter"]
path = book/external/Sphinx-Image-Inverter
url = https://github.com/TeachBooks/Sphinx-Image-Inverter.git

1
book/_toc.yml
View file

@ -47,6 +47,7 @@ parts:
- file: features/custom_toc.md
- file: features/custom_download.md
- file: external/Nested-Books/README.md
- file: external/Sphinx-Image-Inverter/README.md
- file: features/interactive_element.ipynb
sections:
- file: features/grasple.md

2
book/basic-features/References.md
View file

@ -21,5 +21,3 @@ Or, the derivation results in equation {eq}`<eq:Newton>`.
$$ F = m\cdot a $$(eq:Newton)

6
book/basic-features/banner.md
View file

@ -10,7 +10,7 @@ name: banner_mude
Example of a banner in the MUDE book.
```
This is a commonly used feature, desribed in the [Jupyter Book manual here](https://jupyterbook.org/en/stable/web/announcements.html). However, note that if you are using the Sphinx-Thebe interactive Python feature, or other features that customize the top part of a Jupyter Book website (for example, the download page buttons), the banner does not always work. In this case, the banner should be specified using the `announcement` option in the `html_theme_options` setting in the `_config.yml` file:
This is a commonly used feature, described in the [Jupyter Book manual here](https://jupyterbook.org/en/stable/web/announcements.html). However, note that if you are using the Sphinx-Thebe interactive Python feature, or other features that customize the top part of a Jupyter Book website (for example, the download page buttons), the banner does not always work. In this case, the banner should be specified using the `announcement` option in the `html_theme_options` setting in the `_config.yml` file:
```
sphinx:
@ -23,9 +23,9 @@ sphinx:
```
```{tip}
Note that you should always enclose your announcement in quotes to make it a complete string. Use a different type of quote if your announcement itself contains them (for example, `"like 'this'"`). If you are using HTML elements, it is best to make your announcement a complete HTML tag, not Markdown with HTML inside.
You should always enclose your announcement in quotes to make it a complete string. Use a different type of quote if your announcement itself contains them (for example, `"like 'this'"`). If you are using HTML elements, it is best to make your announcement a complete HTML tag, not Markdown with HTML inside.
Markdown links do not work in the announcement, in which case you must use HTML!
Markdown links do not work in the announcement, requiring you to use HTML!
```
## Known Issue

5
book/basic-features/code.md
View file

@ -1,12 +1,12 @@
# 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.*
There are two main ways to include code: directly within a Markdown file or within 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.
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.
We can change how the compiler treats notebook cells by using cell tags. You can find a detailed 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).
@ -18,4 +18,5 @@ For example, the following tag is used to convert the code input into either a d
]
}
```
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.

3
book/basic-features/equations.md
View file

@ -18,6 +18,7 @@ $$
The scientific rules dictate that quantities ($F$, $m$, $a$ etc.) should be printed in italics. Units, however, should not! One can use `\text{m}` in an equation to comply to this rule:
$$ F = m \cdot a = 10 \cdot 9.81 = 98 \text{N}$$
```
> **Warning**
@ -36,6 +37,8 @@ $$
F = m \cdot a
$$ (newtons_second_law)
Equation {eq}`newtons_second_law` can now be referred to.
> **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).

19
book/basic-features/jupyterbook.md
View file

@ -23,20 +23,20 @@ sphinx:
- sphinx_inline_tabs
```
Technically speaking, a `_config.yml` file is not required to build a Jupyter Book. If you don't make one, `jupyter book` will just use all default values. However, you should make a configuration file with at least the following settings:
Technically speaking, a `_config.yml` file is not required to build a Jupyter Book. If you don't make one, `jupyter book` will just use all default values. However, you should make a configuration file which includes at least the following settings:
- `title`: the title of your book, which appears on the top-left of every page, under the logo.
- `author`: authors of the book, which appears in the bottom margin of every page.
- `logo`: (relative) path to the logo of your book (optional).
- `copyright`: the [licences](https://creativecommons.org/share-your-work/cclicenses/) attached to your book.
- `copyright`: the [licenses](https://creativecommons.org/share-your-work/cclicenses/) attached to your book.
In addition, the following option can also be useful:
- `execute_notebooks`: turn on/off the execution of Jupyter Notebooks during the build process. On by default. If you perform heavy computations in your notebook (machine learning, FEM models, et cetera), you might be better off running the notebooks on a more powerful machine as opposed to the CI/CD server. To turn it off, specify the value `'off'`. You can also exclude specific notebooks by creating exclude patterns in the filenames. For more info, see the [Jupyter Book documentation](https://jupyterbook.org/en/stable/content/execute.html#exclude-files-from-execution).
- `execute_notebooks`: *turn on/off* the execution of Jupyter Notebooks during the build process. *On* by default. If you perform heavy computations in your notebook (machine learning, FEM models, et cetera), you might be better off running the notebooks on a more powerful machine as opposed to the CI/CD server. To turn it off, specify the value `'off'`. You can also exclude specific notebooks by creating exclude patterns in the filenames. For more info, see the [Jupyter Book documentation](https://jupyterbook.org/en/stable/content/execute.html#exclude-files-from-execution).
```{warning}
The coniguration and table of contents files are in YAML format (short for YAML Ain't Markup Language). YAML has a specific syntax, which can cause some errors if you don't adhere to it. Just like Python, indentation is very important. You can find an overview of the syntax [here](https://en.wikipedia.org/wiki/YAML#Syntax).
The configuration and table of contents files are in YAML format (short for YAML Ain't Markup Language). YAML has a specific syntax, which can cause some errors if you don't adhere to it. Just like Python, indentation is very important. You can find an overview of the syntax [here](https://en.wikipedia.org/wiki/YAML#Syntax).
```
## The table of contents
@ -85,7 +85,10 @@ parts:
et cetera...
```
## The structure of a chapter
## Content
The main thing people are interested in, is the content of the book. To help the reader, you can structure the book into chapters, each which sections and subsections as explained below.
### The structure of a chapter
The 'nested' structure in the TOC is one way to organize your book. Another way to do so is in the file itself. The structure is defined by the number of `#`:
```
@ -113,7 +116,7 @@ parts:
- file: section_1_2
```
## Including a chapter twice
### Including a chapter twice
In some cases you want to include the same chapter in two different places in your book (for instance parts). However, you do not want to make the same adjustments in different files, the content should only 'live' in one place. The solution is to use `include`:
````
@ -121,7 +124,9 @@ In some cases you want to include the same chapter in two different places in yo
```
````
The *argument* in this case is the location of the file you want to include (for instance: `/basic-features/equations.md`). We provide an example of the use of `include` below: We included the chapter [equations](./equations.md) in this page.
The *argument* in this case is the location of the file you want to include (for instance: `/basic-features/equations.md`). Note that when building the book locally, you get some warnings for duplicate labels..
We provide an example of the use of `include` below: We included the chapter [equations](./equations.md) in this page.
```{include} /basic-features/equations.md

4
book/basic-features/overview.md
View file

@ -2,7 +2,7 @@
```{admonition} User types
:class: tip
This section is useful for user type 3-5.
This section is useful for [user type 3-5](../installation-and-setup/user_types.md).
```
A short description on basic features is given here. These pages will provide a list of some commonly used book features which are all available in the original <a href="https://jupyterbook.org/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book"></a> package. However, this page includes best-practices on how to use them.
These pages will provide a list of some common, basic book features which are all available in the original <a href="https://jupyterbook.org/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book"></a> package. However, this page includes also best-practices.

2
book/external/Nested-Books vendored

@ -1 +1 @@
Subproject commit 4f72481f6a9b65c9b3bd22d0351b58b562f4802c
Subproject commit cc1d35d73558dc5787ede7c4552fb35e9ba82a46

1
book/external/Sphinx-Image-Inverter vendored Submodule

@ -0,0 +1 @@
Subproject commit 61f101bd1fcf9bd8d2990e72b86e38499e0f3f04

2
book/external/TeachBooks vendored

@ -1 +1 @@
Subproject commit c802630d700f579eff2ac990496503bdda57ca3b
Subproject commit f6968d6284d5f75950e502c50c6778d08d0fdf1f

2
book/external/Useful_python_code vendored

@ -1 +1 @@
Subproject commit c8327b3e2cc68d44958974a47c940bc89f4bb32b
Subproject commit 8c7d765f3a06b18517b315455ae7f5dc9230748c

2
book/external/deploy-book-workflow vendored

@ -1 +1 @@
Subproject commit 081491b5f7bd0beecb5663228eaf5ab80b9dd57c
Subproject commit f4e88d59f4e1809547e14fcdfc1ae5c512eec847

2
book/external/latex-to-markdown-conversion vendored

@ -1 +1 @@
Subproject commit 0b9b6512da9ff9011e56897eb6837cc3ed89ee45
Subproject commit f71092bfdb2e3d5d2f580bac5e31ff695806e7d3

2
book/external/template vendored

@ -1 +1 @@
Subproject commit 1ea4faffd395342b79b0bc995526ba254c2c4b63
Subproject commit 080483e6865edff26fd125382bac99b13e4d8539

4
book/intro.md
View file

@ -1,6 +1,6 @@
# TeachBooks Manual
This is an introduction to Git, VS Code and Jupyter Books for teachers and teaching assistants involved in TeachBooks, our platform easing the process of making a <a href="https://jupyterbook.org/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="images/logo-wide.svg" alt="Jupyter book"></a>. This book is still work in progress, so feel free to contribute https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual! For more information about teachbooks, visit [https://teachbooks.tudelft.nl/](https://teachbooks.tudelft.nl/).
This is an introduction to Git, VS Code and Jupyter Books for teachers and teaching assistants involved in TeachBooks, our platform easing the process of making a <a href="https://jupyterbook.org/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="images/logo-wide.svg" alt="Jupyter book"></a>. This book will continue to develop, so feel free to contribute https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual! For more information about teachbooks, visit [https://teachbooks.tudelft.nl/](https://teachbooks.tudelft.nl/).
## Contact
If you encounter any issues and you have a TU Delft account, report it by clicking <svg class="svg-inline--fa fa-gitlab" aria-hidden="true" focusable="false" data-prefix="fab" data-icon="gitlab" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" data-fa-i2svg=""><path fill="currentColor" d="M503.5 204.6L502.8 202.8L433.1 21.02C431.7 17.45 429.2 14.43 425.9 12.38C423.5 10.83 420.8 9.865 417.9 9.57C415 9.275 412.2 9.653 409.5 10.68C406.8 11.7 404.4 13.34 402.4 15.46C400.5 17.58 399.1 20.13 398.3 22.9L351.3 166.9H160.8L113.7 22.9C112.9 20.13 111.5 17.59 109.6 15.47C107.6 13.35 105.2 11.72 102.5 10.7C99.86 9.675 96.98 9.295 94.12 9.587C91.26 9.878 88.51 10.83 86.08 12.38C82.84 14.43 80.33 17.45 78.92 21.02L9.267 202.8L8.543 204.6C-1.484 230.8-2.72 259.6 5.023 286.6C12.77 313.5 29.07 337.3 51.47 354.2L51.74 354.4L52.33 354.8L158.3 434.3L210.9 474L242.9 498.2C246.6 500.1 251.2 502.5 255.9 502.5C260.6 502.5 265.2 500.1 268.9 498.2L300.9 474L353.5 434.3L460.2 354.4L460.5 354.1C482.9 337.2 499.2 313.5 506.1 286.6C514.7 259.6 513.5 230.8 503.5 204.6z"></path></svg> --> {fa}`lightbulb` on the top right corner of this page. Or contribute directly by creating a merge request in the [repository](https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual).
@ -8,6 +8,6 @@ If you encounter any issues and you have a TU Delft account, report it by clicki
If you have questions, contact Tom van Woudenberg, Robert Lanzafame or our TA Julie Kirsch at TeachBooks@tudelft.nl, also for non-TU Delft account holders. TU Delft account holder can also contact us in the [MS Teams Open Interactive Textbooks Community](https://teams.microsoft.com/l/team/19%3Ah9-uRcP_yYauh-VuoPFozJVUvHVOB4a0mz1ZWvh4q4Q1%40thread.tacv2/conversations?groupId=3e88c1f3-4a4f-483a-a366-7e617de9ba99&tenantId=096e524d-6929-4030-8cd3-8ab42de0887b)
## Feedback
We really value your feedback on this manual so we can keep improving it. Please keep using the manual as you build your own Jupyter Book and come back to fill out this short [survey](https://forms.gle/hXbFUQgN95H8ftxt9).
We really value your feedback on this manual. This helps us improving it. Please keep using the manual as you build your own Jupyter Book and come back to fill out this short [survey](https://forms.gle/hXbFUQgN95H8ftxt9).
Happy book building!