diff --git a/book/external/Download-Link-Replacer b/book/external/Download-Link-Replacer index d6f318f..89235af 160000 --- a/book/external/Download-Link-Replacer +++ b/book/external/Download-Link-Replacer @@ -1 +1 @@ -Subproject commit d6f318f52cef2f64f44f195c95ea8a449cf37fe2 +Subproject commit 89235af168099dfc6af2be6cab19ca9a5565e1c8 diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches index e6e2706..541f4a3 160000 --- a/book/external/JupyterBook-Patches +++ b/book/external/JupyterBook-Patches @@ -1 +1 @@ -Subproject commit e6e27067f60a576e3db745361601a1c43bbae5f4 +Subproject commit 541f4a3220f6d8d07ed2909de66a779fd46b23bf diff --git a/book/external/Nested-Books b/book/external/Nested-Books index abb9e70..97780fc 160000 --- a/book/external/Nested-Books +++ b/book/external/Nested-Books @@ -1 +1 @@ -Subproject commit abb9e707d66ad26e55dfd037835f7f7cc86f2620 +Subproject commit 97780fc7ad1ac36ba7079421a1326343c2488cfb diff --git a/book/external/Sphinx-Grasple-public b/book/external/Sphinx-Grasple-public index 9f6f68a..2ca3894 160000 --- a/book/external/Sphinx-Grasple-public +++ b/book/external/Sphinx-Grasple-public @@ -1 +1 @@ -Subproject commit 9f6f68a8eaf28952c996fa3604f9201e7c40f271 +Subproject commit 2ca3894ef285f238cae1ba120ccf2c0f36e73b31 diff --git a/book/external/Sphinx-Image-Inverter b/book/external/Sphinx-Image-Inverter index 2351ab0..215a5b9 160000 --- a/book/external/Sphinx-Image-Inverter +++ b/book/external/Sphinx-Image-Inverter @@ -1 +1 @@ -Subproject commit 2351ab0e25a067d6420be078232e5a6e3d9c3168 +Subproject commit 215a5b9a8e205dba9ddf27052dba9e56d27c341e diff --git a/book/external/Sphinx-Named-Colors b/book/external/Sphinx-Named-Colors index c85d64e..1307f44 160000 --- a/book/external/Sphinx-Named-Colors +++ b/book/external/Sphinx-Named-Colors @@ -1 +1 @@ -Subproject commit c85d64eacbc6b0980530134b08406193f452cf0f +Subproject commit 1307f44c8d64fb98ce4649f585805666e90ec3aa diff --git a/book/external/Sphinx-PRIME-applets b/book/external/Sphinx-PRIME-applets index 14dc36b..6217c86 160000 --- a/book/external/Sphinx-PRIME-applets +++ b/book/external/Sphinx-PRIME-applets @@ -1 +1 @@ -Subproject commit 14dc36bfdbf89d2d363ea2bdcbc30a64c0f7b00f +Subproject commit 6217c862633bbbbce3365d9b121a7815a09f58a7 diff --git a/book/external/Sphinx-TUDelft-theme b/book/external/Sphinx-TUDelft-theme index 2ab5d1d..86f5772 160000 --- a/book/external/Sphinx-TUDelft-theme +++ b/book/external/Sphinx-TUDelft-theme @@ -1 +1 @@ -Subproject commit 2ab5d1d708aed595b9630c94081e05c11a84b18c +Subproject commit 86f5772bedd64ccbb2ab9ab16577215803ef238c diff --git a/book/external/Sphinx-launch-buttons b/book/external/Sphinx-launch-buttons index 2d85abc..63d5397 160000 --- a/book/external/Sphinx-launch-buttons +++ b/book/external/Sphinx-launch-buttons @@ -1 +1 @@ -Subproject commit 2d85abc35c533a6e756d2c16344fe107be24e427 +Subproject commit 63d539763e9b9ce13f4dab2ef4c4a17c46e953ef diff --git a/book/external/Useful_python_code b/book/external/Useful_python_code index 81e9235..c80863d 160000 --- a/book/external/Useful_python_code +++ b/book/external/Useful_python_code @@ -1 +1 @@ -Subproject commit 81e923516e06441fb0c04f4946819f5dae9b0a68 +Subproject commit c80863d19f7fde7a452200baa4b4fafe12debc95 diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow index e4e3249..65010c7 160000 --- a/book/external/deploy-book-workflow +++ b/book/external/deploy-book-workflow @@ -1 +1 @@ -Subproject commit e4e324964468a21493b92df6771f37b1d0ec69f3 +Subproject commit 65010c7dc0eff87eb4d7729ee251d0df221c44f8 diff --git a/book/external/sphinx-iframes b/book/external/sphinx-iframes index a572035..69e6028 160000 --- a/book/external/sphinx-iframes +++ b/book/external/sphinx-iframes @@ -1 +1 @@ -Subproject commit a57203589e1acfaa216a436ea57d17b0b1e76824 +Subproject commit 69e6028e79a3e5aa521093155ee54201299630ff diff --git a/book/external/teachbooks-sphinx-tippy b/book/external/teachbooks-sphinx-tippy index 4d246da..6122c67 160000 --- a/book/external/teachbooks-sphinx-tippy +++ b/book/external/teachbooks-sphinx-tippy @@ -1 +1 @@ -Subproject commit 4d246da43ec7848928e673ca9223458028d3e473 +Subproject commit 6122c67f86a7c9b95f349c80316571e277f0a66b diff --git a/book/external/template b/book/external/template index efa0edb..ba0733a 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit efa0edbb1180081e8ab57ba95eeaece195d786af +Subproject commit ba0733abc6e31eccd7a478f8dd2a433faf5333f7 diff --git a/book/features/apa.md b/book/features/apa.md index 547e547..d2ece83 100644 --- a/book/features/apa.md +++ b/book/features/apa.md @@ -5,7 +5,7 @@ This page is useful for user type 4 and 5. ``` {bdg-primary}`(To be converted into) Sphinx Extension` -{bdg-link-secondary}`Supported by TeachBooks package ` +{bdg-link-secondary}`Supported by TeachBooks package <./teachbooks_intro.html>` ```` diff --git a/book/features/draft-release.md b/book/features/draft-release.md index 7e8de38..227d113 100644 --- a/book/features/draft-release.md +++ b/book/features/draft-release.md @@ -6,9 +6,9 @@ This page is useful for user type 3-5. ``` -{bdg-link-secondary}`Uses TeachBooks package ` -{bdg-link-light}`Included in TeachBooks Template ` -{bdg-link-light}`Supported by Deploy Book workflow ` +{bdg-link-secondary}`Uses TeachBooks package <./teachbooks_intro.html>` +{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>` +{bdg-link-light}`Supported by Deploy Book workflow <../external/deploy-book-workflow/README.html>` ```` diff --git a/book/features/exercise.md b/book/features/exercise.md index 9f88cfd..a798ee2 100644 --- a/book/features/exercise.md +++ b/book/features/exercise.md @@ -10,8 +10,8 @@ This section is useful for user type 3-5. ``` +++ {bdg-primary}`Sphinx Extension` -{bdg-link-light}`Included in TeachBooks Template ` -{bdg-link-primary-line}`Included in TeachBooks Favourites ` +{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>` +{bdg-link-primary-line}`Included in TeachBooks Favourites <./favourites.html>` ```` # Sphinx exercise diff --git a/book/features/external_toc.md b/book/features/external_toc.md index 24dd53c..d00d478 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -9,7 +9,7 @@ This page reuses MIT licensed content from {cite:t}`teachbooks_package`. {fa}`qu This page is useful for user type 3-5. ``` -{bdg-link-secondary}`Uses TeachBooks package ` +{bdg-link-secondary}`Uses TeachBooks package <./teachbooks_intro.html>` {bdg-success}`WebApp` ```` diff --git a/book/features/favourites.md b/book/features/favourites.md index 4645ac1..a5c4ec8 100644 --- a/book/features/favourites.md +++ b/book/features/favourites.md @@ -5,7 +5,7 @@ This page is useful for user type 3-5. ``` {bdg-primary}`Sphinx Extension` -{bdg-link-light}`Included in TeachBooks Template ` +{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>` ```` diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb index d0bfa2d..6674962 100644 --- a/book/features/live_code.ipynb +++ b/book/features/live_code.ipynb @@ -11,8 +11,8 @@ "```\n", "\n", "{bdg-primary}`Sphinx Extension`\n", - "{bdg-link-light}`Included in TeachBooks Template `\n", - "{bdg-link-primary-line}`Included in TeachBooks Favourites `\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", "```` \n", "\n", diff --git a/book/features/local_server.md b/book/features/local_server.md index f3bf55e..c43f3cc 100644 --- a/book/features/local_server.md +++ b/book/features/local_server.md @@ -4,7 +4,7 @@ This section is useful for user type 4-5. ``` -{bdg-link-secondary}`Uses TeachBooks package ` +{bdg-link-secondary}`Uses TeachBooks package <./teachbooks_intro.html>` ```` (setup-local-server)= diff --git a/book/features/overview.md b/book/features/overview.md index e86e124..49d95c1 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -15,8 +15,8 @@ Additionally, not all features are built and shared in the same way. We do our b - {bdg-success}`Chrome Extension` - {bdg-white}`GitHub App and Javascript script` - {bdg-link-secondary}`Python Package: teachbooks <./teachbooks_intro.html>` -- {bdg-link-light}`GitHub Reusable Action: Deploy Book workflow ` -- {bdg-link-light}`GitHub Template: TeachBooks Template ` +- {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>` @@ -27,4 +27,4 @@ Finally, the purpose, installation process and usage of each features is elabora To see examples for these features, go to the [Examples chapter](../examples/overview.md). -As the [TeachBooks Python Package](./teachbooks_intro.md), the [Deploy Book Workflow](https://teachbooks.io/manual/external/deploy-book-workflow/README.html), [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 in more detail, with links to the pages in this manual where individual features are described. \ No newline at end of file +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 in more detail, with links to the pages in this manual where individual features are described. \ No newline at end of file diff --git a/book/features/release_book_online.md b/book/features/release_book_online.md index 5f494c5..f8d7b23 100644 --- a/book/features/release_book_online.md +++ b/book/features/release_book_online.md @@ -4,17 +4,15 @@ This section is useful for user type 3-5. ``` -{bdg-link-light}`GitHub Reusable Action: Deploy Book workflow ` -{bdg-link-light}`Part of TeachBooks Template ` -{bdg-link-secondary}`Uses TeachBooks package ` - -```` +{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>` # 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](https://teachbooks.io/manual/external/deploy-book-workflow/README.html)) 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. +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). @@ -61,7 +59,7 @@ You can adapt the behaviour by setting repository variables as explained [here]( - 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](https://teachbooks.io/manual/external-content-teachbooks-v0.2.0/features/draft-release.html), which removed book-pages and config lines defined with `# START REMOVE-FROM-RELEASE` and `# END REMOVE-FROM-RELEASE` + - 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 @@ -118,7 +116,7 @@ To create this behavior, do the following: - 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](https://teachbooks.io/manual/features/draft-release.html). 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. +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.html). 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? @@ -211,7 +209,7 @@ Once created during a successful build action, an existing cached environment wi 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](https://teachbooks.io/manual/features/update_env.html) is an excellent way to ensure that environments in the DBW are always up to date and this issue is avoided. +Note that Specifying package version numbers explicitly and updating them via [Dependabot](./update_env.html) 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). @@ -236,4 +234,4 @@ Unlike the virtual environments (next subsection), caches of the book build do n ### 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](https://teachbooks.io/manual/features/update_env.html). \ No newline at end of file +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.html). \ No newline at end of file diff --git a/book/features/sphinx-proof.md b/book/features/sphinx-proof.md index fd0e0ce..cc3110d 100644 --- a/book/features/sphinx-proof.md +++ b/book/features/sphinx-proof.md @@ -10,8 +10,8 @@ This section is useful for user type 3-5. ``` +++ {bdg-primary}`Sphinx Extension` -{bdg-link-light}`Included in TeachBooks Template ` -{bdg-link-primary-line}`Included in TeachBooks Favourites ` +{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>` +{bdg-link-primary-line}`Included in TeachBooks Favourites <./favourites.html>` ```` # Sphinx proof @@ -45,7 +45,7 @@ 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](https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html). +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.html). ## Installation To use this extenstion, follow these steps: diff --git a/book/features/teachbooks_intro.md b/book/features/teachbooks_intro.md index e521c54..bf7d323 100644 --- a/book/features/teachbooks_intro.md +++ b/book/features/teachbooks_intro.md @@ -5,7 +5,7 @@ This section is useful for user type 4-5. {bdg-link-secondary}`Python Package: TeachBooks` -{bdg-link-light}`Included in TeachBooks Template ` +{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>` ``` ```` diff --git a/book/features/write_online.md b/book/features/write_online.md index df0e1cb..c42ec23 100644 --- a/book/features/write_online.md +++ b/book/features/write_online.md @@ -4,21 +4,21 @@ This section is useful for user type 3-5. ``` -{bdg-link-light}`Uses Deploy Book workflow ` -{bdg-link-light}`Uses TeachBooks Template ` +{bdg-link-light}`Uses Deploy Book workflow <../external/deploy-book-workflow/README.html>` +{bdg-link-light}`Uses TeachBooks Template <../external/template/README.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](https://teachbooks.io/manual/external/template/README.html) after which they make use of the [Deploy Book Workflow](https://teachbooks.io/manual/external/deploy-book-workflow/README.html) to automatically build and release their book online. +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.html) after which they make use of the [Deploy Book Workflow](../external/deploy-book-workflow/README.html) 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](https://teachbooks.io/manual/external/deploy-book-workflow/README.html) +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