mirror of
https://github.com/TeachBooks/manual.git
synced 2026-11-12 22:35:51 +00:00
typos and text fixing
This commit is contained in:
Freek Pols
parent
26f79a14a7
commit
f718f9f5fc
7 changed files with 24 additions and 18 deletions
|
|
@ -21,5 +21,3 @@ Or, the derivation results in equation {eq}`<eq:Newton>`.
|
|||
|
||||
$$ F = m\cdot a $$(eq:Newton)
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -37,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).
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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!
|
||||
Loading…
Add table
Add a link
Reference in a new issue