From 5c2f2ba82734d485f80f616fdb6e612287aa4f2c Mon Sep 17 00:00:00 2001 From: Freek Pols Date: Wed, 4 Sep 2024 17:26:57 +0200 Subject: [PATCH 01/13] incl $$ to fix bug --- book/basic-features/equations.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/book/basic-features/equations.md b/book/basic-features/equations.md index 89c5a4e..8dd18e4 100644 --- a/book/basic-features/equations.md +++ b/book/basic-features/equations.md @@ -17,7 +17,8 @@ $$ ```{tip} 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} +$$ F = m \cdot a = 10 \cdot 9.81 = 98 \text{N}$$ + ``` > **Warning** From a74332cd1c01e9d320b7e8533ad346843049a107 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 15 Oct 2024 09:36:46 +0200 Subject: [PATCH 02/13] Update latex-to-markdown-conversion --- book/external/latex-to-markdown-conversion | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/latex-to-markdown-conversion b/book/external/latex-to-markdown-conversion index 0b9b651..f71092b 160000 --- a/book/external/latex-to-markdown-conversion +++ b/book/external/latex-to-markdown-conversion @@ -1 +1 @@ -Subproject commit 0b9b6512da9ff9011e56897eb6837cc3ed89ee45 +Subproject commit f71092bfdb2e3d5d2f580bac5e31ff695806e7d3 From f718f9f5fcf9d92f481589be7192124c1dc8ff00 Mon Sep 17 00:00:00 2001 From: Freek Pols Date: Fri, 18 Oct 2024 21:46:42 +0200 Subject: [PATCH 03/13] typos and text fixing --- book/basic-features/References.md | 2 -- book/basic-features/banner.md | 6 +++--- book/basic-features/code.md | 5 +++-- book/basic-features/equations.md | 2 ++ book/basic-features/jupyterbook.md | 19 ++++++++++++------- book/basic-features/overview.md | 4 ++-- book/intro.md | 4 ++-- 7 files changed, 24 insertions(+), 18 deletions(-) diff --git a/book/basic-features/References.md b/book/basic-features/References.md index b5eeaba..1a8c1ee 100644 --- a/book/basic-features/References.md +++ b/book/basic-features/References.md @@ -21,5 +21,3 @@ Or, the derivation results in equation {eq}``. $$ F = m\cdot a $$(eq:Newton) - - diff --git a/book/basic-features/banner.md b/book/basic-features/banner.md index 63db4e0..f92f110 100644 --- a/book/basic-features/banner.md +++ b/book/basic-features/banner.md @@ -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 diff --git a/book/basic-features/code.md b/book/basic-features/code.md index b38f969..0b78694 100644 --- a/book/basic-features/code.md +++ b/book/basic-features/code.md @@ -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. diff --git a/book/basic-features/equations.md b/book/basic-features/equations.md index 8dd18e4..1aa80d1 100644 --- a/book/basic-features/equations.md +++ b/book/basic-features/equations.md @@ -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). diff --git a/book/basic-features/jupyterbook.md b/book/basic-features/jupyterbook.md index ef01edf..cb04343 100644 --- a/book/basic-features/jupyterbook.md +++ b/book/basic-features/jupyterbook.md @@ -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 diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md index 7b9e4d4..ead61cb 100644 --- a/book/basic-features/overview.md +++ b/book/basic-features/overview.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 Jupyter book 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 Jupyter book package. However, this page includes also best-practices. diff --git a/book/intro.md b/book/intro.md index b1ff072..f362f04 100644 --- a/book/intro.md +++ b/book/intro.md @@ -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 Jupyter book. 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 Jupyter book. 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 --> {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! \ No newline at end of file From 0eef663039c9fb14f765ec6d9509dd847c092fc9 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 21 Oct 2024 12:02:29 +0200 Subject: [PATCH 04/13] Update template --- book/external/template | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/template b/book/external/template index 1ea4faf..775c868 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit 1ea4faffd395342b79b0bc995526ba254c2c4b63 +Subproject commit 775c8680d3d2e1b1720cffd13628bf2a57af6f8a From c54f274a25be6eb8247513cb81963e9ce718f8ea Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Tue, 22 Oct 2024 10:22:59 +0200 Subject: [PATCH 05/13] addition of external repo Diana --- .gitmodules | 3 +++ book/_toc.yml | 1 + book/external/Sphinx-Image-Inverter | 1 + 3 files changed, 5 insertions(+) create mode 160000 book/external/Sphinx-Image-Inverter diff --git a/.gitmodules b/.gitmodules index 80ce81d..9f34e0d 100644 --- a/.gitmodules +++ b/.gitmodules @@ -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 diff --git a/book/_toc.yml b/book/_toc.yml index 1c03d88..671dca2 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -59,6 +59,7 @@ parts: sections: - file: features/widgets.ipynb - file: features/exercise_checking.ipynb + - file: external/Sphinx-Image-Inverter/README.md - caption: Examples chapters: diff --git a/book/external/Sphinx-Image-Inverter b/book/external/Sphinx-Image-Inverter new file mode 160000 index 0000000..90af0ab --- /dev/null +++ b/book/external/Sphinx-Image-Inverter @@ -0,0 +1 @@ +Subproject commit 90af0ab633f42e571d3e13aaba1f18160b4a83ac From 99f2e62f1627daeff12b17f94bc6e8c8030d7fe8 Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Tue, 22 Oct 2024 10:39:06 +0200 Subject: [PATCH 06/13] updated remotes --- book/external/Nested-Books | 2 +- book/external/Sphinx-Image-Inverter | 2 +- book/external/TeachBooks | 2 +- book/external/Useful_python_code | 2 +- book/external/deploy-book-workflow | 2 +- book/external/template | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/book/external/Nested-Books b/book/external/Nested-Books index 4f72481..cc1d35d 160000 --- a/book/external/Nested-Books +++ b/book/external/Nested-Books @@ -1 +1 @@ -Subproject commit 4f72481f6a9b65c9b3bd22d0351b58b562f4802c +Subproject commit cc1d35d73558dc5787ede7c4552fb35e9ba82a46 diff --git a/book/external/Sphinx-Image-Inverter b/book/external/Sphinx-Image-Inverter index 90af0ab..61f101b 160000 --- a/book/external/Sphinx-Image-Inverter +++ b/book/external/Sphinx-Image-Inverter @@ -1 +1 @@ -Subproject commit 90af0ab633f42e571d3e13aaba1f18160b4a83ac +Subproject commit 61f101bd1fcf9bd8d2990e72b86e38499e0f3f04 diff --git a/book/external/TeachBooks b/book/external/TeachBooks index c802630..f6968d6 160000 --- a/book/external/TeachBooks +++ b/book/external/TeachBooks @@ -1 +1 @@ -Subproject commit c802630d700f579eff2ac990496503bdda57ca3b +Subproject commit f6968d6284d5f75950e502c50c6778d08d0fdf1f diff --git a/book/external/Useful_python_code b/book/external/Useful_python_code index c8327b3..8c7d765 160000 --- a/book/external/Useful_python_code +++ b/book/external/Useful_python_code @@ -1 +1 @@ -Subproject commit c8327b3e2cc68d44958974a47c940bc89f4bb32b +Subproject commit 8c7d765f3a06b18517b315455ae7f5dc9230748c diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow index 081491b..f4e88d5 160000 --- a/book/external/deploy-book-workflow +++ b/book/external/deploy-book-workflow @@ -1 +1 @@ -Subproject commit 081491b5f7bd0beecb5663228eaf5ab80b9dd57c +Subproject commit f4e88d59f4e1809547e14fcdfc1ae5c512eec847 diff --git a/book/external/template b/book/external/template index 775c868..080483e 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit 775c8680d3d2e1b1720cffd13628bf2a57af6f8a +Subproject commit 080483e6865edff26fd125382bac99b13e4d8539 From 4a8ca486392adf0016a369a76c931cf34a620831 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 22 Oct 2024 12:38:39 +0200 Subject: [PATCH 07/13] Update _toc.yml --- book/_toc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index 671dca2..504fd06 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -48,6 +48,7 @@ parts: - file: features/custom_download.md - file: external/Nested-Books/README.md - file: features/interactive_element.ipynb + - file: external/Sphinx-Image-Inverter/README.md sections: - file: features/grasple.md - file: features/h5p.md @@ -59,7 +60,6 @@ parts: sections: - file: features/widgets.ipynb - file: features/exercise_checking.ipynb - - file: external/Sphinx-Image-Inverter/README.md - caption: Examples chapters: From 9c3f42eecfebacdfefe6af1c233690c7a6799621 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 22 Oct 2024 12:44:35 +0200 Subject: [PATCH 08/13] Update _toc.yml --- book/_toc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index 504fd06..16d456e 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -47,8 +47,8 @@ parts: - file: features/custom_toc.md - file: features/custom_download.md - file: external/Nested-Books/README.md - - file: features/interactive_element.ipynb - file: external/Sphinx-Image-Inverter/README.md + - file: features/interactive_element.ipynb sections: - file: features/grasple.md - file: features/h5p.md From dc4288e286b313baed5f351b2c83e6cb722df072 Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Tue, 22 Oct 2024 14:25:44 +0200 Subject: [PATCH 09/13] submodule --- book/_toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_toc.yml b/book/_toc.yml index 16d456e..92aa83d 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -60,6 +60,7 @@ parts: sections: - file: features/widgets.ipynb - file: features/exercise_checking.ipynb + -file: external/Sphinx-Image-Inverter/README.md - caption: Examples chapters: From 529fa0ba87142b7d816a723083dee03794d3e0f5 Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Tue, 22 Oct 2024 14:33:15 +0200 Subject: [PATCH 10/13] does it work? --- .gitmodules | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitmodules b/.gitmodules index 9f34e0d..463b0a9 100644 --- a/.gitmodules +++ b/.gitmodules @@ -19,3 +19,4 @@ [submodule "book/external/Sphinx-Image-Inverter"] path = book/external/Sphinx-Image-Inverter url = https://github.com/TeachBooks/Sphinx-Image-Inverter.git + branch = Module From 707e61d6262e4094ecdce73a2aa04327be8f9064 Mon Sep 17 00:00:00 2001 From: Julie Kirsch Date: Tue, 22 Oct 2024 15:06:54 +0200 Subject: [PATCH 11/13] fix --- book/_toc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index 92aa83d..9c9bb20 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -60,7 +60,7 @@ parts: sections: - file: features/widgets.ipynb - file: features/exercise_checking.ipynb - -file: external/Sphinx-Image-Inverter/README.md + - file: external/Sphinx-Image-Inverter/README.md - caption: Examples chapters: From f678246caef9c32e4fa7febfc9d58620417ba552 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 22 Oct 2024 16:57:59 +0200 Subject: [PATCH 12/13] Revert "does it work?" This reverts commit 529fa0ba87142b7d816a723083dee03794d3e0f5. --- .gitmodules | 1 - 1 file changed, 1 deletion(-) diff --git a/.gitmodules b/.gitmodules index 463b0a9..9f34e0d 100644 --- a/.gitmodules +++ b/.gitmodules @@ -19,4 +19,3 @@ [submodule "book/external/Sphinx-Image-Inverter"] path = book/external/Sphinx-Image-Inverter url = https://github.com/TeachBooks/Sphinx-Image-Inverter.git - branch = Module From 95d60cc84c3f41dce256c918a990911b16c5bbae Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 22 Oct 2024 16:58:38 +0200 Subject: [PATCH 13/13] revert toc chagne --- book/_toc.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index 9c9bb20..16d456e 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -60,7 +60,6 @@ parts: sections: - file: features/widgets.ipynb - file: features/exercise_checking.ipynb - - file: external/Sphinx-Image-Inverter/README.md - caption: Examples chapters: