` elements, both before and after the text (make sure to leave an empty line after the `
`!):
-````
-
- and the output
-
-
+````html
+
+and the output
+
+
- ```{figure} ../images/TUDelft_logo_rgb.png
- ---
- width: 50%
- name: demoexample3
- align: right
- ---
- example 3: width (50%) as percentage, align right with additional div style
- ```
+```{figure} ../images/TUDelft_logo_rgb.png
+---
+width: 50%
+name: demoexample3
+align: right
+---
+example 3: width (50%) as percentage, align right with additional div style
+```
-
+
````
@@ -108,16 +108,16 @@ including `figclass: margin` sets the figure to the column at the right.
-````
- ```{figure} demo97/demo97_figure1.jpg
- ---
- figclass: margin
- width: 50%
- name: demoexample2
-
- ---
- example 2:including figclass: margin
- ```
+````md
+```{figure} demo97/demo97_figure1.jpg
+---
+figclass: margin
+width: 50%
+name: demoexample2
+
+---
+example 2:including figclass: margin
+```
````
diff --git a/book/basic-features/hypothesis.md b/book/basic-features/hypothesis.md
index 0f42e79..49ebe28 100644
--- a/book/basic-features/hypothesis.md
+++ b/book/basic-features/hypothesis.md
@@ -1,11 +1,13 @@
-# Making comments on the website: Hypothesis
-
+````{margin}
```{admonition} User types
:class: tip
This section is useful for user type 1-5.
```
{bdg-warning}`Javascript overlay` {bdg-success}`Chrome Extension`
+````
+
+# Making comments on the website: Hypothesis
Hypothesis is a third-party application that allows anyone to make publicly visible comments on a website (once you create a free account). This section explains how to use and install the extension. As this tool requires an account with a third-party, we advise to use our [local-annotator](../external/annotater/README.md) with similar capabilities but which store annotations locally. By default Hypothesis stores annotations publicly, which might confuse other students.
diff --git a/book/basic-features/jupyterbook.md b/book/basic-features/jupyterbook.md
index 6737a17..a9d7a91 100644
--- a/book/basic-features/jupyterbook.md
+++ b/book/basic-features/jupyterbook.md
@@ -1,18 +1,17 @@
-# Anatomy of a Jupyter Book
+# Anatomy of a TeachBook
-To build a Jupyter Book, you need three things:
+To build a TeachBook, you need three things:
1. A configuration file
2. A table of contents
3. Content
## The configuration file
-The configuration file of Jupyter Books is named `_config.yml`. It mainly contains settings that apply when building the book. Here is a basic example of a configuration file, taken from this book:
+The configuration file of TeachBooks is named `_config.yml`. It mainly contains settings that apply when building the book. Here is a basic example of a configuration file, taken from this book:
```yaml
-title: Jupyter Book Manual
-author: Interactive Textbooks CiTG
-logo: images/TUDelft_logo_rgb.png
+title: TeachBook Manual
+author: TeachBooks development team
copyright: CC BY-NC
execute:
@@ -23,7 +22,7 @@ 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 which includes at least the following settings:
+Technically speaking, a `_config.yml` file is not required to build a TeachBook. If you don't make one, your TeachBook 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.
@@ -32,7 +31,7 @@ Technically speaking, a `_config.yml` file is not required to build a Jupyter Bo
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 v1 documentation](https://jupyterbook.org/v1/content/execute.html#exclude-files-from-execution).
```{warning}
@@ -116,6 +115,9 @@ parts:
- file: section_1_2
```
+#### Exercise
+Check out [this exercise](https://teachbooks.io/template/syntax_exercises/007.html) in the TeachBooks template to see for yourself how to structure files with titles!
+
### 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`:
diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md
index df68f69..74b4e04 100644
--- a/book/basic-features/overview.md
+++ b/book/basic-features/overview.md
@@ -1,8 +1,10 @@
-# Original Jupyter Book and Sphinx Features
-
+````{margin}
```{admonition} User types
:class: tip
This section is useful for [user type 3-5](../installation-and-setup/user_types.md).
```
+````
-These pages will provide a list of some common, basic book features which are all available in the original
package. Additionally, this page includes also best-practices.
+# Overview
+
+These pages itemize some of the more common, basic book features which are all available in the original
package, without requiring any additional software. They are, of course, selected with teachers and teaching applications in mind. On each page best-practices are illustrated.
diff --git a/book/basic-features/utterances.md b/book/basic-features/utterances.md
index f82a44f..cbdc82e 100644
--- a/book/basic-features/utterances.md
+++ b/book/basic-features/utterances.md
@@ -1,11 +1,13 @@
-# Discussions in your book: Utterances
-
+````{margin}
```{admonition} User types
:class: tip
This section is useful for user type 3-5.
```
{bdg-white}`GitHub app and Javascript script`
+````
+
+# Discussions in your book: Utterances
[Utterances 🔮](https://utteranc.es/) is a lightweight open-source widget which allows you, your colleages and your students to discuss stuff in a blog post in your book. It is build on GitHub issues, so requires a GitHub repository, although the book can be hosted anywhere (so also on GitLab).
diff --git a/book/basic-features/videos.md b/book/basic-features/videos.md
index d623ad1..c3b4e32 100644
--- a/book/basic-features/videos.md
+++ b/book/basic-features/videos.md
@@ -13,9 +13,9 @@ kernelspec:
# Videos
-Videos uploaded to YouTube can be embedded in the Jupyter Book. There are several ways to do so:
+Videos uploaded to YouTube can be embedded in the TeachBook. There are several ways to do so:
-**1.** 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
+**1.** To embed them in the TeachBook, 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
```
```
@@ -37,4 +41,4 @@ Some best-practices on the use of H5p:
In the next subpage, these exampled are shown.
-More information on H5p using the TU Delft provided hosting: [Teaching Support - Educational Tools - H5P](https://www.tudelft.nl/teaching-support/educational-tools/h5p)
\ No newline at end of file
+More information on H5p using the TU Delft provided hosting: [Teaching Support - Educational Tools - H5P](https://www.tudelft.nl/teaching-support/educational-tools/h5p)
diff --git a/book/features/jupyterlite/configuration.md b/book/features/jupyterlite/configuration.md
index 2a6f036..5f8b1a4 100644
--- a/book/features/jupyterlite/configuration.md
+++ b/book/features/jupyterlite/configuration.md
@@ -23,9 +23,9 @@ When you have installed `jupyterlite-xeus-python`, the kernel will automatically
}
}
-## Updating the Jupyter Book `_config.yml`
+## Updating the TeachBook's `_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:
+Since `jupyterlite-sphinx` is a Sphinx extension, we need to tell TeachBooks 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:
@@ -37,4 +37,4 @@ Of course, change `jupyterlite-config.json` to the name of your configuration fi
## 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`.
\ No newline at end of file
+When everything is configured correctly, a `Xeus-Python` kernel will be built when you build your book via `teachbooks 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`.
\ No newline at end of file
diff --git a/book/features/jupyterlite/jupyterlite.md b/book/features/jupyterlite/jupyterlite.md
index 87d0945..01a9fed 100644
--- a/book/features/jupyterlite/jupyterlite.md
+++ b/book/features/jupyterlite/jupyterlite.md
@@ -1,6 +1,6 @@
# 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.
+By popular demand: how to include interactive pieces of code in your TeachBook. 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 TeachBook with the [`JupyterLite-Sphinx`](https://github.com/jupyterlite/jupyterlite-sphinx) extension.
## An example
diff --git a/book/features/jupyterquiz.ipynb b/book/features/jupyterquiz.ipynb
index 20f73e3..c4ee03e 100644
--- a/book/features/jupyterquiz.ipynb
+++ b/book/features/jupyterquiz.ipynb
@@ -7,14 +7,16 @@
"hidePrompt": true
},
"source": [
- "# JupyterQuiz\n",
- "\n",
+ "````{margin}\n",
"```{admonition} User types\n",
":class: tip\n",
"This section is useful for user type 4-5.\n",
"```\n",
"\n",
- "- {bdg-secondary}`Python Package: jupyterquiz`\n",
+ "{bdg-secondary}`Python Package: jupyterquiz`\n",
+ "````\n",
+ "\n",
+ "# JupyterQuiz\n",
"\n",
"JupyterQuiz is a code-based implementation of multiple-choiche questions and numerical answer questions. This is a basic open course tool which requires you to write your quiz questions in Python language as a `dict` or to a `.json` file. An example is given below:\n",
"\n",
diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb
index a4703a7..ac78b60 100644
--- a/book/features/live_code.ipynb
+++ b/book/features/live_code.ipynb
@@ -4,16 +4,21 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "# Interactive content: Run Python inside your book\n",
- "\n",
+ "````{margin}\n",
"```{admonition} User types\n",
":class: tip\n",
"This section is useful for user type 5.\n",
"```\n",
"\n",
"{bdg-primary}`Sphinx Extension`\n",
+ "{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>`\n",
+ "{bdg-link-primary-line}`Included in TeachBooks Favourites <./favourites.html>`\n",
"\n",
- "Our book has been enable to run Python code live in the browser (thanks Max!). This extension makes code cells in your `.ipynb` book pages editable and executable by the reader! Opposed to the original sphinx-thebe extensions, our extension runs python in the reader's browser and doesn't rely on an external webserver for the python kernel. We highly recommend this extension as it allows you to use the strength of combining text/figures and code of a jupyter book with interactivity!\n",
+ "```` \n",
+ "\n",
+ "# Interactive content: Run Python inside your book\n",
+ "\n",
+ "Our book has been enable to run Python code live in the browser (thanks Max!). This extension makes code cells in your `.ipynb` book pages editable and executable by the reader! Opposed to the original sphinx-thebe extensions, our extension runs python in the reader's browser and doesn't rely on an external webserver for the python kernel. We highly recommend this extension as it allows you to use the strength of combining text/figures and code of a TeachBook with interactivity!\n",
"\n",
"This page contains some installation instructions and the other sections show how to use this functionality to create interactive figures and feedback on code\n",
"\n",
@@ -90,7 +95,7 @@
"\n",
"By `launch_buttons` you initiate the {fa}`rocket` --> {guilabel}`Live Code` on the top right corner of every page generated from a `.ipynb` file. \n",
"\n",
- "Note, if you're messing around with `html_theme_options` (for example when adding more buttons), all button behaviour is affected. In that case, as opposed to the jupyter book documentation, all buttons have to be specified from within `sphinx: html_theme_options` where you might also specify other buttons as well (ie. the [code repository button](https://jupyterbook.org/en/stable/basics/repository.html)).\n",
+ "Note, if you're messing around with `html_theme_options` (for example when adding more buttons), all button behaviour is affected. In that case, as opposed to the jupyter book v1 documentation, all buttons have to be specified from within `sphinx: html_theme_options` where you might also specify other buttons as well (ie. the [code repository button](https://jupyterbook.org/v1/basics/repository.html)).\n",
"\n",
"```yaml\n",
"sphinx:\n",
@@ -114,7 +119,7 @@
"If you push to main, you can test the interactivity on the book-draft website as well.\n",
"\n",
"## Custom cell tags\n",
- "With the extended functionality of live code, additional cell tags have been developed to be added to python cells (not markdown cells) in any .ipynb file, next to the [existing tags] of the jupyter book (https://jupyterbook.org/en/stable/content/metadata.html):\n",
+ "With the extended functionality of live code, additional cell tags have been developed to be added to python cells (not markdown cells) in any .ipynb file, next to the [existing tags] of the jupyter book v1 (https://jupyterbook.org/en/stable/content/metadata.html):\n",
"- `disable-execution-cell` disables the ability to execute the cell when thebe is activated. This might be useful if you notebook file includes interactivity for only a part of the coding cells\n",
"- `disable-execution-page` disables the ability to execute the entire page. This might be useful if you use python code for creating a page, but the code is not part of the actual content of the book.\n",
"- `auto-execute-page` automatically starts the thebe live coding functionality whenever the page is opened. This is particularly useful if you're using widgets on a page.\n",
@@ -171,6 +176,10 @@
"cell_type": "markdown",
"metadata": {},
"source": [
+ "## Exercises and examples with executable code\n",
+ "\n",
+ "To include executable code in your book inside exercises and/or examples, you can use the Sphinx extension [Sphinx-Exercises](https://ebp-sphinx-exercise.readthedocs.io/en/latest/syntax.html#alternative-gated-syntax) and/or the Sphinx extension {ref}`Sphinx-Code-Examples
`.\n",
+ "\n",
"## Alternative with JupyterLite (less well integrated)\n",
"\n",
"Another option to use python in your browser is to use [JupyterLite](https://jupyterlite.readthedocs.io/en/stable/). However, compared to Sphinx-Thebe, described above, this doesn't give a similar seamless interface within your page. Nevertheless, depending on your application, JupyterLite could be a useful tool, especially as it allows for three IDE types: Jupyter Notebook, Jupyter Lab and the iPython REPL.\n",
@@ -179,7 +188,7 @@
"\n",
"```{tip}\n",
"The TeachBooks Team has focused primarily on the use of Sphinx-Thebe and has not looked at JupyterLite over the last couple years. If you have an interesting application of this tool for teaching, please get in touch, we would love to see it! You can use [GitHub Discussions](https://github.com/orgs/TeachBooks/discussions) or sent us an email at [info@teachbooks.io](mailto:info@teachbooks.io).\n",
- "```"
+ "```\n"
]
}
],
diff --git a/book/features/local_server.md b/book/features/local_server.md
index fcdbbc1..44803d8 100644
--- a/book/features/local_server.md
+++ b/book/features/local_server.md
@@ -1,12 +1,14 @@
-(setup-local-server)=
-# Local Server to view interactive elements locally
-
+````{margin}
```{admonition} User types
:class: tip
This section is useful for user type 4-5.
```
-{bdg-secondary}`Python Package: teachbooks`
+{bdg-link-secondary}`Uses TeachBooks package <./teachbooks_intro.html>`
+````
+
+(setup-local-server)=
+# Local Server to view interactive elements locally
Perhaps you have already noticed that when building a book and testing it locally on your computer, some features do not work the way you expect, or worse---do not work at all! This is because many interactive features rely on browser functionality to work properly, for example: Grasple/H5p iframe exercises, Sphinx-Thebe Python interactivity and HTML/Javascript elements. Although the website is _static_ (i.e., there is no code running on a webserver that generates the content), modern web browsers have their own internal computing environments that run processes to deliver the rich content we desire in our books.
@@ -15,7 +17,7 @@ Technically what is needed to facilitate this during the editing and checking of
```{admonition} Why do you need a local server?
:class: tip
-A Jupyter Book is really just a _static website._ This means that all book content _and interactivity_ is available via the (static) files that are provided to you by a webserver when you visit a specific URL. After this initial request, all required files are available in your web browser, however, some features require the request and response protocol to work properly.
+A TeachBook is really just a _static website._ This means that all book content _and interactivity_ is available via the (static) files that are provided to you by a webserver when you visit a specific URL. After this initial request, all required files are available in your web browser, however, some features require the request and response protocol to work properly.
```
We recommend you use the **TeachBooks Python Package**, which has a `serve` command in the CLI tool to start and stop local servers. Find out more on {ref}`the TeachBooks Package page `.
@@ -138,4 +140,4 @@ A Windows-specific command for the CMD prompt or Powershell is:
```
TASKKILL /IM python.exe /F
-```
\ No newline at end of file
+```
diff --git a/book/features/overview.md b/book/features/overview.md
index 35dd27f..a1a1314 100644
--- a/book/features/overview.md
+++ b/book/features/overview.md
@@ -4,23 +4,27 @@
As TeachBooks, we collect a suite of existing open-source software so you don't have to! Some of the software is developed with our TA's to improve the learning experience of our students and ease the book-development process for our teachers. As the open-source software landscape changes rapidly, it is essential to keep in contact and share resources amongst ourselves to minimize maintenance and downtime for our book websites and focus on what really matters: teaching!
Since the list of TeachBook features is getting quite long, we have grouped them in categories:
-- Original Jupyter Book and Sphinx features
-- Easy editing process
-- Additional functionality
-- Book styling
-- TeachBooks student-view features
+- [Original Jupyter Book v1 and Sphinx features](../basic-features/overview.md)
+- [Easy editing process](./easy-editing.md)
+- [Additional functionality](./sphinx_extensions.md)
+- [Book styling](./visuals.md)
+- [TeachBooks student-view features](./students.md)
Additionally, not all features are built and shared in the same way. We do our best to make sure that as many tools as possible are included automatically when using our TeachBooks Template Book; if you are not using the Template, we try to make sure each of our tools can be used independently. For transparency, tags will help differentiate between the different backgrounds of the features:
- {bdg-warning}`Javascript overlay`
- {bdg-success}`Chrome Extension`
- {bdg-white}`GitHub App and Javascript script`
-- {bdg-secondary}`Python Package: teachbooks`
-- {bdg-light}`GitHub Reusable Action`
-- {bdg-light}`GitHub Template`
+- {bdg-link-secondary}`Python Package: teachbooks <./teachbooks_intro.html>`
+- {bdg-link-light}`GitHub Reusable Action: Deploy Book workflow <../external/deploy-book-workflow/README.html>`
+- {bdg-link-light}`GitHub Template: TeachBooks Template <../external/template/README.html>`
- {bdg-dark}`Git Workflow`
- {bdg-primary}`Sphinx Extension`
+- {bdg-link-primary-line}`TeachBooks Favourites <./favourites.html>`
- {bdg-danger}`iframe`
+- {bdg-success}`WebApp`
-Finally, the purpose, installation process and usage of each features is elaborated on in the respective sub-sections.
+For each feature, the purpose, installation process and usage is elaborated in the respective sub-sections.
-To see examples for these features, go to the [Examples chapter](../examples/overview.md).
\ No newline at end of file
+To see examples of these features, go to the [Examples chapter](../examples/overview.md).
+
+As the [TeachBooks Python Package](./teachbooks_intro.md), the [Deploy Book Workflow](../external/deploy-book-workflow/README.md), [TeachBooks Favourites](./favourites.md) and the [TeachBook template](../external/template/README.md) are important tools that incorporate and deploy more than one feature, an additional explanation is provided here in subpages to this page in more detail, with links to other pages in this manual where individual features are described.
\ No newline at end of file
diff --git a/book/features/plotly.ipynb b/book/features/plotly.ipynb
index ec889da..7f92684 100644
--- a/book/features/plotly.ipynb
+++ b/book/features/plotly.ipynb
@@ -7,22 +7,66 @@
"hidePrompt": true
},
"source": [
- "# Interactive plots: plotly\n",
- "\n",
+ "````{margin}\n",
"```{admonition} User types\n",
":class: tip\n",
"This section is useful for user type 5.\n",
"```\n",
+ "````\n",
"\n",
- "The use of the [plotly](https://plotly.com/python/getting-started/) package is an example which allows you to create HTML/Javascript widgets from python code without any knowledge on HTML/Javascript."
+ "# Interactive plots: plotly\n",
+ "\n",
+ "The use of the [plotly](https://plotly.com/python/getting-started/) package is an example which allows you to create HTML/Javascript widgets from python code without any knowledge on HTML/Javascript. The example below is taken from the FEM-module by Frans van der Meer."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
- "The example below is taken from the FEM-module by Frans van der Meer.\n",
- "When using Plotly graphs, make sure the notebook is executed in Jupyter Lab / Jupyter Notebook for the figures to be shown in the book. Running the code in VS code might break the result in the book, although the output is visible in VS code. Alternatively, add the following lines of code to your notebook to have a valid output in the book as well:\n",
+ "If you want to create the plot during the build of the book, don't use `fig.show()` but use the code below:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import os\n",
+ "from IPython.display import HTML\n",
+ "\n",
+ "def show_plotly(fig):\n",
+ " # Use HTML when building book in CI environment\n",
+ " if os.environ.get(\"CI\") == \"true\":\n",
+ " return HTML(fig.to_html(include_plotlyjs=\"cdn\"))\n",
+ "\n",
+ " # Local execution in Jupyter Notebook / JupyterLab / VS Code\n",
+ " fig.show()\n",
+ "\n",
+ "....\n",
+ "\n",
+ "show_plotly(fig)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Make sure you have in your `_config.yml`:\n",
+ "\n",
+ "```yaml\n",
+ "execute:\n",
+ " execute_notebooks: \"auto\"\n",
+ "```\n",
+ "\n",
+ "Eventually in combination with [](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.md)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Alternatively, you can run the notebook locally before building the book. This is not recommended for the combination with git because you will be committing binary output to the repository. When pre-generating Plotly graphs, make sure the notebook is executed in Jupyter Lab / Jupyter Notebook for the figures to be shown in the book. Running the code in VS code might break the result in the book, although the output is visible in VS code. Add the following lines of code to your notebook to have a valid output in the book as well:\n",
"\n",
"```python\n",
"import plotly.io as pio\n",
diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md
index 1ce4265..4ada459 100644
--- a/book/features/pull_request_build.md
+++ b/book/features/pull_request_build.md
@@ -1,9 +1,11 @@
-# Build pull requests from forks
-
+````{margin}
```{admonition} User types
:class: tip
This section is useful for user type 3-5.
```
+````
+
+# Build pull requests from forks
When writing a TeachBook it is useful to automatically build and view these changes online. This exactly why we designed and build the [deploy-book-workflow](../external/deploy-book-workflow/README.md) tool, which also allows for multiple versions of your book to exist at any time with customizable URL's. However, it doesn't cover all use cases. Luckily, **Read the Docs** is a free tool that can easily be used for this purpose. It also provides a very easy way to view differences between versions on each page!
@@ -11,7 +13,7 @@ Pull Requests are a key tool for allowing anyone with a GitHub account to make a
Read the Docs is not recommended for final versions of your book because of the advertisement in the free version. If you'd like to pay for it, it can replace the functionality of the [deploy-book-workflow](../external/deploy-book-workflow/README.md).
-This tool works using Sphinx, which is the core engine for Jupyter Book; it is carried out using a Jupyter Book command to generate a Sphinx configuration file, for example:
+This tool works using Sphinx, which is the core engine for Jupyter Book v1; it is carried out using a Jupyter Book command to generate a Sphinx configuration file, for example:
```
jupyter-book config sphinx book/
diff --git a/book/features/release_book_online.md b/book/features/release_book_online.md
new file mode 100644
index 0000000..80da122
--- /dev/null
+++ b/book/features/release_book_online.md
@@ -0,0 +1,257 @@
+````{margin}
+
+```{note}
+
+{bdg-link-light}`GitHub Reusable Action: Deploy Book workflow <../external/deploy-book-workflow/README.html>`
+
+{bdg-link-light}`Part of TeachBooks Template <../external/template/README.html>`
+
+{bdg-link-secondary}`Uses TeachBooks package <./teachbooks_intro.html>`
+
+```
+
+```{tip}
+This section is useful for user type 3-5.
+```
+
+```{seealso}
+
+[{octicon}`mark-github` Repository deploy book workflow](https://github.com/TeachBooks/deploy-book-workflow)
+
+[{octicon}`book` Publish version on separate (fixed) URLs](../installation-and-setup/versions_URLs.md)
+
+{octicon}`pencil` Exercises:
+- [Your version of the book](https://teachbooks.io/template/exercises/004.html)
+- [Deploy book workflow](https://teachbooks.io/template/extension_exercises/015.html)
+
+```
+
+````
+
+# Share book online for multiple versions
+
+As you'll start working on your TeachBook, you'll probably want to share it online. And over time you'll create more and more versions of your book, for example for different academic years.
+
+Our Deploy Book Workflow (described in general [here](../external/deploy-book-workflow/README.md)) allows you to do so. It builds your book for all branches in your repository and releases them online via GitHub Pages. In simplified terms, it automatically builds the book website based on updates to your repository, creates multiple instances of your book (defined by each branch) and provides the ability to customize the URL's at which each instance of the book can be accessed. This tool is designed specifically for educational contexts, for example, when you may want to preserve book versions from multiple academic years so that students are able to access it later.
+
+Sharing your book online has many features and customizations:
+- Automatic and manual building and releasing of your book online via GitHub Pages using a Reusable GitHub Actions. See explanation [below](how_to_start).
+- Ability to release both private (GitHub Pro, GitHub Team, GitHub Enterprise Cloud, or GitHub Enterprise Server required) and public (GitHub Free is enough) repositories. GitHub Teams is free for teachers as described in the [GitHub documentation](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers). If you have an organization for your TeachBook on GitHub, link your GitHub team rights to your organization as described on the [GitHub website](https://github.com/team#organizations).
+- Releasing all or a selection of branches, allowing to build a draft version of the TeachBook online which reduces the need for local builds of the book. See explanation [below](gh-workflow-settings).
+- Allowing use of submodules within your book. For private submodules, see the explanation [below](private_submodules)
+- Converting branch-names to well-defined URLs. See explanation [below](gh-workflow-settings).
+- Customizable settings on where the books should be deployed including alias for branch-names and selection of one branch to be deployed on root. The workflow will gives warnings if these settings are ill-defined or conflicting. Although aliases are generally not allowed by GitHub Pages, it seems you can use one alias, but not more. See explanation [below](gh-workflow-settings).
+- Customizable behavior of book URL root directory, either by redirecting the root to one of the branches or by copying or moving one of the branches to root. See explanation [below](gh-workflow-settings).
+- Adds an 'archived'-banner to old branches / branches of previous years. See explanation [below](gh-workflow-settings).
+- Custom 404 "Page Not Found" page with buttons for redirecting to Homepage (e.g., book intro page), "Go Back" or Repository home.
+- Provides a summary describing where the TeachBook is released, errors in the build process per branch and how the release step is configured. See explanation [below](gh-workflow-summary)
+- Caching of already built books so that it can be partially reused when another branch is released or the next build contains critical errors. See explanation [below](gh-caching)
+- Caching of python environment to speed up the workflow. See explanation [below](gh-caching)
+
+(how_to_start)=
+## How to start using this workflow
+
+The Deploy Book Workflow is by default incorporated into any book that has been created using the [TeachBooks Template](https://github.com/TeachBooks/template).
+
+Feel free to use it for your existing TeachBook as well:
+1. Add [`teachbooks`](https://github.com/TeachBooks/TeachBooks) to your `requirements.txt` file in your root folder
+2. Move all the TeachBook files (including `_config.yml` and `_toc.yml`) to a subdirectory `book/`.
+3. Copy the [`call-deploy-book.yml`](https://github.com/TeachBooks/template/blob/main/.github/workflows/call-deploy-book.yml) workflow to the `/.github/workflows` folder in your repository (the file is located in the TeachBooks Template repository becuase that file then refers to the file `deploy-book.yml` located in _this_ repository).
+4. Set source for GitHub pages to GitHub Actions under `Settings` - `Pages` - `Build and deployment` - `Source` - `GitHub Actions` (as long as you don't do this the workflow deploys all branches which build successfully).
+5. Trigger the workflow by making an edit to the TeachBook by editing and committing changes to one of the files in the `book/` subdirectory (available under `Code`) or manually activating the workflow under `Actions` - `All workflows` - `call-deploy-book` - `Run workflow` - `Use workflow from branch: ` - `Run workflow` (this workflow).
+6. Now checkout the progress and summary of the releasing workflow under `Actions` - `All workflows` - `call-deploy-book` -``.
+
+(gh-workflow-settings)=
+## Customize the workflow: TeachBook releasing settings
+You can adapt the behaviour by setting repository variables as explained [here](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository) or using the [VS Code Extension GitHub Actions](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-github-actions). Define the following repository variables:
+- `PRIMARY_BRANCH` which is set to `main` whenever it's not defined in the repository variables.
+ - This sets the branch or alias (when using 'redirect' for `BEHAVIOR_PRIMARY`) which is shown on root.
+ - It is advised to show either your default branch on root, or the branch shared with your primary/active book audience (e.g., your current students).
+- `BEHAVIOR_PRIMARY` which is set to `redirect` whenever it's not defined in the repository variables.
+ - This indicates whether to copy the PRIMARY_BRANCH to root ('copy'), move the PRIMARY_BRANCH to root ('move') or redirect from root to the PRIMARY_BRANCH ('redirect')
+ - Advised to use 'redirect' if you expect to archive a version in the future so that the URL doesn't change for the reader (e.g., to preserve URL containing the current academic year shared with students).
+ - Use copy or move when you only expect readers to use the root URL. Move is useful to remove unnecessary build artifacts and if you don't need to visit the URL containing the branch or alias name.
+- `BRANCH_ALIASES` which is set to ` ` (just a space) whenever it's not defined in the repository variables.
+ - This defines an alias (custom URL) for a branch
+ - Variables should be a space-separated list of branch names, e.g. 'alias:really-long-branch-name`
+ - If no alias is wanted, `BRANCH_ALIASES` may be set to ` ` (just a space)
+- `BRANCHES_TO_DEPLOY` which is set to `*` (all branches) whenever it's not defined in the repository variables.
+ - This defines the branches to deploy.
+ - It should be a space-separated list of branch names, e.g. 'main second third'.
+- `BRANCHES_TO_PREPROCESS` which is set to ` ` (just a space = no branch) whenever it's not defined in the repository variables
+ - This defines the branches to preprocess with the [`TeachBooks` package](./draft-release.md), which removed book-pages and config lines defined with `# START REMOVE-FROM-RELEASE` and `# END REMOVE-FROM-RELEASE`
+ - It should be a space-separated list of branch names, e.g. 'main second third'.
+ - If no preprocessing is required, `BRANCH_TO_PREPROCESS` may be set to ' ' (space).
+- `BRANCHES_ARCHIVED` which is set to ` ` (space, no branch) whenever it's not defined in the repository variables
+ - This adds a banner to the released branch: You are viewing an archived version of the book. Click here for the latest version.
+ - It should be a space-separate list of branch names, e.g. 'main second third'.
+
+In `call-deploy-book.yml` itself you can specify the trigger for this workflow. By default, a push to any branch triggers the workflow. You can limit the branches or subdirectories.
+
+## Additional GitHub settings
+We advise you to enable two options in the general repository setting regarding pull requests in GitHub:
+- Enable `Always suggest updating pull request branches`, suggesting a merge from the default branch into any separate branch before merging into main.
+- Enable `Automatically delete head branches` to delete branches after they are merged (you'll still be able to restore those).
+
+## Common Usage Examples
+
+Relevant use cases are explained here, along with an explanation for how to set up the workflow accordingly. Note that it is not required to set your `PRIMARY_BRANCH` to the default branch of your GitHub repository; this is a choice that is determined by what version of the source code you want visitors to see (i.e., work in progress, or the most recent "complete" or "released" version of a book).
+
+### Books with active users of different versions (academic years)
+
+Consider a case where each academic year you would like to create a new book for your students. However, you need to ensure that students from previous years can still access "their" version of the book.
+
+Assume for this example that we are working in the "my_organization" GitHub Organization in repository "my_book" and that the current academic year is 2025, and that we have one or more books in our repository from previous years. The desired URL structure is thus:
+- students from this year use the book at `my_organization.github.io/my_book/2025/`
+- students from last year use the book at `my_organization.github.io/my_book/2024/`
+- visitors to `my_organization.github.io/my_book/` will automatically be redirected to the book from the current year
+
+To create this behavior, do the following:
+
+- Create a branch for each year: a logical name would have format `YYYY`, (technically it can be anything, as the URL can be set to `YYYY` with `BRANCH_ALIASES`).
+- Set `PRIMARY_BRANCH` to the branch for the current academic year (e.g., `2025`)
+- Set `BEHAVIOR_PRIMARY` to `redirect` (default)
+
+#### Alternative without redirect to current year
+
+One possible modification to this setup would be if you are progressively releasing content to your current students (e.g., `2025`) but you wanted visitors to `my_organization.github.io/my_book/` to see a complete version of your book. Assuming that the ideal version for such visitors is the completed book from the previous year (`2024`), you could do this:
+- Set `PRIMARY_BRANCH` to `2024`
+- Set `BEHAVIOR_PRIMARY` to `copy`
+
+As your current students may then accidentally go to the older version of the book, we recommend you use a banner to indicate to readers that there is a (partial) new version available, and advise them where to find it. You can add a banner using this workflow (`BRANCHES_ARCHIVED`) or the [standard Jupyter Book v1 banner feature](https://jupyterbook.org/v1/web/announcements.html).
+
+### Books with active editors working in parallel
+
+Consider a case where several authors are working on material for a book and you would like to be able to see the work of any author at any time. You also have a branch that is used to share finalized material with your readers (we call this a "release" branch) and a branch that is used to collect and review the work of all authors before releasing it (we call this a "draft" branch).
+
+Assume for this example that we are working in the "my_organization" GitHub Organization in repository "my_book." The released book is on branch `release` the draft book is on branch `draft`; author branches are `author_1`, `author_2`, etc. The desired URL structure is thus:
+- official (released) version of the book is at `my_organization.github.io/my_book/`
+- draft version of the book is at `my_organization.github.io/my_book/draft/`
+- the work of each author can be found at `my_organization.github.io/my_book/author_1/`, etc.
+
+To create this behavior, do the following:
+
+- Create a branch for each author as well as `release` and `draft` branches
+- Set `draft` to the default branch
+- Set `PRIMARY_BRANCH` to `release`
+- Set `BEHAVIOR_PRIMARY` to `copy`
+
+Note that in this situation we strongly recommend using the Draft-Release workflow that is incorporated in the TeachBooks Python package, which allows you to restrict specific content from appearing in the `release` book that is already incorporated in the `draft` book. [Find out more here](./draft-release.md). This is useful, for example, if you would like to review many chapters, but release only one at a time, or use a banner in the draft book (e.g., via `_config.yml`) but not the released book.
+
+#### Why make the draft branch default?
+
+What if you want to make sure the source code for the released book is visible in the repository, rather than the draft version (e.g., you want to make sure external visitors see this version of the material)? You can do this by making `release` your default branch instead of `draft`. However, this also means that Pull Requests will be default be made into the `release` branch instead of `draft`, which may alter the working method of your team in an undesirable way (e.g., not being able to use a `draft` branch, accidentally releasing material before checking on `draft`, or having to manually adjust every PR that is created by GitHub to merge into `draft` instead of `release`).
+
+(private_submodules)=
+## Private submodules
+In case your book includes private submodules, you'll need to create a Personal Access Token (classic) with at least the scope `repo` as described in the [github documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), and add this token with the name `GH_PAT` as a `Repository secret` or `Organization secret` ( `Settings` > `Secrets and variables` > `Actions` > `Repository secrets` or `Organization secrets`.) Furthermore, manually copy the workflow (.github/workflows/deploy-book.yml) in your own repository as the authorization doesn't work with the called workflow.
+
+(gh-workflow-summary)=
+## View the workflow progress and summary
+
+Whenever the workflow is triggered, its progress and a summary can be seen under the `Actions`- `All workflows` - `call-deploy-book` in GitHub! It shows you a descriptive summary:
+- Ill-defined repository configuration variables (in `Annotations`)
+- Which branches are released and where (`https://.github.io/` (case sensitive)) including which branch is released on the website root and the applied alias
+- Errors in the build process
+- How the repository variables are defined during the build.
+
+Here's an example for a summary for the template book:
+
+> ### Branches deployed
+> | Branch 🎋 | Link 🔗 | Build status ☑️ |
+> | :--- | :--- | :--- |
+> | main | [https://teachbooks.github.io/template/main](https://teachbooks.github.io/template/main) | ✅ `Released` |
+> | version2 | [https://teachbooks.github.io/template/version2](https://teachbooks.github.io/template/version2) | 🔴 `Build failed [1]` |
+> | version3 | [https://teachbooks.github.io/template/version3](https://teachbooks.github.io/template/version3) | ⭕ `Build failed [2]` |
+>
+> #### Legend for build status
+> ✅ `Released` - build success, new version released.
+>
+> 🔴 `Build failed [1]` - build failure, previous version of the book reused.
+>
+> ⭕ `Build failed [2]` - build failure, no previous version reused.
+>
+> #### Primary book at root
+> The book at the website root
+>
+> ```
+> PRIMARY_BRANCH=main (default value used)
+> BRANCH_ALIASES=draft:main
+> BRANCHES_TO_DEPLOY=* (default value used)
+> BRANCHES_TO_PREPROCESS=main
+> BEHAVIOR_PRIMARY=redirect (default value used)
+> BRANCHES_ARCHIVED= (default value used)
+> ```
+
+(gh-caching)=
+## Caching
+
+The GitHub Action [Cache](https://github.com/actions/cache) is used in the Deploy Book Workflow (DBW) to save time when building the book. This is accompliched by caching two sets of files for each branch: 1) the Python virtual environment, and 2) the build artifact (the HTML files forming each book website).
+
+The reason for doing this stems from the primary purpose of the Deploy Book Workflow, which builds many versions of a book based on each branch, as well as creating a Python virtual environment from the `requirements.txt` file in the repository. A unique environment for each branch is necessary to test changes to book dependencies and configuration in an isolated way, but can dramatically increase the time required to build all versions of the book when the DBW runs. In addition, it also takes time to build the book itself. For this reason, both of these sets of files are cached (although at the moment, most of the time savings is primarily caching the build artifact).
+
+This works by hashing a specific set of files and including that in the filename of the cache. Every time the workflow is triggered, a new hashed filename is created and compared to the list of existing caches to see if one with the same name exists; if so, the cache is reused. If not, a new environment and/or build artifact is constructed and a new cache is made.
+
+Cached files can be found in GitHub under the Actions tab, then looking for the "Caches" section under the "Management" pane on the left hand side of the screen. For example, this link shows the [caches for this TeachBooks Manual](https://github.com/TeachBooks/manual/actions/caches). If needed, caches can be deleted manually from this page. A cache will expire if unused for longer than 1 week or if the maximum allowed disk space for all cached files is exceeded (both are GitHub policies).
+
+Files created during a GitHub Action are called [artifacts](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow). Although this is _not_ the same thing as a cache, the files in a specific cache or artifact are identical. Artifacts have their own expiration period, which is possible to [customize in the repository settings](https://docs.github.com/en/organizations/managing-organization-settings/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-organization) (default is 90 days). Unexpired artifacts can be viewed at the bottom of any workflow run summary that is available on the Actions tab of a GitHub repository.
+
+To add even more confusion to the situation, if an artifact built during an Action is a set of HTML files (a website) that are used to create a GitHub Pages website, the files served when visiting the URL for that are stored on a webserver; they are _not_ the artifact files, but are identical. Fortunately webserver files are preserved indefinitely (or until GitHub changes this policy), meaning that even though your cache or artifact may be deleted, the website will still remain active.
+
+The cache is a key component of the DBW and leads to several considerations for the building and maintenance of a book, which are explained below, after the criteria for each cache type are described.
+
+### Cached Environment
+
+The DBW uses [Python virtual environments](https://docs.python.org/3/library/venv.html) (`python -m venv .venv`) and `python -m pip install -r requirements.txt` to install packages and create the book building environment. The entire `.venv` directory is preserved in the cache with a file name beginning with `venv-...`. The week number is also included in the file hash, which ensures that a new hash is created at least once per week.
+
+Once created during a successful build action, an existing cached environment will be found and reused unless two specific criteria are met: 1) a book build is required (replacing the cached build artifact), _and_ 2) the `requirements.txt` file is changed. Requirements for a "book build" are described in the next section.
+
+Note that any change to the `requirements.txt` file will trigger creation of a new environment, not necessarily one that specifies the version number of a package.
+
+Note that Specifying package version numbers explicitly and updating them via [Dependabot](./update_env.md) is an excellent way to ensure that environments in the DBW are always up to date and this issue is avoided.
+
+If you are _not_ using Dependabot and are not able to get your packages updated when the DBW is running, delete the cache manually and rerun your GitHub Actions job (go to Actions tab, then looking for the "Caches" section under the "Management" pane on the left hand side of the screen).
+
+### Cached Build Artifacts
+
+Build artifacts are the HTML files that define the website (i.e., the book) and are typically located in the subdirectory `book/_build/html` of a repository once the book is built. Note that these files are typically only visible if you are building the book locally, as they are not committed to the repository by default (i.e., `.gitignore`). For users only using the DBW and the GitHub browswer editor, downloading the build cache is the easiest way to view these files, which have filenames beginnig with `html-build--...`.
+
+Once created during a successful build action, an existing cached build artifact will be found and reused unless _any_ of three specific criteria are met: 1) a change is made to a file in `book/`, 2) the `requirements.txt` file is changed, or 3) the status of a branch as archive or preprocess has changed (`BRANCHES_TO_PREPROCESS` of `BRANCHES_ARCHIVED`).
+
+Immediately after a successful build action, the book website files exist in three places: cache, artifact and on a GitHub webserver. However, as described at the beginning of this section, the cache will be automatically deleted after 1 week, if unused, and the artifact will be deleted based on the setting in your repository (90 days by default).
+
+### Effect of Caching on Book Workflow
+
+Implementation of the DBW has several characteristics that should be noted which could help understand certain behaviors of the book build and website deployment process. These points may be useful to consider if you are experiencing undesired behavior in your Actions builds and/or your actual book websites.
+
+- Remember that the DBW action will only run if a commit is made that changes `requirements.txt` or contents of `book/`
+- When first creating a repository, the action may not run, or may run and fail; occasionally it is needed to make a new commit to get the workflow to run for the first time (remember to modify something in `book/`) or you may try to re-run the job from the Actions tab
+- when using multiple branches, only the branch that is edited will be updated
+- the website for each branch may be built with a different Python environments (different package versions)
+
+Unlike the virtual environments (next subsection), caches of the book build do not influence subsequent builds of the book, as this artifact is replaced whenever a commit to a specific branch triggers a new build process. As described above, old cached build artifacts are used if the build process from a new commit fails, ensuring that the URL of a website does not return a 404 page.
+
+### Effect of Caching on Virtual Environment
+
+In particular, note that older branches may have been built with cached environments that are different than those in a newer branch, leading to (undesired) differences in book appearance or functionality---often without the author being aware! This occurs if a package in `requirements.txt` is updated in the time between the creation of environments on different branches, as `pip` will use the newest version when downloading a package (the first time a venv cache is created in the DBW), but it will not always automatically update a package if `pip install -r requirements.txt` is used on an existing environment (this happens every time an existing cache is used!). This means that, when compared to the venv on a newer branch, a frequently used branch (where the cache has not expired) may retain old and out of date packages long after an updated version is available; however, since the week number is included in the venv file hash, this will last for a maximum of 1 week. A best practice to avoid this situation is to pin version numbers explicitly (e.g., `teachbooks==0.2.0`) if you want book builds to remain consistent. In addition, a feature like dependabot can be used to automatically notify you when an update is made; this is [here](./update_env.md).
diff --git a/book/features/sphinx-proof.md b/book/features/sphinx-proof.md
new file mode 100644
index 0000000..7627adb
--- /dev/null
+++ b/book/features/sphinx-proof.md
@@ -0,0 +1,80 @@
+````{margin}
+```{attributiongrey} Attribution
+:class: attribution
+This page reuses MIT licensed content from {cite:t}`sphinx-proof`. {fa}`quote-left`{ref}`Find out more here.`
+```
+
+```{admonition} User types
+:class: tip
+This section is useful for user type 3-5.
+```
++++
+{bdg-primary}`Sphinx Extension`
+{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>`
+{bdg-link-primary-line}`Included in TeachBooks Favourites <./favourites.html>`
+````
+
+# Sphinx proof
+
+This extensions provides an easy way to add proofs, theorem, axioms and much more to your book. It is created by the Executable Books team and is [documented here](https://sphinx-proof.readthedocs.io/en/latest/).
+
+TeachBooks has made some small modifications to the original extension, such that it works well with translated books; this modified version is located in the repository [github.com/TeachBooks/sphinx-proof](https://github.com/TeachBooks/sphinx-proof).
+
+## What does it do?
+
+This extension defines proofs, theorems, axioms and other similar concepts as new admonition types:
+
+````{prf:example}
+:label: my-example
+
+Next, we shut down randomness in demand and assume that the demand shock
+$\nu_t$ follows a deterministic path:
+
+
+```{math}
+\nu_t = \alpha + \rho \nu_{t-1}
+```
+
+Again, we’ll compute and display outcomes in some figures
+
+```python
+ex2 = SmoothingExample(C2=[[0], [0]])
+
+x0 = [0, 1, 0]
+ex2.simulate(x0)
+```
+````
+
+More information can be found in the [official documentation](https://sphinx-proof.readthedocs.io/en/latest/index.html). It can be [configured in combination the TeachBooks extension to include examples with executable code and visuals](../_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.ipynb).
+
+## Installation
+To use this extenstion, follow these steps:
+
+**Step 1: Install the Package**
+
+Install the TeachBooks' version of `sphinx-exercise` package using `pip`:
+```
+pip install sphinx-proof @ git+https://github.com/TeachBooks/sphinx-proof.git
+```
+
+**Step 2: Add to `requirements.txt`**
+
+Make sure that the package is included in your project's `requirements.txt` to track the dependency:
+```
+sphinx-proof @ git+https://github.com/TeachBooks/sphinx-proof.git
+```
+
+**Step 3: Enable in `_config.yml`**
+
+In your `_config.yml` file, add the extension to the list of Sphinx extra extensions (**important**: underscore, not dash this time):
+```
+sphinx:
+ extra_extensions:
+ .
+ .
+ .
+ - sphinx_proof
+ .
+ .
+ .
+```
diff --git a/book/features/sphinx_extensions.md b/book/features/sphinx_extensions.md
index fa53945..ffd76ce 100644
--- a/book/features/sphinx_extensions.md
+++ b/book/features/sphinx_extensions.md
@@ -1,8 +1,10 @@
-# Additional functionality
-
+````{margin}
```{admonition} User types
:class: tip
This section is useful for user type 4-5.
```
+````
-This sections includes the features developed by TeachBooks which add functionality to the book. Most of them are implemented as sphinx extensions, which are plugins developed for the Sphinx documentation ecosystem (which Jupyter Book is built upon). They extend or modify Sphinx’s capabilities. Since Sphinx extensions are not an integral part of jupyter-book, as opposed to original jupyter-book features, they must be installed and configured explicitly, for example in the `_config.yml` file.
\ No newline at end of file
+# Additional functionality
+
+This sections includes the features developed by TeachBooks which add functionality to the book. Most of them are implemented as sphinx extensions {bdg-primary}`Sphinx Extension`, which are plugins developed for the Sphinx documentation ecosystem (which Jupyter Book v1 and TeachBooks is built upon). They extend or modify Sphinx’s capabilities. Since Sphinx extensions are not an integral part of Jupyter Book and TeachBooks, as opposed to original jupyter-book v1 features, they must be installed and configured explicitly, for example in the `_config.yml` and `requirements.txt` files.
\ No newline at end of file
diff --git a/book/features/students.md b/book/features/students.md
index 46a6993..0ce5bca 100644
--- a/book/features/students.md
+++ b/book/features/students.md
@@ -1,8 +1,11 @@
-# TeachBooks Student-view Features
-
+````{margin}
```{admonition} User types
:class: tip
This section is useful for user type 1-5.
```
+````
+
+# TeachBooks Student-view Features
+
This chapter includes some TeachBooks features which aim to improve the way students can use TeachBooks. These tools are fully student-side, they don't influence the book website and the author doesn't have to setup anything. Nevertheless, the author could point the students to the availability of these tools and use it as part of the didactical approach. These tools could also be useful for other users.
diff --git a/book/features/teachbooks_intro.md b/book/features/teachbooks_intro.md
new file mode 100644
index 0000000..0f55afc
--- /dev/null
+++ b/book/features/teachbooks_intro.md
@@ -0,0 +1,50 @@
+
+````{margin}
+
+```{note}
+
+{bdg-link-secondary}`Python Package: TeachBooks`
+
+{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>`
+
+```
+
+```{tip}
+This section is useful for user type 4-5.
+
+```
+
+```{seealso}
+
+[{octicon}`mark-github` Repository](https://github.com/teachbooks/teachbooks)
+
+[{octicon}`book` Documentation](https://teachbooks.readthedocs.io/)
+
+```
+
+````
+
+(teachbooks_package)=
+# TeachBooks Python Package
+
+The TeachBooks Python package is a collection of tools that are used to enhance the Jupyter Book v1 software package by adding features and making customization easier. In general, it is only of interest to user types 4 and 5 when building a book locally. However, it may be important for other users to know what the package does, as it is incorporated in the [Deploy Book Workflow](../external/deploy-book-workflow/README.md) and, therefore, any book created from the [TeachBooks Template](../external/template/README.md). This raises two important points:
+
+1. If you are a book user using the [TeachBooks Template](../external/template/README.md) and/or the [Deploy Book Workflow](../external/deploy-book-workflow/README.md), your book is by default built with the `teachbooks` package, and the way your book is built and features that are included in the book may change automatically when it is updated (these will be non-breaking changes; if not, we will notify our mailing list).
+2. If you are using the `jupyter-book` v1 package to build your book, some of the features described in this Manual may not be available to you (i.e., those listed on this page). This will be the case if you are using a [setup described in the Jupyter Book v1 Manual](https://jupyterbook.org/v1/publish/web.html), for example, [this GitHub workflow](https://jupyterbook.org/v1/publish/gh-pages.html).
+
+For those who wish to use the package, it is available on [PyPI](https://pypi.org/project/teachbooks/) and can be installed using `pip install teachbooks`. As `teachbooks` is a wrapper, the package is meant to replace the usage of `jupyter-book` commands (although it does indeed add a few new commands to the CLI, e.g., `serve`). It is conventionally used in an identical way, as follows:
+
+```
+teachbooks build book
+```
+
+This Manual describes the main features and usage of the package. For those who wish to understand more of hte technical details, note that the implementation the API is is documented at [teachbooks.readthedocs.io/](https://teachbooks.readthedocs.io/).
+
+## List of Features
+
+Items in the list here are currently implemented in the TeachBooks package and described on other pages of this manual:
+- [Draft-Release Workflow](./draft-release.md)
+- [External Contents](./external_toc.md)
+- [Local Server](./local_server.md)
+
+The package is also set up to handle [APA references](./apa) when using the Draft-Release Workflow (the `_ext` subdirectory and its contents are manually copied during the pre-build phase). This will not be necessary once the APA Reference feature is turned into a proper Sphinx extension or Pybtext plugin.
\ No newline at end of file
diff --git a/book/features/update_env.md b/book/features/update_env.md
index 442512a..ef06d12 100644
--- a/book/features/update_env.md
+++ b/book/features/update_env.md
@@ -1,24 +1,29 @@
-# Auto-updating packages
-
+````{margin}
```{admonition} User types
:class: tip
This page is useful for user type 4-5.
```
{bdg-dark}`Git Workflow`
+````
-When building your book, your making use of packages: the teachbooks and jupyterbook packages themselves, but also packages for extensions. These are regularly updated, while those updates are not necessarily taken into your book. This is all defined in the `requirements.txt` file, which is provided as part of the [template](../external/template/README.md). There are three options:
-1. `requirements.txt` only contains names of packages like: `download_link_replacer`. In that case, your [deploy-book-workflow](../external/deploy-book-workflow/README.md) will take the most up-to-date version when making your book website once a week (as the chache will be cleared once a week). This might lead to unexpected changes when new version come out, although new version are in general backwards compatible.
+# Auto-updating packages
+
+When building your book, you are making use of various Python packages: the `teachbooks` and `jupyter-book` v1 packages themselves, but also packages for extensions. These are regularly updated, however, those updates are not necessarily incorporated into your book automatically. The list of packages and their versions are defined in the `requirements.txt` file, which is provided as part of the [template](../external/template/README.md). Consider the following three options for how packages can be specified:
+1. `requirements.txt` only contains names of packages like: `download_link_replacer`. In that case, your [deploy-book-workflow](../external/deploy-book-workflow/README.md) will take the most up-to-date version when making your book website once a week (as the chache will be cleared once a week). This might lead to unexpected changes when a new version has been released (although new versions will generally be backwards compatible).
1. `requirements.txt` contains names of packages with a specified version like: `download_link_replacer==1.0.4`. In that case, your [deploy-book-workflow](../external/deploy-book-workflow/README.md) always uses that specific version. In doing so, you'll never get a new update unless you explicitly adapt the version in `requirements.txt`. If you'd like to get notified for updates, you might consider using GitHub's Dependabot.
-1. A combination of 1. and 2.: In that case (once a week at most) you will receive new versions for only the unfixed packages, no updates for the fixed versions. In this case you can also use GitHub's Dependabot.
+1. A combination of 1. and 2.: In that case (once a week at most) you will receive new versions for only the unfixed packages, no updates for the fixed versions.
+
+For the case of specified versions, you can use GitHub's Dependabot to notify you that a new version is available _and_ to automatically set up a Pull Request to update your book with the new version.
## Notifications updated packages with Dependabot
-Dependabot checks the specified version of packages in your `requirements.txt` file and opens a branch and pull requests whenever there's an update available for that package. Note that package without a fixed version are ignored by Dependabot.
+Dependabot checks the specified version of packages in your `requirements.txt` file and, if a new version is found, will create a new branch, update the `requirements.txt` file and open a Pull Request whenever there's an update available for that package. Note that packages without a fixed version are ignored by Dependabot.
To activate this feature:
1. Specify version for all packages you want to be notified on in your `requirements.txt` file. See [`requirements.txt`](https://github.com/TeachBooks/manual/blob/release/requirements.txt) of this manual as an example
1. In the `.github/` directory, add a file named `dependabot.yml` with the following content (note that sphinx-thebe (used in [python live coding](./live_code.ipynb)) and docutils (using in [APA referencing](./apa.md)) are ignored because these require a very specific version to work):
+
```yaml
version: 2
updates:
@@ -33,11 +38,12 @@ updates:
- dependency-name: "docutils"
```
-This will check every sunday around midnight (UTC) whether any of the fixed-version packages are updated. If so, several things will happen:
-1. A new branch starting with _dependabot_ will be created in the repository and any relevant workflows will be triggered.
-1. A _pull request_ will be created to pull the new branch into the _default_ branch. This pull request must be manually reviewed and merged. Afterwards the _dependabot_ branch can be deleted (automatically).
+This check will run every Sunday around midnight (UTC) whether any of the fixed-version packages are updated. If so, several things will happen:
+1. A new branch is created with a name that begins with `dependabot...` in the repository
+1. A commit is made updating `requirements.txt` (e.g., `jupyterbook_patches==1.4.2` is changed to `jupyterbook_patches==1.4.4`)
+1. A _pull request_ will be created to merge the new branch into the _default_ branch. This pull request must be manually reviewed and merged. Afterwards the _dependabot_ branch can be deleted (automatically).
-If the workflow `call-deploy-book` is used, and you don't want the _dependabot_ branches to be built and deployed (and all other branches you do want), you can achieve this by adding the next to the file `call-deploy-book.yml`:
+Note that these activities will occur automatically and may trigger other workflows in your repository (for example, the building of a book on another branch). If the workflow `call-deploy-book` is used, and you don't want the _dependabot_ branches to be built and deployed (and all other branches you do want), you can achieve this by adding the following text to the file `call-deploy-book.yml`:
```yaml
on:
diff --git a/book/features/versioning.md b/book/features/versioning.md
index c769c82..ed2a626 100644
--- a/book/features/versioning.md
+++ b/book/features/versioning.md
@@ -1,6 +1,10 @@
-# TeachBooks Versioning
+````{margin}
+```{attributiongrey} Attribution
+:class: attribution
+This page reuses adapted CC BY 3.0 content from {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.````
+````
-> This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.`
+# TeachBooks Versioning
Inspired by versioning systems in software management (i.e. semantic and CalVer versioning) TeachBooks suggests a versioning guideline in which the version number tells the reader about the impact of the change. This might more suitable for your online books than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. We recommend TeachBooks versioning, which comes in two flavors:
@@ -16,10 +20,11 @@ We have come up with guidelines how to use the two TeachBooks-versioning options
3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next errata or additions version.
4. Additions version MUST be incremented if an addition is made to the book. It MUST be communicated in both the source code and in the book itself. It MAY include errata level changes. The errata version MUST be reset to 0 when the addition version is incremented.
5. Academic year version MUST be incremented if a fresh book is started for which additions will follow later. It MUST be communicated in both the source code and in the book itself. Additions and errata versions MUST be reset to 0 when academic version is incremented.
-6. Precedence refers to how versions are compared to each other when ordered.
+6. A pre-release version MAY be denoted by appending `.pre-release`. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is not complete.
+7. Precedence refers to how versions are compared to each other when ordered.
1. Precedence MUST be calculated by separating the version into academic year, additions and errata identifiers in that order.
2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Academic year, additions and errata versions are always compared numerically. Example: 2024.0.0 < 2025.0.0 < 2025.1.0 < 2025.1.1.
-7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself.
+8. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself.
An example can be seen in [the source repository of the Engineering Systems Optimization book](https://github.com/TUDelft-books/CME4501/tags) showing tags for different versions.
````
@@ -35,4 +40,4 @@ An example can be seen in [the source repository of the Engineering Systems Opti
````
`````
-Read [](../installation-and-setup/versioning_changelog.md) on how to combine this with a changelog, tags and releases!
\ No newline at end of file
+Read [](../installation-and-setup/versioning_changelog.md) on how to combine this with a changelog, tags and releases!
diff --git a/book/features/visuals.md b/book/features/visuals.md
index 3ae37b8..249de89 100644
--- a/book/features/visuals.md
+++ b/book/features/visuals.md
@@ -1,8 +1,10 @@
-# Book styling
-
+````{margin}
```{admonition} User types
:class: tip
This section is useful for user type 1-5.
```
+````
+
+# Book styling
TeachBooks developed a few improvements of the book which improve the visual book styling.
\ No newline at end of file
diff --git a/book/features/widgets.ipynb b/book/features/widgets.ipynb
index 63a0846..f6b874e 100644
--- a/book/features/widgets.ipynb
+++ b/book/features/widgets.ipynb
@@ -6,7 +6,7 @@
"source": [
"# Ipywidgets\n",
"\n",
- "If you publish widgets in a jupyter book they might (depending on your implementation) require an active python kernel for the output to be interactive. Using the [thebe-integration](../examples/live_code.md), this is possible. Note: You can circumvent the use of a kernel by using packages which don't need such a kernel, for example the [non-kernel-based widgets using Plotly](./plotly.ipynb).\n",
+ "If you publish widgets in a TeachBook they might (depending on your implementation) require an active python kernel for the output to be interactive. Using the [thebe-integration](../examples/live_code.md), this is possible. Note: You can circumvent the use of a kernel by using packages which don't need such a kernel, for example the [non-kernel-based widgets using Plotly](./plotly.ipynb).\n",
"\n",
"## `matplotlib` widgets\n",
"When you'd like to use `ipywidgets` in combinations with a `matplotlib` figure, import the following packages:\n",
@@ -221,7 +221,7 @@
"metadata": {
"celltoolbar": "Tags",
"kernelspec": {
- "display_name": "Python 3 (ipykernel)",
+ "display_name": "base",
"language": "python",
"name": "python3"
},
@@ -235,7 +235,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
- "version": "3.11.5"
+ "version": "3.12.11"
}
},
"nbformat": 4,
diff --git a/book/features/write_online.md b/book/features/write_online.md
new file mode 100644
index 0000000..40fa9be
--- /dev/null
+++ b/book/features/write_online.md
@@ -0,0 +1,82 @@
+````{margin}
+
+```{note}
+
+{bdg-link-light}`Uses Deploy Book workflow <../external/deploy-book-workflow/README.html>`
+
+{bdg-link-light}`Uses TeachBooks Template <../external/template/README.html>`
+
+```
+
+```{tip}
+This section is useful for user type 3-5.
+```
+
+```{seealso}
+
+[{octicon}`mark-github` Repository deploy book workflow](https://github.com/TeachBooks/deploy-book-workflow)
+
+[{octicon}`mark-github` Repository template](https://github.com/TeachBooks/template)
+
+[{octicon}`book` Collaborative book-editing](../workflows/collaboration.md)
+
+{octicon}`pencil` Exercises:
+- [First file edit](https://teachbooks.io/template/exercises/001.html)
+- [Add a new file to the table of contents](https://teachbooks.io/template/exercises/002.html)
+- [Change book configuration](https://teachbooks.io/template/exercises/003.html)
+- [Syntax exercises](https://teachbooks.io/template/syntax_exercises.html)
+```
+
+````
+
+
+# Write book fully in GitHub interface
+
+Using the GitHub tooling in combination with TeachBook's software, users are able to write their book fully online, without the need to install any software locally. This is especially useful for users that are not familiar with Git and GitHub, or do not have the rights to install software on their computer. To make this possible, users can start with the [TeachBooks Template](../external/template/README.md) after which they make use of the [Deploy Book Workflow](../external/deploy-book-workflow/README.md) to automatically build and release their book online.
+
+## How to do this
+
+New users can start writing their book by following the steps shown in the [TeachBooks Template repository](https://github.com/TeachBooks/template).
+
+Users who already have a TeachBook repository can add the Deploy Book Workflow as explained [here](./release_book_online.md).
+
+After that, users can start writing and editing their book fully online in the GitHub interface. This is supported with:
+- Automatic book builds for all version. See [](./release_book_online.md) for more information
+- A summary describing where the TeachBook is released, errors in the build process per branch and how the release step is configured
+
+## Example of summary
+
+Whenever the workflow is triggered, its progress and a summary can be seen under the `Actions`- `All workflows` - `call-deploy-book` in GitHub! It shows you a descriptive summary. This summary includes, among others, the errors in the build process per branch and where the book is released online.
+
+Here's an example for a summary for the template book:
+
+> ### Branches deployed
+> | Branch 🎋 | Link 🔗 | Build status ☑️ |
+> | :--- | :--- | :--- |
+> | main | [https://teachbooks.github.io/template/main](https://teachbooks.github.io/template/main) | ✅ `Released` |
+> | version2 | [https://teachbooks.github.io/template/version2](https://teachbooks.github.io/template/version2) | 🔴 `Build failed [1]` |
+> | version3 | [https://teachbooks.github.io/template/version3](https://teachbooks.github.io/template/version3) | ⭕ `Build failed [2]` |
+>
+> #### Legend for build status
+> ✅ `Released` - build success, new version released.
+>
+> 🔴 `Build failed [1]` - build failure, previous version of the book reused.
+>
+> ⭕ `Build failed [2]` - build failure, no previous version reused.
+>
+> ### Preview of build errors & warnings
+> For more details please see the corresponding `build-books` jobs in the left pane.
+>
+> On branch `version2`:
+> ```
+> �[91m/home/runner/work/template/template/book/some_content/overview.md:5: WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]�[39;49;00m
+> ```
+>
+> On branch `version3`:
+> ```
+> /home/runner/work/_temp/ff8c8325-8d8b-4c0b-a2b2-32d2169c55bc.sh: line 8: teachbooks: command not found
+> ```
+>
+
+## Exercise
+Check out [the exercises](https://teachbooks.io/template/exercises.html) in the TeachBooks template to see for yourself how you can write and edit your book fully online in GitHub!
diff --git a/book/helper_code/converter.md b/book/helper_code/converter.md
index b90bdcb..0460d96 100644
--- a/book/helper_code/converter.md
+++ b/book/helper_code/converter.md
@@ -1,7 +1,7 @@
(tex_md_converter)=
# Convert LaTeX to Markdown
-A script is to convert LaTeX files to Markdown for use in Jupyter Books {cite:p}`timon_latex`.
+A script is to convert LaTeX files to Markdown for use in TeachBooks and Jupyter Books v1 {cite:p}`timon_latex`.
This script has been used successfully on at least one book in the TU Delft OPEN library: [Introduction to particle and continuum mechanics, by Timon Idema](https://textbooks.open.tudelft.nl/textbooks/catalog/book/81). The author is able to convert nearly everything in this book automatically, with only a few manual adjustments needed (e.g., a special character and a figure caption).
diff --git a/book/helper_code/intro.md b/book/helper_code/intro.md
index 6e8f8e7..b02a601 100644
--- a/book/helper_code/intro.md
+++ b/book/helper_code/intro.md
@@ -1,7 +1,8 @@
# Scripts for automating workflow
-This chapter contains a few scripts which can be useful in the book-editing process:
- - [LaTeX to markdown conversion](tex_md_converter) to convert a LaTeX file into jupyter-book compatible markdown.
+This chapter contains a few scripts which can be useful in the book-editing process, all of which are scripts and/or files stored in other repositories (they are _not_ Sphinx extensions).
+
+ - [LaTeX to markdown conversion](tex_md_converter) to convert a LaTeX file into TeachBook compatible markdown.
- [Snippitall](Snippitall) to insert the same code snippet at a certain point in each md file in a specific folder and all subfolder.
- [Snippitonce](Snippitonce) to insert the same code snippet at a certain point in each md file only in a specific folder.
- [Extensionchecker](Extensionchecker) to identify the kind of files present in subfolder
diff --git a/book/images/nothing.svg b/book/images/nothing.svg
new file mode 100644
index 0000000..2c4a47c
--- /dev/null
+++ b/book/images/nothing.svg
@@ -0,0 +1 @@
+
+
diff --git a/book/installation-and-setup/anaconda.md b/book/installation-and-setup/anaconda.md
index 502ffe9..2a1ba28 100644
--- a/book/installation-and-setup/anaconda.md
+++ b/book/installation-and-setup/anaconda.md
@@ -1,9 +1,11 @@
-# Managing code-related software: Anaconda
-
+````{margin}
```{admonition} User types
:class: tip
This page is useful for user type 5.
```
+````
+
+# Managing code-related software: Anaconda
Before you can start using python in your book, you need Anaconda. 'Anaconda's conda tool simplifies package and environment management across operating systems' (Anaconda.com), such as windows or MacOS. It makes getting started with python a lot easier because it already has a lot of useful python packages pre-installed. Unfortunately, each of these packages are themselves require a number of different packages to function properly. Do you like installing all of them? You shouldn't---but where do you get them come from? Many of those packages are packages required by only a few specific packages. These packages are called _dependencies_, and are necessary to make your Python packages function as expected. When you run install a specific package, `conda` (part of Anaconda) checks all of the dependent packages that are needed and makes sure they are also provided in the `environment` (collection of software with a specific version) that is being created. In reality, this is simply a folder on your computer with all of the `*.py` files stored in it. This _package management_ is what `conda` and `pip` are really doing when you use them to install a package. It also checks that it has a suitable _version_ of each dependency; this is why it sometime takes a long time to install a package Unfortunately, this means that as you add more packages to a particular environment, it gets more and more difficult to make sure everything works well together. Luckily, there is a practical solution: create new environments for specific projects to make sure the proper packages can function properly!
@@ -34,7 +36,7 @@ A python virtual environment is, like the name might suggest, a reserved space w
### Set-up environments
-Now we will set up your first environment. The following steps will create an Anaconda environment and install Python 3.11. Even if you already have Python 3.11, it is still good practice to create a dedicated Anaconda environment for each of your major projects such as creating a jupyter book.
+Now we will set up your first environment. The following steps will create an Anaconda environment and install Python 3.11. Even if you already have Python 3.11, it is still good practice to create a dedicated Anaconda environment for each of your major projects such as creating a TeachBook.
For simplicity we will call this environment `my_new_book_env`, but you can give it any name you like.
@@ -45,7 +47,7 @@ For simplicity we will call this environment `my_new_book_env`, but you can give
4. Additional 4th step: `pip install -r requirements.txt` (explanation in the following section)
-Now everytime you want to work on your jupyter-book, you need to activate the environment! (step 3) If you don't activate your environment, you will work in a 'wrong' working environment that might not contain all the packages you need.
+Now everytime you want to work on your TeachBook, you need to activate the environment! (step 3) If you don't activate your environment, you will work in a 'wrong' working environment that might not contain all the packages you need.
As mentioned before, python packages can be downloaded in the environments you create. Both NumPy and pandas are popular Python packages used for data manipulation and analysis. For the creation of Jupyter Books, we will use the package `teachbooks` which is a wrapper around JupyterBooks. More information about this package [here](jupyter-book-setup.md).
diff --git a/book/installation-and-setup/collab.md b/book/installation-and-setup/collab.md
index 201c1c9..c09090c 100644
--- a/book/installation-and-setup/collab.md
+++ b/book/installation-and-setup/collab.md
@@ -1,9 +1,11 @@
-# Organize editing team, collaboration and visibility
-
+````{margin}
```{admonition} User types
:class: tip
This page is useful for user type 4-5.
```
+````
+
+# Organize editing team, collaboration and visibility
## Roles and responsibilities
To ensure smooth collaboration, it is essential to define the roles and responsibilities within your team. Firstly, designate who will be in charge of team organization ('administrators') who should be at least user type 4. Additionally, assign 'maintainers' responsible for combining content, also requiring at least user type 4. 'Editors' should be identified for editing and reviewing content, requiring at least user type 3.
@@ -13,7 +15,7 @@ Finally, ensure that team members identify themselves according to the user type
## Review process
Furthermore, establish a clear editing and review process.
-For the editing process, establish some practical rules on whether to use issues, branches and forks for adding content, fixing typos or making other changes. Furthermore, it can help to write down when you expect (draft) merge/pull requests and how to use the assign and review options in GitHub/GitLab. It is advisable to have at least a maintainer review each piece of content to maintain quality and consistency. Provide explanation on how you organize the book-editing and how you'd like to receive feedback in both the readme as the published book. The use of the [repository button {fa}`github`, suggest edit {fa}`pencil` and issue button {fa}`lightbulb`](https://jupyterbook.org/en/stable/basics/repository.html) is advised.
+For the editing process, establish some practical rules on whether to use issues, branches and forks for adding content, fixing typos or making other changes. Furthermore, it can help to write down when you expect (draft) merge/pull requests and how to use the assign and review options in GitHub/GitLab. It is advisable to have at least a maintainer review each piece of content to maintain quality and consistency. Provide explanation on how you organize the book-editing and how you'd like to receive feedback in both the readme as the published book. The use of the [repository button {octicon}`mark-github`, suggest edit {fa}`pencil` and issue button {fa}`lightbulb`](https://jupyterbook.org/v1/basics/repository.html) is advised.
(draft_book)=
## Define draft version of book
diff --git a/book/installation-and-setup/copyright.md b/book/installation-and-setup/copyright.md
index f825244..82b60a0 100644
--- a/book/installation-and-setup/copyright.md
+++ b/book/installation-and-setup/copyright.md
@@ -1,12 +1,18 @@
-(copyright)=
-# Copyright and Licenses checklist
-
-> This page reuses adapted CC BY content from the TU Delft Library. {cite:p}`tud_cip_24`. {fa}`quote-left`{ref}`Find out more here.`
+````{margin}
+```{attributiongrey} Attribution
+:class: attribution
+This page reuses adapted CC BY content from the TU Delft Library. {cite:p}`tud_cip_24`. {fa}`quote-left`{ref}`Find out more here.`
+```
```{admonition} User types
:class: tip
This page is useful for all user types.
```
+````
+
+(copyright)=
+# Copyright and Licenses checklist
+
The previous sections have familiarized you with the necessary software for your user type, the basics of Git, and how to collaborate with your team using Git. Now it's time to create your own content. This section will provide an overview of the copy right laws which need to be taking into account when creating and including content at TU Delft!
diff --git a/book/installation-and-setup/copyright/considerations.md b/book/installation-and-setup/copyright/considerations.md
index b507d7f..ea24246 100644
--- a/book/installation-and-setup/copyright/considerations.md
+++ b/book/installation-and-setup/copyright/considerations.md
@@ -1,7 +1,14 @@
+````{margin}
+```{attributiongrey} Attribution
+:class: attribution
+This page reuses adapted CC BY content from {cite:t}`tud_cip_24`. {fa}`quote-left`{ref}`Find out more here.`
+```
+````
+
(copyright_considerations)=
# Copyright Considerations
-> This page reuses adapted CC BY content from {cite:t}`tud_cip_24`. {fa}`quote-left`{ref}`Find out more here.`
+
Copyright law dictates how online book material can and should be created, maintained and shared. An author should understand a few key concepts, as well as best practices, in order to create a book that not only is a useful resource, but, also fairly reuses the work of others and, if provided with an open license, enables original content to also be reused.
@@ -59,12 +66,6 @@ The use of open licenses actually does not prohibit the author from using the ma
**Still don't agree?** Sorry. Please take this up with your nearest library or copyright expert and let us know if you get a different response! In the meantime, we will simply list ourselves as authors, use CC BY licenses and remember that TU Delft holds the copyright for our work produced as teachers.
-```{warning}
-The TeachBooks Team isn't sure where code and data lie here. Since TeachBooks is oriented towards education, we assume that TU Delft also owns the copyright for this.
-
-Do you have a better answer? Let us know!
-```
-
## Licensing
This dictates how others may or may not be able to share or (re)use your work. It is (fortunately) becoming more common to include licenses with educational material (including books), which makes it much easier to understand how specific material can be used. Note that _in the absence of a license, you must assume that nothing can be reused!_ In this case you have to ask permission to the copyright holder, which can be a time-consuming process. License considerations are described in more detail in the following pages.
@@ -83,4 +84,4 @@ There are many legal aspects to consider when creating an online book. Hopefully
2. Clearly **indicate where and how you have used the work of others** in your book (i.e., within the _content_ of your book).
3. **Summarize all sources** used in your book, as well as what may or may not be included under the license which you have chosen.
-The following pages illustrate how to do this. It turns out to be not only a clear set of instructions for (re)users of your content, but also to help you remember what you have used in your book and where to find it later if changes are needed.
\ No newline at end of file
+The following pages illustrate how to do this. It turns out to be not only a clear set of instructions for (re)users of your content, but also to help you remember what you have used in your book and where to find it later if changes are needed.
diff --git a/book/installation-and-setup/copyright/licenses.md b/book/installation-and-setup/copyright/licenses.md
index 40fb5d7..f3e2e7d 100644
--- a/book/installation-and-setup/copyright/licenses.md
+++ b/book/installation-and-setup/copyright/licenses.md
@@ -1,8 +1,13 @@
+````{margin}
+```{attributiongrey} Attribution
+:class: attribution
+This page reuses adapted CC BY content from {cite:t}`hall21`. {fa}`quote-left`{ref}`Find out more here.`
+```
+````
+
(copyright_licenses)=
# Licenses
-> This page reuses adapted CC BY content from {cite:t}`hall21`. {fa}`quote-left`{ref}`Find out more here.`
-
Here we present an overview of various license types, with a particular focus on the preference of TeachBooks to use Permissive Open Licenses, regardless of whether material is _content, code or data_ (described below).
```{admonition} Why permissive open licenses?
@@ -11,7 +16,7 @@ Here we present an overview of various license types, with a particular focus on
Since we (TeachBooks) authors have been working on making online books, we see the value in making content available for reuse. When preparing a new page or assignment, nothing makes us happier than seeing a CC BY license on something that we would like to (re)use ourselves. Why? Because we know that all we have to do is properly attribute the work and we can get on with our true passion: **teaching!**
```
-This page is written expressly for content authors of online interactive textbooks (e.g., those including, but not restricted to, Jupyter Books), which are composed of two parts:
+This page is written expressly for content authors of online interactive textbooks (e.g., those including, but not restricted to, TeachBooks), which are composed of two parts:
1. An online document in the form of a website, accessible at a specific URL, and
2. The _source code,_ which defines the _content_ and is required to create the website.
diff --git a/book/installation-and-setup/copyright/recommendations.md b/book/installation-and-setup/copyright/recommendations.md
index 16ea6b8..5d2fba1 100644
--- a/book/installation-and-setup/copyright/recommendations.md
+++ b/book/installation-and-setup/copyright/recommendations.md
@@ -22,7 +22,7 @@ The recommendations on this page are designed for content that is available in t
## Key Locations in the Book
-Note that there are several types of pages and files that can be incorporated into your TeachBook which, together, accomplish our goals of proper attribution and referencing. These are summarized in the table and explained in more detail in the following sections, along with examples for implementation in a Jupyter Book.
+Note that there are several types of pages and files that can be incorporated into your TeachBook which, together, accomplish our goals of proper attribution and referencing. These are summarized in the table and explained in more detail in the following sections, along with examples for implementation in a TeachBook..
```{list-table} Key Locations in the Book for Attribution and Referencing Best Practices
:header-rows: 1
@@ -52,20 +52,71 @@ Note that there are several types of pages and files that can be incorporated in
(copyright_recc_content)=
### Content Pages
-Make sure you show the source of your content where it is provided. We adopt a standard icon and link to help readers recognize this: {fa}`quote-left`{ref}`Find out more here.`
+Make sure you show the source of your content where it is provided. We adopt a standard icon and link to help readers recognize this: {fa}`quote-left`{ref}`Find out more here.`. This can be used to provide attribution to authors for specific pages too
#### How to implement this in your book
-Copy the following line into your content file
-```md
-> This page reuses content from {cite:t}`bib_id`. {fa}`quote-left`{ref}`Find out more here.`
+> This page reuses content from {cite:t}`bib_id`. {fa}`quote-left`{ref}`Find out more here.`
+
+(custom_attribution)=
+##### Format as custom admonition
+The previous syntax might be used for other purposes as well. An alternative is a custom attribution admonition:
+
+Therefore, use the following syntax:
+
+````{margin}
+```{attributiongrey} Attribution
+:class: attribution
+Written by
+This page reuses CC BY 4.0 licensed content from {cite:t}`jason_moore`. {fa}`quote-left`{ref}`Find out more here.`
+```
+````
+
+`````md
+````{margin}
+```{attributiongrey} Attribution
+:class: attribution
+Written by
+This page reuses content from {cite:t}`bib_id`. {fa}`quote-left`{ref}`Find out more here. "
@@ -111,7 +113,7 @@ And type the following command to set the email address:
## GitHub Desktop
-GitHub is a competitor company to GitLab. It provides very similar services, but they are often called different names, or have slightly different features. GitHub provides a free software that is very useful: [GitHub Desktop](https://desktop.github.com/)! While GitLab is a cloud-based version control system built around Git, GitHub Desktop makes it possible to manage our Git repositories locally on our computers, even though they are stored on GitLab. This is very useful for working with the jupyter-book more extensively and work on interactive features. GitHub Desktop provides an alternative to Git in VS Code, and will be described on a later stage.
+GitHub is a competitor company to GitLab. It provides very similar services, but they are often called different names, or have slightly different features. GitHub provides a free software that is very useful: [GitHub Desktop](https://desktop.github.com/)! While GitLab is a cloud-based version control system built around Git, GitHub Desktop makes it possible to manage our Git repositories locally on our computers, even though they are stored on GitLab. This is very useful for working with the TeachBook more extensively and work on interactive features. GitHub Desktop provides an alternative to Git in VS Code, and will be described on a later stage.
## Terminology
This is a (non-exhaustive) list of terminology that will be used in Git for local use.
@@ -129,4 +131,4 @@ This is a (non-exhaustive) list of terminology that will be used in Git for loca
## More on GitLab/GitHub
-To get to know more about working in GitLab/GitHub and getting familiar with its features, click [here](../workflows/collaboration.md) or watch this [video](https://www.youtube.com/watch?v=1SBtM3znviU&t=1s)!
\ No newline at end of file
+To get to know more about working in GitLab/GitHub and getting familiar with its features, click [here](../workflows/collaboration.md) or watch this [video](https://www.youtube.com/watch?v=1SBtM3znviU&t=1s)!
diff --git a/book/installation-and-setup/git.md b/book/installation-and-setup/git.md
index 4434739..90489d5 100644
--- a/book/installation-and-setup/git.md
+++ b/book/installation-and-setup/git.md
@@ -1,9 +1,11 @@
-# Collaboration tool: Git
-
+````{margin}
```{admonition} User types
:class: tip
This page is useful for user type 3-5.
```
+````
+
+# Collaboration tool: Git
You will need to interact with Git to collaborate on a TeachBook, even if you are working by yourself! You've been introduced to it in the [exercises in the template](../intro/template.md) and you'll be guided through all of the steps in detail in [](../workflows/collaboration.md), but what is this "thing" that sounds suspiciously like something only a computer scientist would want to use?
diff --git a/book/installation-and-setup/git_bash_conda_vs-code.md b/book/installation-and-setup/git_bash_conda_vs-code.md
index b11dd01..586c7c6 100644
--- a/book/installation-and-setup/git_bash_conda_vs-code.md
+++ b/book/installation-and-setup/git_bash_conda_vs-code.md
@@ -1,12 +1,14 @@
-# Combining Git Bash, VS Code and Conda
-
+````{margin}
```{admonition} User types
:class: tip
This page is useful for user type 5.
```
+````
+
+# Combining Git Bash, VS Code and Conda
## Conda in Git Bash
-Git Bash is a shell (also referred to as "the terminal") that is automatically installed with git. It provides Unix-like commands on a Windows OS, and is recommended for working with open source projects like Jupyter (for example `pip install`, building Jupyter books, using Git Bash in VS Code, etc). To do this, `conda` needs to be setup properly; this is described here:
+Git Bash is a shell (also referred to as "the terminal") that is automatically installed with git. It provides Unix-like commands on a Windows OS, and is recommended for working with open source projects like Jupyter (for example `pip install`, building TeachBooks, using Git Bash in VS Code, etc). To do this, `conda` needs to be setup properly; this is described here:
(vscode-setup-bash)=
````{tab} Windows - Git Bash (preferred)
diff --git a/book/installation-and-setup/jupyter-book-setup.md b/book/installation-and-setup/jupyter-book-setup.md
index a947a77..da65557 100644
--- a/book/installation-and-setup/jupyter-book-setup.md
+++ b/book/installation-and-setup/jupyter-book-setup.md
@@ -1,13 +1,15 @@
-# Build your book: JupyterBook
-
+````{margin}
```{admonition} User types
:class: tip
This page is useful for user type 5.
```
+````
-
diff --git a/book/installation-and-setup/overview.md b/book/installation-and-setup/overview.md
index eb209c9..a99389e 100644
--- a/book/installation-and-setup/overview.md
+++ b/book/installation-and-setup/overview.md
@@ -1,9 +1,11 @@
-# Install & authenticate required software
-
+````{margin}
```{admonition} User types
:class: tip
This page is useful for user type 4-5.
```
+````
+
+# Install & authenticate required software
Now that the types of users have been explained, you might have an idea which type corresponds to you!
@@ -14,4 +16,4 @@ The following table will link the relevant installation and setup steps for you.
| Type 1.github.io/` url, for example the [template book](https://teachbooks.github.io/template/)), which takes all the steps of hosting out of your hands. Next to GitHub-provided URLs, you can set up a custom owned URL, although this requires some additional skills on a domain which you should own.
-If you're part of TU Delft, you can put your book in the [TUDelft-Book organisation](https://github.com/tudelft-books), which allows you to host your book at `oit.tudelft.nl/`. If you've a private book which is part of the [GitHub Enterprise TU Delft](https://github.com/enterprises/tudelft) and is using SSO, a random url is generated `.github.io/`. For courses we advise you to create a organization with the course name so that the URL represent that course.
+If you're part of TU Delft, you can put your book in the [TUDelft-Book organisation](https://github.com/tudelft-books), which allows you to host your book at `oit.tudelft.nl/`. If you've a private book which is part of the [GitHub Enterprise TU Delft](https://github.com/enterprises/tudelft) and is using SSO, a random url is generated `.github.io/`. For courses we advise you to create an organization with the course name so that the URL represent that course.
On TU Delft's GitLab you need a webserver, which was offered by TeachBooks in the past (to be recognized by the url `teachbooks.tudelft.nl/`), and is still offered by the TU Delft OIT team (to be recognized by the url `interactivetextbooks.tudelft.nl/`).
## Real-time editing book
-Editing the book can happen both locally as online on GitHub/GitLab. If done locally, the book can be generated and viewed locally too (typically takes around 1 minute) but this requires you to be at least user type 4 or 5 depending on the book content. The built book can also be viewed online separate from the released version.
+Editing the book can be done both locally and online on GitHub/GitLab. If done locally, the book can be generated and viewed locally too (typically takes around 1 minute) but this requires you to be at least user type 4 or 5 depending on the book content. The built book can also be viewed online separate from the released version.
-On GitHub we developed a [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). For a private repository, there is an extensive but limited amount of actions-minutes required for published your book. If this proves to be a limit, consider applying for [Teacher benefits](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers) or joining the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft).
+On GitHub we developed an [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). For a private repository, there is an extensive but limited amount of actions-minutes required for publishing your book. If this proves to be a limit, consider applying for [Teacher benefits](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers) or joining the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft).
-On GitLab a webserver is required to process book-changes online. Both we and other people at TU Delft have a simplistic workflow which can be used when you're set up on those Git environments and webservers. This simplistic workflow doesn't build all branches, is not easily adaptable, doesn't cache environments, doesn't give a visual summary, and doesn't allow for parallel processes (for every build a runner needs to be assigned for which there's typically only one available). If you want to use GitLab but still want to make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in an active editing-phase since constant copyright checks have to be performed. The amount of computing power available is dependent on how you set the server yourself.
+For GitLab a webserver is required, if GitLab pages is not enabled, to process book-changes online. Both we and other people at TU Delft have a simplistic workflow which can be used when you're set up on those Git environments and webservers. This simplistic workflow doesn't build all branches, is not easily adaptable, doesn't cache environments, doesn't give a visual summary, and doesn't allow for parallel processes (for every build a runner needs to be assigned for which there's typically only one available). If you want to use GitLab but still want to make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in an active editing-phase since constant copyright checks have to be performed. The amount of computing power available is dependent on how you set the server yourself.
## Setting up book repository and website
On GitHub you can start right away with a git environment and online book using our [template](../external/template/README.md) without the need for any webserver setup!
@@ -52,10 +59,11 @@ GitHub has a nice integration with the [GitHub Desktop application](git-setup_lo
Here's a table summarizing the information:
| | GitHub | TU Delft GitLab |
|--|----------|-------------|
+| Account | Free GitHub account (owned by Microsoft) 🤝 | Closed, TU Delft account 🔒 |
| Book url | GitHub pages (`.github.io/`), for TU Delft books a custom URL (`oit.tudelft.nl/`), for private books on TU Delft GitHub Enterprise with SSO a random URL (`.github.io/`), or custom url `./`> 🌐 | TU Delft OIT (`interactivetextbooks.tudelft.nl/`) 🎓 |
-| Real-time book editing | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) 🚀 | Automated but simplistic (not easily adaptable, no caching environments, no visual summaries, no parallel processes) 🛵 For TU Delft OIT: restricted adaptations because of copyright checks 🚫 |
+| Real-time book editing | Automated and flexible (multiple version of the book, building error insights, fast, custom urls) with [DBW](../external/deploy-book-workflow/README.md) 🚀 | Some automated scripts exist, but simplistic (not easily adaptable, no caching environments, no visual summaries, no parallel processes) 🛵 For TU Delft OIT: restricted adaptations because of copyright checks 🚫 |
| Setting up book website | Immediate and automated with [template](../external/template/README.md) ⚡️ | Manual setup on personal webserver, or access required by TeachBooks or TU Delft OIT 🚧 |
-| Book access with SSO | Only available for GitHub pages on GitHub Enterprise of TU Delft 🎓, optional with custom URL ✅ | Optional ✅ |
+| Book access with SSO | Only available for GitHub pages on GitHub Enterprise of TU Delft 🎓, optional with custom URL ✅ | Optional ✅ |
| Access to source code | Private (if part of organization linked to educational account) /public / internally TU Delft (on GitHub Enterprise of TU Delft) 👥 | Private / public (read-only) / internally TU Delft, editing requires requires SSO login 👥 👀 |
| Book size limits | 1 GB for all branches 📚 | 150 MB per book 📕 |
| GitHub Desktop | Well integrated 😎 | Basic integration 🙂 |
diff --git a/book/installation-and-setup/user_types.md b/book/installation-and-setup/user_types.md
index 7eb516e..636cdb2 100644
--- a/book/installation-and-setup/user_types.md
+++ b/book/installation-and-setup/user_types.md
@@ -1,6 +1,6 @@
# User types
-Different types of users will interact with the website or the Jupyter Books differently and will therefore need to know more or less about the composition of the book. For now we will differentiate 5 types of users.
+Different types of users will interact with the website or the TeachBooks differently and will therefore need to know more or less about the composition of the book. For now we will differentiate 5 types of users.
## User type 1: Students providing feedback via the book website
@@ -32,7 +32,7 @@ class: dark-light
```
-In a similar manner as students, colleagues and team members can leave content-related comments on the website through extensions or GitHub/GitLab features (e.g., Issues). In this way, multiple teachers can give input in the draft of the textbook and course material without requiring a complete understanding of Jupyter Books or GitLab/GitHub. The responsible teacher (or student assistants) can then make adaptations to the book as recommended by their colleagues.
+In a similar manner as students, colleagues and team members can leave content-related comments on the website through extensions or GitHub/GitLab features (e.g., Issues). In this way, multiple teachers can give input in the draft of the textbook and course material without requiring a complete understanding of TeachBooks or GitLab/GitHub. The responsible teacher (or student assistants) can then make adaptations to the book as recommended by their colleagues.
## User type 3: Colleague making adjustments via the browser
diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md
index e265115..a2597ea 100644
--- a/book/installation-and-setup/versioning.md
+++ b/book/installation-and-setup/versioning.md
@@ -1,9 +1,11 @@
-# Versioning and URLs
-
+````{margin}
```{admonition} User types
:class: tip
This page is useful for user type 4-5.
```
+````
+
+# Versioning and URLs
Online books can be easily updated, however, this might confuse readers. Therefore, it's good practice to be aware of this and, where needed, provide an explicit version to the readers.
diff --git a/book/installation-and-setup/versions_URLs.md b/book/installation-and-setup/versions_URLs.md
index d948409..4561c1d 100644
--- a/book/installation-and-setup/versions_URLs.md
+++ b/book/installation-and-setup/versions_URLs.md
@@ -6,8 +6,10 @@ If you plan on maintaining only one public version, it is advisable to set `BEHA
To share the built book / website of old versions for your book on GitHub you have a few options:
- Create a branch for each version. When doing this, [the GitHub workflow](../external/deploy-book-workflow/README.md) will build it on GitHub pages. Here's a few tips:
- - It's advised to use the version as branch name. In case of versions per academic year, you can just name each branch to the current academic year, this leads to the URL with the same academic year..
- - It is recommended to update the primary branch as the `PRIMARY BRANCH` when using the [GitHub workflow](gh-workflow-settings) whenever a new version is considered to be the most primary one. This ensures that readers are redirected to a consistent URL, even when new versions of the book are added later.
+ - It's advised to use the version as branch name, making it very clear which branch to which website. In case of versions per academic year, you can just name each branch to the current academic year, this leads to the URL with the same academic year. In case of book which are more stable over year, you could consider a simpler v1.1. See the page on [TeachBooks versioning](./versioning_changelog.md) for more information about how to name versions (and thus branches).
+ - You might consider a draft version for each version, in which you collect contributions leading up to a new release of the non-draft versoin. It's advised to name the draft branches so that the link with the non-draft version is obvious. Furthermore, you might consider the [Draft-Release Workflow](../features/draft-release.md)
+ - Whenever a new version is considered to be the most primary one, it is recommended to update the branch `PRIMARY BRANCH` when using the [GitHub workflow](gh-workflow-settings). This ensures that readers which have visited your book before are redirected to a consistent URL, even when new versions of the book are added later. Furthermore, it revert new readers to the most primary one.
+ - Set the primary branch (or its draft branch) as the default branch in git, so that that branch is directly visible when people visit your repository. Furthermore, this is probably the branch where you'd like contributers to start from when forking / opening a pull request.
- Eventually, you can add old branches to the list of `BRANCHES_ARCHIVED` when using the [GitHub workflow](gh-workflow-settings) to include a banner on the page indicating its archived state. Alternatively, you can add a banner manually to `_config.yml`, as explained [here](../basic-features/banner.md).
- If you're using tags (as will be explained in [later](./versioning_changelog.md)), you can create a branch from a tag locally by running: `git branch `.
- If you have many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store.
diff --git a/book/installation-and-setup/vscode-setup.md b/book/installation-and-setup/vscode-setup.md
index a2e76d7..5ecb421 100644
--- a/book/installation-and-setup/vscode-setup.md
+++ b/book/installation-and-setup/vscode-setup.md
@@ -1,9 +1,11 @@
-# Editing text: VS Code
-
+````{margin}
```{admonition} User types
:class: tip
This page is useful for user type 4 and 5.
```
+````
+
+# Editing text: VS Code
VS Code is a text editor with some extra features, such as integrated source control and a file browser. Moreover, extensions are available to add functionality to VS Code.
@@ -13,7 +15,7 @@ VS Code can be downloaded from [here](https://code.visualstudio.com). The instal
## Extensions
-When working with Jupyter Book (or Notebooks in general), these extensions are highly recommended:
+When working with TeachBooks (or Jupyter Notebooks in general), these extensions are highly recommended:
- User type 4-5:
- [MyST-Markdown](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) - adds support for MyST markdown, including previews.
diff --git a/book/intro.md b/book/intro.md
index a918590..165c9f7 100644
--- a/book/intro.md
+++ b/book/intro.md
@@ -1,8 +1,8 @@
# TeachBooks Manual
-This manual is primarily designed for and by teachers for use in education, but should be a useful resource for anyone interested in creating and collaborating on
+
+ Pagina-1
+
+ Blad.1
+ 1
+
+
+ Blad.3
+ Source code (repository) *.md, *.ipynb
+ (repository) *.md, *.ipynb
+
+ Blad.6
+
+
+ Blad.7
+
+
+ Blad.8
+
+
+ Blad.9
+
+
+ Blad.11
+ 2
+
+
+ Blad.12
+ Markup Software teachbooks, jupyter-book, sphinx,
+ teachbooks, jupyter - book, sphinx,
+
+ Blad.13
+
+
+ Blad.14
+
+
+ Blad.15
+
+
+ Blad.16
+
+
+ Blad.18
+
+
+ Blad.28
+ 3
+
+
+ Blad.29
+ Local website *.html
+ website *.html
+
+ Blad.30
+
+
+ Blad.31
+
+
+ Blad.32
+
+
+ Blad.33
+
+
+ Blad.34
+
+
+ Blad.38
+ 4
+
+
+ Blad.39
+ Online book Webserver, GitHub pages
+ Webserver, GitHub pages
+
+ Blad.40
+
+
+ Blad.41
+
+
+ Blad.42
+
+
+ Blad.43
+
+
+ Blad.44
+
+
+ Blad.45
+
+
+ Blad.46
+
+
+ Blad.47
+
+
+ Blad.48
+
+
+ Blad.49
+ TeachBooks tools and GitHub do the rest!
+
+
+ Blad.52
+
+
+ Blad.53
+ You edit text-based files
+ based files
+
+ Blad.620
+
+ Blad.621
+
+
+ Blad.622
+
+
+ Blad.623
+
+
+ Blad.624
+
+
+ Blad.625
+
+
+ Blad.626
+
+
+ Blad.627
+
+
+ Blad.628
+
+
+ Blad.629
+
+
+ Blad.630
+
+
+ Blad.631
+
+
+ Blad.632
+
+
+ Blad.633
+
+
+ Blad.634
+
+
+ Blad.635
+
+
+ Blad.636
+
+
+ Blad.637
+
+
+ Blad.638
+
+
+ Blad.639
+
+
+ Blad.640
+
+
+ Blad.641
+
+
+ Blad.642
+
+
+ Blad.643
+
+
+ Blad.644
+
+
+ Blad.645
+
+
+ Blad.646
+
+
+ Blad.647
+
+
+ Blad.648
+
+
+ Blad.649
+
+
+ Blad.650
+
+
+ Blad.651
+
+
+ Blad.652
+
+
+ Blad.653
+
+
+ Blad.654
+
+
+ Blad.655
+
+
+ Blad.656
+
+
+ Blad.657
+
+
+ Blad.658
+
+
+ Blad.659
+
+
+ Blad.660
+
+
+ Blad.661
+
+
+ Blad.662
+
+
+ Blad.663
+
+
+ Blad.664
+
+
+ Blad.665
+
+
+ Blad.666
+
+
+ Blad.667
+
+
+ Blad.668
+
+
+ Blad.669
+
+
+ Blad.670
+
+
+ Blad.671
+
+
+ Blad.672
+
+
+ Blad.673
+
+
+ Blad.674
+
+
+ Blad.675
+
+
+ Blad.676
+
+
+ Blad.677
+
+
+ Blad.678
+
+
+ Blad.679
+
+
+ Blad.680
+
+
+ Blad.681
+
+
+ Blad.682
+
+
+ Blad.683
+
+
+ Blad.684
+
+
+ Blad.685
+
+
+ Blad.686
+
+
+ Blad.687
+
+
+ Blad.688
+
+
+ Blad.689
+
+
+ Blad.690
+
+
+ Blad.691
+
+
+ Blad.692
+
+
+ Blad.693
+
+
+ Blad.694
+
+
+ Blad.695
+
+
+ Blad.696
+
+
+ Blad.697
+
+
+ Blad.698
+
+
+ Blad.699
+
+
+ Blad.700
+
+
+ Blad.701
+
+
+ Blad.702
+
+
+ Blad.703
+
+
+ Blad.704
+
+
+ Blad.705
+
+
+ Blad.706
+
+
+ Blad.707
+
+
+ Blad.708
+
+ Blad.709
+
+
+ Blad.710
+
+
+ Blad.711
+
+
+ Blad.712
+
+
+ Blad.713
+
+
+ Blad.714
+
+
+ Blad.715
+
+
+ Blad.716
+
+
+ Blad.717
+
+
+ Blad.718
+
+
+ Blad.719
+
+
+ Blad.720
+
+
+ Blad.721
+
+
+ Blad.722
+
+
+ Blad.723
+
+
+ Blad.724
+
+
+ Blad.725
+
+
+ Blad.726
+
+
+ Blad.727
+
+
+ Blad.728
+
+
+
+ Blad.729
+
+
+ Blad.730
+
+
+ Blad.731
+
+
+ Blad.732
+
+
+ Blad.733
+
+
+ Blad.734
+
+
+ Blad.735
+
+
+ Blad.736
+
+
+ Blad.737
+
+
+ Blad.738
+
+
+ Blad.739
+
+
+ Blad.740
+
+
+ Blad.741
+
+
+ Blad.742
+
+
+ Blad.743
+
+
+ Blad.744
+
+
+ Blad.745
+
+
+ Blad.746
+
+
+ Blad.747
+
+
+ Blad.748
+
+
+ Blad.749
+
+
+ Blad.750
+
+
+ Blad.751
+
+
+ Blad.752
+
+
+ Blad.753
+
+
+ Blad.754
+
+
+ Blad.755
+
+
+ Blad.756
+
+
+ Blad.757
+
+
+ Blad.758
+
+
+ Blad.759
+
+
+ Blad.760
+
+
+ Blad.761
+
+
+ Blad.762
+
+
+ Blad.763
+
+
+ Blad.764
+
+
+ Blad.765
+
+
+ Blad.766
+
+
+ Blad.767
+
+
+ Blad.768
+
+
+ Blad.769
+
+
+ Blad.770
+
+
+ Blad.771
+
+
+ Blad.772
+
+
+ Blad.773
+
+
+ Blad.774
+
+
+ Blad.775
+
+
+ Blad.776
+
+
+ Blad.777
+
+
+ Blad.778
+
+
+ Blad.779
+
+
+ Blad.780
+
+
+ Blad.781
+
+
+ Blad.782
+
+
+ Blad.783
+
+
+ Blad.784
+
+
+ Blad.785
+
+
+ Blad.786
+
+
+ Blad.787
+
+
+ Blad.788
+
+
+ Blad.789
+
+
+ Blad.790
+
+
+ Blad.791
+
+
+ Blad.792
+
+
+ Blad.793
+
+
+ Blad.794
+
+
+ Blad.795
+
+
+ Blad.796
+
+
+ Blad.797
+
+
+ Blad.798
+
+
+ Blad.799
+
+
+ Blad.800
+
+
+ Blad.801
+
+
+ Blad.802
+
+
+ Blad.803
+
+
+ Blad.804
+
+
+ Blad.805
+
+
+ Blad.806
+
+
+
+ Blad.807
+
+ Blad.808
+
+
+ Blad.809
+
+
+ Blad.810
+
+
+ Blad.811
+
+
+ Blad.812
+
+
+ Blad.813
+
+
+ Blad.814
+
+
+ Blad.815
+
+
+ Blad.816
+
+
+ Blad.817
+
+
+ Blad.818
+
+
+ Blad.819
+
+
+ Blad.820
+
+
+ Blad.821
+
+
+ Blad.822
+
+
+ Blad.823
+
+
+ Blad.824
+
+
+ Blad.825
+
+
+ Blad.826
+
+
+ Blad.827
+
+
+ Blad.828
+
+
+ Blad.829
+
+
+ Blad.830
+
+
+ Blad.831
+
+
+ Blad.832
+
+
+ Blad.833
+
+
+ Blad.834
+
+
+ Blad.835
+
+
+ Blad.836
+
+
+ Blad.837
+
+
+ Blad.838
+
+
+ Blad.839
+
+
+ Blad.840
+
+
+ Blad.841
+
+
+ Blad.842
+
+
+ Blad.843
+
+
+ Blad.844
+
+
+ Blad.845
+
+
+ Blad.846
+
+
+ Blad.847
+
+
+ Blad.848
+
+
+ Blad.849
+
+
+ Blad.850
+
+
+ Blad.851
+
+
+ Blad.852
+
+
+ Blad.853
+
+
+ Blad.854
+
+
+ Blad.855
+
+ Blad.856
+
+
+ Blad.857
+
+
+ Blad.858
+
+
+ Blad.859
+
+
+ Blad.860
+
+
+ Blad.861
+
+
+ Blad.862
+
+
+ Blad.863
+
+
+ Blad.864
+
+
+ Blad.865
+
+
+ Blad.866
+
+
+ Blad.867
+
+
+ Blad.868
+
+
+ Blad.869
+
+
+ Blad.870
+
+
+ Blad.871
+
+
+ Blad.872
+
+
+
+ Blad.873
+
+
+ Blad.874
+
+
+ Blad.875
+
+
+ Blad.876
+
+
+ Blad.877
+
+
+ Blad.878
+
+
+ Blad.879
+
+
+ Blad.880
+
+
+ Blad.881
+
+
+ Blad.882
+
+
+ Blad.883
+
+
+ Blad.884
+
+ Blad.885
+
+
+ Blad.886
+
+
+ Blad.887
+
+
+ Blad.888
+
+
+ Blad.889
+
+
+
+ Blad.890
+
+
+ Blad.891
+
+
+ Blad.892
+
+
+ Blad.893
+
+ Blad.894
+
+
+ Blad.895
+
+
+ Blad.896
+
+
+ Blad.897
+
+
+ Blad.898
+
+
+ Blad.899
+
+
+ Blad.900
+
+
+ Blad.901
+
+
+
+ Blad.902
+
+
+ Blad.903
+
+
+ Blad.904
+
+
+ Blad.905
+
+
+ Blad.906
+
+
+ Blad.907
+
+
+ Blad.908
+
+
+ Blad.909
+
+
+ Blad.910
+
+
+ Blad.911
+
+
+ Blad.912
+
+
+ Blad.913
+
+
+ Blad.914
+
+
+ Blad.915
+
+
+ Blad.916
+
+
+ Blad.917
+
+
+ Blad.918
+
+
+ Blad.919
+
+
+ Blad.920
+
+
+ Blad.921
+
+
+ Blad.922
+
+
+ Blad.923
+
+
+ Blad.924
+
+
+ Blad.925
+
+
+ Blad.926
+
+
+ Blad.927
+
+
+ Blad.928
+
+
+
+ Blad.929
+
+ Blad.930
+
+
+
+
diff --git a/book/intro/figures/intro-book-2.vsdx b/book/intro/figures/intro-book-2.vsdx
new file mode 100644
index 0000000..d0deade
Binary files /dev/null and b/book/intro/figures/intro-book-2.vsdx differ
diff --git a/book/intro/next.md b/book/intro/next.md
index 5af2661..22712df 100644
--- a/book/intro/next.md
+++ b/book/intro/next.md
@@ -1,6 +1,6 @@
# You Know the Basics: What Next?
-You've seen what a JupyterBook is, how TeachBooks tries to help you with making those, and what the potential is in teaching. So what's next?
+You've seen what a TeachBooks is, how git is useful in combination with it, and what the potential is in teaching. So what's next?
In this manual we explain how to get going depending on the way you want to use it. If you successfully followed the steps until here, you'll be able to make book as a 'user type 3'!
diff --git a/book/intro/template.md b/book/intro/template.md
index 9e4fb0c..353d2ea 100644
--- a/book/intro/template.md
+++ b/book/intro/template.md
@@ -7,7 +7,7 @@ width: 150px
align: right
```
-Now that you've been introduced to the basics of a Jupyter Book, let's make one! The TeachBooks Team has put together a set of tools to make the book-creation process as smooth and automatic as possible. This page guides you through the process of creating a book, followed by a series of exercises that are designed to help you get used to the syntax and structure of a Jupyter Book, as well as the tools and essential workflows associated with the editing, checking and review processes.
+Now that you've been introduced to the basics of a TeachBook, let's make one! The TeachBooks Team has put together a set of tools to make the book-creation process as smooth and automatic as possible. This page guides you through the process of creating a book, followed by a series of exercises that are designed to help you get used to the syntax and structure of a TeachBook, as well as the tools and essential workflows associated with the editing, checking and review processes.
## 1. Create a GitHub account
TeachBooks relies of freely available services from GitHub to store files online, carry out the book-building process and host your book as a website. All you need to get started is a GitHub account (not counted in the 10 clicks 🤭).
@@ -26,7 +26,7 @@ Go to the [TeachBooks Template repository on GitHub](https://github.com/TeachBoo
```
## 3. Let's practice!
-Getting used to the syntax of writing in a Jupyter Book can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises covering the TeachBooks workflow have been prepared for you. The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages.
+Getting used to the syntax of writing in a TeachBook can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises covering the TeachBooks workflow have been prepared for you. The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages.
The exercises on the TeachBooks Workflow can be found in your book at `https://.github.io//exercises/exercises` (case sensitive) or at https://teachbooks.io/template/exercises.html.
diff --git a/book/intro/workflow.md b/book/intro/workflow.md
index bc0c038..a472ace 100644
--- a/book/intro/workflow.md
+++ b/book/intro/workflow.md
@@ -26,7 +26,7 @@ Let's create a space for you idea to form. You can create your own version of th
width: 100px
align: right
```
-Creativity activated, let's start adding content to your book! You'll add text, images, videos, math, interactive quizes, coding, widgets, etc. As editing the book is not directly done in a graphical interface with buttons like Microsoft Word, you'll need to learn a bit of syntax. The [MyST syntax cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) will be added to your bookmarks. The changes you'll make have to be added to the GitHub version control system, creating `commits` on the your git `branch`.
+Creativity activated, let's start adding content to your book! You'll add text, images, videos, math, interactive quizes, coding, widgets, etc. As editing the book is not directly done in a graphical interface with buttons like Microsoft Word, you'll need to learn a bit of syntax. The [MyST syntax cheat sheet](https://jupyterbook.org/v1/reference/cheatsheet.html) will be added to your bookmarks. The changes you'll make have to be added to the GitHub version control system, creating `commits` on the your git `branch`.
## 4 check changes
```{figure} figures/check.png
diff --git a/book/references.bib b/book/references.bib
index 3b54aed..884c860 100644
--- a/book/references.bib
+++ b/book/references.bib
@@ -1,144 +1,220 @@
@misc{timon_latex,
- title={LaTeX to Markdown conversion},
- author={Idema (Delft University of Technology), Timon},
- institution ={Delft University of Technology},
- url={https://gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion},
- year={2024},
- note = {Retrieved December, 2024. BSD-3.}
+ title = {LaTeX to Markdown conversion},
+ author = {Idema (Delft University of Technology), Timon},
+ institution = {Delft University of Technology},
+ url = {https://gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion},
+ year = {2024},
+ note = {Retrieved December, 2024. BSD-3.},
}
@misc{hall21,
- author = {Hall, Matt},
- title = {Which open licence should I choose?},
- institution = {Agile Scientific},
- url = {https://agilescientific.com/blog/2021/2/17/which-open-licence-should-i-choose},
- year = {2021},
- note = {Online; posted 17-February-2021. CC BY.}
+ author = {Hall, Matt},
+ title = {Which open licence should I choose?},
+ institution = {Agile Scientific},
+ url = {https://agilescientific.com/blog/2021/2/17/which-open-licence-should-i-choose},
+ year = {2021},
+ note = {Online; posted 17-February-2021. CC BY.},
}
@misc{jason_moore,
- title={Learn Multibody Dynamics, SymPy},
- author={Moore, Jason},
- url={https://moorepants.github.io/learn-multibody-dynamics/sympy.html},
- year={2023}
+ title = {Learn Multibody Dynamics, SymPy},
+ author = {Moore, Jason},
+ url = {https://moorepants.github.io/learn-multibody-dynamics/sympy.html},
+ year = {2023},
}
@misc{tud_cip_24,
- author = {{TU Delft Library}},
- title = {Copyright Information Point},
- url = {https://www.tudelft.nl/library/support/copyright},
- year = {2024},
- note = {Retrieved December, 2024. CC BY 4.0.}
+ author = {{TU Delft Library}},
+ title = {Copyright Information Point},
+ url = {https://www.tudelft.nl/library/support/copyright},
+ year = {2024},
+ note = {Retrieved December, 2024. CC BY 4.0.},
}
@misc{deploy_book,
- author = {{TeachBooks}},
- title = {GitHub reusable action: publish your book online to GitHub Pages},
- url = {https://github.com/TeachBooks/deploy-book-workflow},
- year = {2024},
- note = {Retrieved December, 2024. BSD-3-Clause.}
+ author = {{TeachBooks}},
+ title = {GitHub reusable action: publish your book online to GitHub Pages},
+ url = {https://github.com/TeachBooks/deploy-book-workflow},
+ year = {2024},
+ note = {Retrieved December, 2024. BSD-3-Clause.},
}
@misc{download_link,
- author = {{TeachBooks}},
- title = {Sphinx extension: download link replacer},
- url = {https://github.com/TeachBooks/Download-Link-Replacer},
- year = {2024},
- note = {Retrieved December, 2024. BSD-3-Clause.}
+ author = {{TeachBooks}},
+ title = {Sphinx extension: download link replacer},
+ url = {https://github.com/TeachBooks/Download-Link-Replacer},
+ year = {2024},
+ note = {Retrieved December, 2024. BSD-3-Clause.},
}
@misc{patches,
- author = {{TeachBooks}},
- title = {Sphinx extension: JupyterBook-Patches},
- url = {https://github.com/TeachBooks/JupyterBook-Patches},
- year = {2024},
- note = {Retrieved December, 2024. BSD-3-Clause.}
+ author = {{TeachBooks}},
+ title = {Sphinx extension: JupyterBook-Patches},
+ url = {https://github.com/TeachBooks/JupyterBook-Patches},
+ year = {2024},
+ note = {Retrieved December, 2024. BSD-3-Clause.},
}
@misc{annotator,
- author = {{TeachBooks}},
- title = {Local Annotator Extension},
- url = {https://github.com/TeachBooks/annotator},
- year = {2024},
- note = {Retrieved December, 2024. BSD-3-Clause.}
+ author = {{TeachBooks}},
+ title = {Local Annotator Extension},
+ url = {https://github.com/TeachBooks/annotator},
+ year = {2024},
+ note = {Retrieved December, 2024. BSD-3-Clause.},
}
@misc{nested,
- author = {{TeachBooks}},
- title = {Git workflow: Share content between book},
- url = {https://github.com/TeachBooks/Nested-Books},
- year = {2024},
- note = {Retrieved December, 2024. CC BY 4.0.}
+ author = {{TeachBooks}},
+ title = {Git workflow: Share content between book},
+ url = {https://github.com/TeachBooks/Nested-Books},
+ year = {2024},
+ note = {Retrieved December, 2024. CC BY 4.0.},
}
@misc{grasple,
- author = {{TeachBooks}},
- title = {Sphinx extension: Grasple},
- url = {https://github.com/TeachBooks/Sphinx-Grasple-public},
- year = {2024},
- note = {Retrieved December, 2024. MIT.}
+ author = {{TeachBooks}},
+ title = {Sphinx extension: Grasple},
+ url = {https://github.com/TeachBooks/Sphinx-Grasple-public},
+ year = {2024},
+ note = {Retrieved December, 2024. MIT.},
}
@misc{image,
- author = {{TeachBooks}},
- title = {Sphinx extension: Image Inverter},
- url = {https://github.com/TeachBooks/Sphinx-Image-Inverter},
- year = {2024},
- note = {Retrieved December, 2024. BSD-3-Clause.}
+ author = {{TeachBooks}},
+ title = {Sphinx extension: Image Inverter},
+ url = {https://github.com/TeachBooks/Sphinx-Image-Inverter},
+ year = {2024},
+ note = {Retrieved December, 2024. BSD-3-Clause.},
}
@misc{tudelft_theme,
- author = {{TeachBooks}},
- title = {Sphinx extension: TU Delft theme},
- url = {https://github.com/TeachBooks/Sphinx-TUDelft-theme},
- year = {2024},
- note = {Retrieved December, 2024. MIT.}
+ author = {{TeachBooks}},
+ title = {Sphinx extension: TU Delft theme},
+ url = {https://github.com/TeachBooks/Sphinx-TUDelft-theme},
+ year = {2024},
+ note = {Retrieved December, 2024. MIT.},
}
@misc{tippy,
- author = {{TeachBooks}},
- title = {TeachBooks Sphinx extension: Rich hover over tips},
- url = {https://github.com/TeachBooks/teachbooks-sphinx-tippy},
- year = {2024},
- note = {Retrieved December, 2024. MIT.}
+ author = {{TeachBooks}},
+ title = {TeachBooks Sphinx extension: Rich hover over tips},
+ url = {https://github.com/TeachBooks/teachbooks-sphinx-tippy},
+ year = {2024},
+ note = {Retrieved December, 2024. MIT.},
}
@misc{template,
- author = {{TeachBooks}},
- title = {Your first TeachBook using the GitHub template},
- url = {https://github.com/TeachBooks/template},
- year = {2024},
- note = {Retrieved December, 2024. CC BY 4.0.}
+ author = {{TeachBooks}},
+ title = {Your first TeachBook using the GitHub template},
+ url = {https://github.com/TeachBooks/template},
+ year = {2024},
+ note = {Retrieved December, 2024. CC BY 4.0.},
}
@misc{useful_code,
- author = {{TeachBooks}},
- title = {Useful python code},
- url = {https://github.com/TeachBooks/Useful_python_code},
- year = {2024},
- note = {Retrieved December, 2024. BSD-3-Clause.}
+ author = {{TeachBooks}},
+ title = {Useful python code},
+ url = {https://github.com/TeachBooks/Useful_python_code},
+ year = {2024},
+ note = {Retrieved December, 2024. BSD-3-Clause.},
}
@misc{launch_buttons,
- author = {{TeachBooks}},
- title = {Custom launch buttons},
- url = {https://github.com/TeachBooks/Sphinx-launch-buttons},
- year = {2024},
- note = {Retrieved December, 2024. BSD-3-Clause.}
+ author = {{TeachBooks}},
+ title = {Custom launch buttons},
+ url = {https://github.com/TeachBooks/Sphinx-launch-buttons},
+ year = {2024},
+ note = {Retrieved December, 2024. BSD-3-Clause.},
}
@misc{sphinx-colors,
- author = {{TeachBooks}},
- title = {Sphinx Named Colors},
- url = {https://github.com/TeachBooks/Sphinx-Named-Colors},
- year = {2024},
- note = {Retrieved January 2025. MIT.}
+ author = {{TeachBooks}},
+ title = {Sphinx Named Colors},
+ url = {https://github.com/TeachBooks/Sphinx-Named-Colors},
+ year = {2024},
+ note = {Retrieved January 2025. MIT.},
}
@misc{semver,
- author = {Tom Preston-Werner},
- title = {Semantic Versioning specification},
- url = {https://semver.org/},
- year = {2025},
- note = {Retrieved February 2025. CC BY 3.0.}
+ author = {Tom Preston-Werner},
+ title = {Semantic Versioning specification},
+ url = {https://semver.org/},
+ year = {2025},
+ note = {Retrieved February 2025. CC BY 3.0.},
}
+
+@misc{sphinx-iframes,
+ author = {{TeachBooks}},
+ title = {Sphinx iframes},
+ url = {https://github.com/TeachBooks/sphinx-iframes},
+ year = {2025},
+ note = {Retrieved April 2025. MIT.},
+}
+
+@misc{sphinx-prime-applets,
+ author = {{TeachBooks}},
+ title = {Sphinx PRIME applets},
+ url = {https://github.com/TeachBooks/Sphinx-PRIME-applets},
+ year = {2025},
+ note = {Retrieved April 2025. MIT.},
+}
+
+@misc{teachbooks_package,
+ author = {{TeachBooks}},
+ title = {TeachBooks Package: Jupyter Book Wrapper},
+ url = {https://github.com/TeachBooks/TeachBooks},
+ year = {2024},
+ note = {Retrieved April, 2025. MIT License.},
+}
+
+@misc{sphinx-indexed-definitions,
+ author = {{TeachBooks}},
+ title = {Sphinx Indexed Definitions},
+ url = {https://github.com/TeachBooks/Sphinx-Indexed-Definitions},
+ year = {2025},
+ note = {Retrieved April, 2025. MIT License.},
+}
+
+@misc{sphinx-interactive-graph,
+ author = {{TeachBooks}},
+ title = {Sphinx Indexed Definitions},
+ url = {https://github.com/TeachBooks/Sphinx-Indexed-Definitions},
+ year = {2025},
+ note = {Retrieved April, 2025. MIT License.},
+}
+
+@misc{sphinx-proof,
+ author = {{executablebooks}},
+ title = {Sphinx Proof},
+ url = {https://github.com/executablebooks/sphinx-exercise},
+ year = {2024},
+ note = {Retrieved September, 2025. MIT License.},
+}
+
+@misc{sphinx-exercise,
+ author = {{executablebooks}},
+ title = {Sphinx Exercise},
+ url = {https://github.com/executablebooks/sphinx-exercise},
+ year = {2024},
+ note = {Retrieved September, 2025. MIT License.},
+}
+
+@inproceedings{dummyreference,
+ author = {Author, Some and Writer, Another and Novelist, Also and Cowriter, Maybe},
+ title = {Efficient Estimation of Word Representations in Vector Space},
+ booktitle = {Proceedings of Workshop at ICLR},
+ year = {2013},
+ url = {https://arxiv.org/abs/1301.3781},
+}
+
+@misc{TeachBooksLogo,
+ author = {Veronica Comin},
+ title = {The logo of TeachBooks.},
+ year = {2024},
+ date = {2024-11-13},
+ note = {License: CC BY},
+ url = {https://github.com/TeachBooks/logos_and_visualisations},
+ howpublished = {\url{https://github.com/TeachBooks/logos_and_visualisations}},
+ copyright = {© TeachBooks 2024},
+}
+
diff --git a/book/tools/figmaker.md b/book/tools/figmaker.md
index 534a57d..cdd73c8 100644
--- a/book/tools/figmaker.md
+++ b/book/tools/figmaker.md
@@ -1,11 +1,13 @@
-# Figure syntax maker
-
+````{margin}
```{admonition} User types
:class: tip
This section is useful for user type 3-5.
```
+````
-One might quickely forget the code for making figures, here is a useful tool to make your figures, just specify all information and the code is produced for you:
+# Figure syntax maker
+
+One might quickly forget the code for making figures, so here we provide a useful tool to make the source code for figures. Simply specify the information in the empty fields below and the code is produced for you automatically:
provides a range of features which are visually appealing and functional. These elements can enhance the interactivity and visual design of your book, offering additional information or links in a compact and visually engaging way. The badges, buttons and icons are made available through Sphinx and they themselves wrote a [documentation](https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html) about it.
+
. Our aim is to provide a simple way to start book-making for new users (it only takes 10 clicks!) through advanced usage for experienced users. We hope you find this resource useful and refer back to it often.
+This manual is primarily designed for and by teachers for use in education, but should be a useful resource for anyone interested in creating and collaborating on a TeachBook: a 
Sphinx backend with additional editing tools and book features. Our aim is to provide a simple way to start book-making for new users (it only takes 10 clicks!), ease the editing process for anyone, and provide additional features developed for education-purposes. We hope you find this resource useful and refer back to it often.
-TeachBooks originated at Delft University of Technology in the Netherlands, and some of the material in this Manual reflects tools and resources specific to TU Delft. With the exception of a few tools for which we have educational licenses at Delft, everything in this Manual is open source. Despite this, we are happy to grow our community beyond Delft and welcome contributions from all users.
+TeachBooks originated at Delft University of Technology in the Netherlands, and some of the material in this Manual reflects tools and resources specific to TU Delft. With the exception of a few tools for which we have educational licenses at Delft, everything in this Manual is open source. Despite this, we are happy to grow our open source community beyond Delft and welcome contributions from all users.
For more information about TeachBooks, visit [https://teachbooks.io/](https://teachbooks.io/). Do not hesitate to reach out via email at [info@teachbooks.io](mailto:info@teachbooks.io) or contribute on GitHub via discussions, issues or pull requests.
@@ -11,9 +11,9 @@ Happy book building!
## How to Use this Manual
There are several "parts" to the manual:
-- **Your First TeachBook!** introduces the essential platforms and workflows, and contains a _workshop_ that can be completed independently or as part of a TeachBooks training. We recommend even experienced Jupyter Book users go through this material to better understand the TeachBooks vision on how to make books collaboratively, as this drives much of our tool development. The workshop is designed to be completed in 1-2 hours and does not require any prior knowledge or installation (just a GitHub account).
+- **Your First TeachBook!** introduces the essential platforms and workflows, and contains a _workshop_ that can be completed independently or as part of a TeachBooks training. We recommend even experienced Jupyter Book v1 users go through this material to better understand the TeachBooks vision on how to make books collaboratively, as this drives much of our tool development. The workshop is designed to be completed in 1-2 hours and does not require any prior knowledge or installation (just a GitHub account).
- **Getting Going!** begins with an overview of _User Types_, which are used to help understand which parts of the Manual are most relevant to you. Detailed software installation instructions, book and team setup and workflows are also provided in this part.
- The **Features** part describes a suite of tools that are useful for teachers, many of which are developed by TeachBooks contributors specifically for use in education. Many of these tools are illustrated in the **Examples**.
- A few special tools are included in the **Editing Tools** that are useful when writing content.
-See the final chapters of this book (under **Miscellaneous**) for additional information about References, Credits, etc.
\ No newline at end of file
+See the final chapters of this book (under **Miscellaneous**) for additional information about References, Credits, etc.
diff --git a/book/intro/book.md b/book/intro/book.md
index b8e7426..86b6b0b 100644
--- a/book/intro/book.md
+++ b/book/intro/book.md
@@ -1,15 +1,16 @@
# What is a TeachBook?
-Never seen a TeachBook before? Here's a small demo of our MUDE-book!
+Never seen a TeachBook before? Here's a small demo of the MUDE-book!
```{video} https://www.youtube.com/embed/gbBsWo6em4c?si=ayKhISsx06LmGbDD
+:class: blend
```
-So what are you looking at? It's a website generated with the [Jupyter Book package](https://jupyterbook.org/). Various extensions have been added to improve the student-experience, especially for technical topics! The actual website you're looking at now is a Jupyter Book. With TeachBooks we aim to make it easy to collaboratively use it, even if you've little experience with the software package which is part of it.
+So what are you looking at? It's a website generated with the [TeachBooks package](https://github.com/TeachBooks/TeachBooks) which in turn makes use of many other tools, of which [Jupyter Book package](https://jupyterbook.org/v1/) and [Sphinx](https://www.sphinx-doc.org/) are the most prominent. Various extensions have been added to improve the student-experience, especially for technical topics! With TeachBooks we aim to make it easy to collaboratively use it, even if you've little experience with the software package which is part of it.
## Three Key Ingredients
-To create a Jupyter Book, three key ingredients are needed:
+To create a TeachBook, three key ingredients are needed:
1. A **configuration file** to define functionalities, `_config.yml`
2. A **table of contents** file to list which files should end up in the book, `_toc.yml`, as well as define its structure
@@ -37,7 +38,7 @@ Note the arrangement of the 3 key book ingredients in a subdirectory called `boo
`````{admonition} Text-based files? yml? What is that?!
:class: tip, dropdown
-Text-based files are digital files on your computer that you can open in a text editor and read directly. There are many file extensions used for text-based files, a few common ones related to Jupyter Book are: Markdown (`*.md`), Jupyter Notebooks (`*.ipynb`), and YAML (`*.yml`).
+Text-based files are digital files on your computer that you can open in a text editor and read directly. There are many file extensions used for text-based files, a few common ones related to TeachBooks are: Markdown (`*.md`), Jupyter Notebooks (`*.ipynb`), and YAML (`*.yml`).
YAML (or YML) is a text-based file format that is primarily used to store data. It is useful because it is easy for humans to read and write, and easy for machines to _parse_ and generate., which is why YAML is often used for configuration files. Here is an example of a YAML file...can you tell what information is being stored?
@@ -63,25 +64,23 @@ You can see quite clearly that a number of files are listed, and that they are o
## How is a book made?
-A book is made by by writing content in text-based files such as Markdown (`*.md`), Jupyter Notebooks (`*.ipynb`), etc. After that, software is used to "parse" these files and create the final book (e.g., Jupyter Book). Fortunately when getting started you don't need to worry about the software because TeachBooks has set up GitHub tools for you that take care of this process automatically! The process is illustrated in the diagram below.
+A book is made by by writing content in text-based files such as Markdown (`*.md`), Jupyter Notebooks (`*.ipynb`), etc. After that, software is used to "parse" these files and create the final book (e.g., website). Fortunately when getting started you don't need to worry about the software because TeachBooks has set up GitHub tools for you that take care of this process automatically! The process is illustrated in the diagram below.
+
+```{figure} figures/intro-book-2.svg
-```{figure} figures/intro-book.svg
----
-width: 700px
----
The process of building a book with TeachBooks. When just getting started, TeachBooks tools enables you to focus on what matters most: learning to write content for your book!
```
```{admonition} Familiar with LaTeX? There are similarities!
:class: dropdown
-Have you ever used LaTeX? It turns out there are a lot of similarities with Jupyter Book. Here is a quick list:
+Have you ever used LaTeX? It turns out there are a lot of similarities with TeachBooks. Here is a quick list:
1. Writing "source code" in text-based files (i.e., `*.tex` versus `*.md`, `*.ipynb`, etc) that is generally easy to read without the markup and uses special functions to format rich document objects (e.g., tables, figures, etc).
-2. The "book" is created by using a piece of software that parses the source code and creates the final document (a `*.pdf` versus a `*.html` for Jupyter Book).
+2. The "book" is created by using a piece of software that parses the source code and creates the final document (a `*.pdf` versus a `*.html` for TeachBooks).
3. Creating the document structure using a list of files that contain source code that automatically generates the Table of Contents and Index..
4. Sometimes you can spend more time than you like troubleshooting "bugs" that turn out to be simple syntax errors.
-If you've used LaTeX before, it will be relatively easy to learn to use a Jupyter Book.
+If you've used LaTeX before, it will be relatively easy to learn to use a TeachBook.
```
## Why are Git and GitHub Important?
diff --git a/book/intro/figures/intro-book-2.svg b/book/intro/figures/intro-book-2.svg
new file mode 100644
index 0000000..bc35954
--- /dev/null
+++ b/book/intro/figures/intro-book-2.svg
@@ -0,0 +1,1456 @@
+
+
+
+
diff --git a/book/intro/figures/intro-book-2.vsdx b/book/intro/figures/intro-book-2.vsdx
new file mode 100644
index 0000000..d0deade
Binary files /dev/null and b/book/intro/figures/intro-book-2.vsdx differ
diff --git a/book/intro/next.md b/book/intro/next.md
index 5af2661..22712df 100644
--- a/book/intro/next.md
+++ b/book/intro/next.md
@@ -1,6 +1,6 @@
# You Know the Basics: What Next?
-You've seen what a JupyterBook is, how TeachBooks tries to help you with making those, and what the potential is in teaching. So what's next?
+You've seen what a TeachBooks is, how git is useful in combination with it, and what the potential is in teaching. So what's next?
In this manual we explain how to get going depending on the way you want to use it. If you successfully followed the steps until here, you'll be able to make book as a 'user type 3'!
diff --git a/book/intro/template.md b/book/intro/template.md
index 9e4fb0c..353d2ea 100644
--- a/book/intro/template.md
+++ b/book/intro/template.md
@@ -7,7 +7,7 @@ width: 150px
align: right
```
-Now that you've been introduced to the basics of a Jupyter Book, let's make one! The TeachBooks Team has put together a set of tools to make the book-creation process as smooth and automatic as possible. This page guides you through the process of creating a book, followed by a series of exercises that are designed to help you get used to the syntax and structure of a Jupyter Book, as well as the tools and essential workflows associated with the editing, checking and review processes.
+Now that you've been introduced to the basics of a TeachBook, let's make one! The TeachBooks Team has put together a set of tools to make the book-creation process as smooth and automatic as possible. This page guides you through the process of creating a book, followed by a series of exercises that are designed to help you get used to the syntax and structure of a TeachBook, as well as the tools and essential workflows associated with the editing, checking and review processes.
## 1. Create a GitHub account
TeachBooks relies of freely available services from GitHub to store files online, carry out the book-building process and host your book as a website. All you need to get started is a GitHub account (not counted in the 10 clicks 🤭).
@@ -26,7 +26,7 @@ Go to the [TeachBooks Template repository on GitHub](https://github.com/TeachBoo
```
## 3. Let's practice!
-Getting used to the syntax of writing in a Jupyter Book can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises covering the TeachBooks workflow have been prepared for you. The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages.
+Getting used to the syntax of writing in a TeachBook can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises covering the TeachBooks workflow have been prepared for you. The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages.
The exercises on the TeachBooks Workflow can be found in your book at `https://