From 77da9807d217f0fe255f75d780100d94d9c06137 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 14 Sep 2025 09:08:58 +0200 Subject: [PATCH 01/24] WIP add favourites --- book/features/favourites.md | 28 ++++++++++++++++++++++++++++ book/features/overview.md | 10 +++++++++- 2 files changed, 37 insertions(+), 1 deletion(-) create mode 100644 book/features/favourites.md diff --git a/book/features/favourites.md b/book/features/favourites.md new file mode 100644 index 0000000..7b39d96 --- /dev/null +++ b/book/features/favourites.md @@ -0,0 +1,28 @@ +````{margin} +```{admonition} User types +:class: tip +This page is useful for user type 3-5. +``` + +{bdg-primary}`Sphinx Extension` + +``` +```` + +# TeachBooks Favourites + +TeachBooks Favourites is a Sphinx extension which collects all of TeachBooks' favourite features in one place (including tools originally by TeachBooks and from other sources). It is included by default in the [TeachBooks Template](../external/template/README.md) and can be installed independently using `pip install teachbooks-favourites`. The features included are: + +- [Sphinx-Thebe from TeachBooks](./live_code.ipynb) +- [Jupyterbook patches](../external/jupyterbook-patches/README.md) +- [Download link replacer](../external/download-link-replacer/README.md) +- [Sphinx image inverter](../external/sphinx-image-inverter/README.md) +- [Sphinx iframes](../external/sphinx-iframes/README.md) +- [Sphinx exercise (TeachBooks contribution to the original)](https://ebp-sphinx-exercise.readthedocs.io/en/latest/) +- [Teachbooks Sphinx tippy](../external/teachbooks-sphinx-tippy/README.html) +- [Sphinx named colors](../external/sphinx-named-colors/README.md) +- [Sphinx dropdown toggle](../_git/github.com_TeachBooks_Sphinx-Dropdown-Toggle/main/MANUAL.md) +- [Sphinx proof (TeachBooks contribution to the original)](https://sphinx-proof.readthedocs.io/en/latest/) +- [Sphinx code examples](../_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.md) +- [Sphinx accessibility](../_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.html) +- [Sphinx toggle button (TeachBooks contribution to the original)](https://sphinx-togglebutton.readthedocs.io/en/latest/) diff --git a/book/features/overview.md b/book/features/overview.md index f7cf5db..cbeefd6 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -19,6 +19,7 @@ Additionally, not all features are built and shared in the same way. We do our b - {bdg-light}`GitHub Template` - {bdg-dark}`Git Workflow` - {bdg-primary}`Sphinx Extension` +- {bdg-primary-line}`Part of TeachBooks Favourites` - {bdg-danger}`iframe` - {bdg-success}`WebApp` @@ -26,7 +27,7 @@ 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 and the Deploy Book Workflow are important tools that incorporate and deploy more than one feature, an additional explanation is provided on this page in more detail, with links to the pages in this manual where individual features are described. +As the TeachBooks Python Package, the Deploy Book Workflow and TeachBooks Favourites are important tools that incorporate and deploy more than one feature, an additional explanation is provided on this page in more detail, with links to the pages in this manual where individual features are described. (teachbooks_package)= ## TeachBooks Python Package @@ -81,11 +82,13 @@ Important for these features: ### Book Build Commands By default the DBW builds books using the following command: + ``` teachbooks build book/ ``` To use the [Draft-Release Workflow](./draft-release.md) with the Deploy Book Workflow the `BRANCHES_TO_PREPROCESS` variable must be configured for a specific branch, which will then execute the following command: + ``` teachbooks build --release book/ ``` @@ -97,3 +100,8 @@ As described on the [DBW page](../external/deploy-book-workflow/README.md), ther 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). + +(teachbooks-favourites-intro)= +## TeachBooks Favourites + +The [TeachBooks Favourites](./favourites.md) is a sphinx extension which collects all of TeachBooks favourite features in one place. It is included by default in the [TeachBooks Template](../external/template/README.md). All features which are part of TeachBooks Favourites are indicated with {bdg-primary-line}`Part of TeachBooks Favourites`. If you'd like ot use specific features, but not the entire TeachBooks Favourites, you can remove this extension and replace it with the individual extensions you want to use. \ No newline at end of file From 16b12087c6f601ab4d6d9e012850c29215c715e3 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 27 Sep 2025 13:23:54 +0200 Subject: [PATCH 02/24] Update favourites.md --- book/features/favourites.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/features/favourites.md b/book/features/favourites.md index 7b39d96..a19fbcd 100644 --- a/book/features/favourites.md +++ b/book/features/favourites.md @@ -26,3 +26,4 @@ TeachBooks Favourites is a Sphinx extension which collects all of TeachBooks' fa - [Sphinx code examples](../_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.md) - [Sphinx accessibility](../_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.html) - [Sphinx toggle button (TeachBooks contribution to the original)](https://sphinx-togglebutton.readthedocs.io/en/latest/) +- [Notebook execution patterns](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html) \ No newline at end of file From 76ab30859cab25c9b414efef98450a7d1c8d0e11 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 27 Sep 2025 13:36:41 +0200 Subject: [PATCH 03/24] Refactor features overview and add intro pages Split the TeachBooks Python Package and Deploy Book Workflow documentation into dedicated intro pages (teachbooks_intro.md, DBW_intro.md), update references and links throughout feature pages, and revise the _toc.yml structure to include new sections. Added clarifications to favourites and live_code features, improving organization and navigation for users. --- book/_toc.yml | 4 ++ book/features/DBW_intro.md | 40 +++++++++++++++ book/features/draft-release.md | 2 +- book/features/external_toc.md | 2 +- book/features/favourites.md | 4 +- book/features/live_code.ipynb | 2 + book/features/local_server.md | 2 +- book/features/overview.md | 83 ++----------------------------- book/features/teachbooks_intro.md | 35 +++++++++++++ 9 files changed, 90 insertions(+), 84 deletions(-) create mode 100644 book/features/DBW_intro.md create mode 100644 book/features/teachbooks_intro.md diff --git a/book/_toc.yml b/book/_toc.yml index cd93e64..1cbe995 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -42,6 +42,10 @@ parts: - caption: Features chapters: - file: features/overview.md + sections: + - file: features/teachbooks_intro.md + - file: features/DBW_intro.md + - file: features/favourites.md - file: basic-features/overview.md sections: - file: basic-features/jupyterbook.md diff --git a/book/features/DBW_intro.md b/book/features/DBW_intro.md new file mode 100644 index 0000000..fba7911 --- /dev/null +++ b/book/features/DBW_intro.md @@ -0,0 +1,40 @@ + +(deploy-book-workflow-intro)= +## Deploy Book Workflow + +The [Deploy Book Workflow](../external/deploy-book-workflow/README.md) is by default incorporated into any book that has been created using the [TeachBooks Template](../external/template/README.md). We also strongly encourage anyone to consider this tool as an alternative to the "standard" workflow provided by Jupyter Book, as ours automatically builds a different version of your book for every branch in your respository, along with a number of settings that can be used to customize the build process and URL structure of your book(s). This tool is described in more detail on [the Deploy Book Workflow page of this manual](../external/deploy-book-workflow/README.md), and one should note that it influences a number of other aspects of a TeachBook. + +### Related Features + +A list of tools and features that are dependent on, or related to, the Deploy Book Workflow (DBW) is provided here: + +Important for these features: +- [](../external/deploy-book-workflow/README.md): the main DBW page +- [](../external/template/README.md): books created from the Template include DBW by default +- [](./draft-release.md): can be configured directly using the DBW +- [](./update_env.md): behaviors of this tool may influence the DBW +- {ref}`TeachBooks Python Package `: included by default in the DBW +- [](./pull_request_build.md): created to provide DBW-like behavior for PR's from forked repositories +- [](./apa.md): a temporary fix is included in `teachbooks` to enable use in the DBW + +### Book Build Commands + +By default the DBW builds books using the following command: + +``` +teachbooks build book/ +``` + +To use the [Draft-Release Workflow](./draft-release.md) with the Deploy Book Workflow the `BRANCHES_TO_PREPROCESS` variable must be configured for a specific branch, which will then execute the following command: + +``` +teachbooks build --release book/ +``` + +### Environments and Caching + +As described on the [DBW page](../external/deploy-book-workflow/README.md), there is a lot going on "under the hood" with regards to caching of GitHub Action artifacts. This can lead to undesired behavior when using the DBW, especially if package version numbers are not precisely defined. In general we expect the risk of this occurring to be low, as it should only happen when multiple branches are being actively used (new commits on each branch at least once per week), a package from the `requirements.txt` file is updated in the time between creation of two or more branches, and that package _also_ has a significant impact on the book building process. As the Python virtual environment cache is replaced by default if older than one week, the issue should resolve itself within that time frame. + +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). \ No newline at end of file diff --git a/book/features/draft-release.md b/book/features/draft-release.md index 4a7915d..c194753 100644 --- a/book/features/draft-release.md +++ b/book/features/draft-release.md @@ -6,7 +6,7 @@ This page is useful for user type 3-5. ``` -{bdg-link-secondary}`Python Package: teachbooks <./overview#teachbooks-python-package>` +{bdg-secondary}`Python Package: teachbooks <./teachbooks_intro.html>` ```` diff --git a/book/features/external_toc.md b/book/features/external_toc.md index d8aaec5..ea770fa 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}`Python Package: teachbooks <./overview#teachbooks-python-package>` +{bdg-link-secondary}`Python Package: teachbooks <./teachbooks_intro.html>` {bdg-success}`WebApp` ```` diff --git a/book/features/favourites.md b/book/features/favourites.md index a19fbcd..a855105 100644 --- a/book/features/favourites.md +++ b/book/features/favourites.md @@ -26,4 +26,6 @@ TeachBooks Favourites is a Sphinx extension which collects all of TeachBooks' fa - [Sphinx code examples](../_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.md) - [Sphinx accessibility](../_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.html) - [Sphinx toggle button (TeachBooks contribution to the original)](https://sphinx-togglebutton.readthedocs.io/en/latest/) -- [Notebook execution patterns](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html) \ No newline at end of file +- [Notebook execution patterns](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html) + +All features which are part of TeachBooks Favourites are indicated with {bdg-primary-line}`Part of TeachBooks Favourites`. If you'd like to use specific features, but not the entire TeachBooks Favourites, you can remove this extension and replace it with the individual extensions you want to use. \ No newline at end of file diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb index 1d9aa0c..5eb4eed 100644 --- a/book/features/live_code.ipynb +++ b/book/features/live_code.ipynb @@ -11,6 +11,8 @@ "```\n", "\n", "{bdg-primary}`Sphinx Extension`\n", + "{bdg-primary-line}`Part of TeachBooks Favourites`\n", + "\n", "```` \n", "\n", "# Interactive content: Run Python inside your book\n", diff --git a/book/features/local_server.md b/book/features/local_server.md index 415e964..ec21dcc 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}`Python Package: teachbooks <./overview#teachbooks-python-package>` +{bdg-link-secondary}`Python Package: teachbooks <./teachbooks_intro.html>` ```` (setup-local-server)= diff --git a/book/features/overview.md b/book/features/overview.md index cbeefd6..38a4857 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -14,8 +14,8 @@ Additionally, not all features are built and shared in the same way. We do our b - {bdg-warning}`Javascript overlay` - {bdg-success}`Chrome Extension` - {bdg-white}`GitHub App and Javascript script` -- {bdg-link-secondary}`Python Package: teachbooks <./overview.html#teachbooks-python-package>` -- {bdg-light}`GitHub Reusable Action` +- {bdg-link-secondary}`Python Package: teachbooks <./teachbooks_intro.html>` +- {bdg-link-light}`GitHub Reusable Action: Deploy Book workflow <./DBW_intro.html>` - {bdg-light}`GitHub Template` - {bdg-dark}`Git Workflow` - {bdg-primary}`Sphinx Extension` @@ -27,81 +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, the Deploy Book Workflow and TeachBooks Favourites are important tools that incorporate and deploy more than one feature, an additional explanation is provided on this page in more detail, with links to the pages in this manual where individual features are described. - -(teachbooks_package)= -## TeachBooks Python Package - -````{margin} -```{admonition} User types -:class: tip -This section is useful for user type 4-5. -``` -```` - -The TeachBooks Python package is a collection of tools that are used to enhance the Jupyter Book 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](./deploy-book-workflow.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 {ref}`Deploy Book Workflow `, 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` 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 Manual](https://jupyterbook.org/en/stable/publish/web.html), for example, [this GitHub workflow](https://jupyterbook.org/en/stable/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. - -(deploy-book-workflow-intro)= -## Deploy Book Workflow - -The [Deploy Book Workflow](../external/deploy-book-workflow/README.md) is by default incorporated into any book that has been created using the [TeachBooks Template](../external/template/README.md). We also strongly encourage anyone to consider this tool as an alternative to the "standard" workflow provided by Jupyter Book, as ours automatically builds a different version of your book for every branch in your respository, along with a number of settings that can be used to customize the build process and URL structure of your book(s). This tool is described in more detail on [the Deploy Book Workflow page of this manual](../external/deploy-book-workflow/README.md), and one should note that it influences a number of other aspects of a TeachBook. - -### Related Features - -A list of tools and features that are dependent on, or related to, the Deploy Book Workflow (DBW) is provided here: - -Important for these features: -- [](../external/deploy-book-workflow/README.md): the main DBW page -- [](../external/template/README.md): books created from the Template include DBW by default -- [](./draft-release.md): can be configured directly using the DBW -- [](./update_env.md): behaviors of this tool may influence the DBW -- {ref}`TeachBooks Python Package `: included by default in the DBW -- [](./pull_request_build.md): created to provide DBW-like behavior for PR's from forked repositories -- [](./apa.md): a temporary fix is included in `teachbooks` to enable use in the DBW - -### Book Build Commands - -By default the DBW builds books using the following command: - -``` -teachbooks build book/ -``` - -To use the [Draft-Release Workflow](./draft-release.md) with the Deploy Book Workflow the `BRANCHES_TO_PREPROCESS` variable must be configured for a specific branch, which will then execute the following command: - -``` -teachbooks build --release book/ -``` - -### Environments and Caching - -As described on the [DBW page](../external/deploy-book-workflow/README.md), there is a lot going on "under the hood" with regards to caching of GitHub Action artifacts. This can lead to undesired behavior when using the DBW, especially if package version numbers are not precisely defined. In general we expect the risk of this occurring to be low, as it should only happen when multiple branches are being actively used (new commits on each branch at least once per week), a package from the `requirements.txt` file is updated in the time between creation of two or more branches, and that package _also_ has a significant impact on the book building process. As the Python virtual environment cache is replaced by default if older than one week, the issue should resolve itself within that time frame. - -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). - -(teachbooks-favourites-intro)= -## TeachBooks Favourites - -The [TeachBooks Favourites](./favourites.md) is a sphinx extension which collects all of TeachBooks favourite features in one place. It is included by default in the [TeachBooks Template](../external/template/README.md). All features which are part of TeachBooks Favourites are indicated with {bdg-primary-line}`Part of TeachBooks Favourites`. If you'd like ot use specific features, but not the entire TeachBooks Favourites, you can remove this extension and replace it with the individual extensions you want to use. \ No newline at end of file +As the [TeachBooks Python Package](./teachbooks_intro.md), the [Deploy Book Workflow](./DBW_intro.md) and [TeachBooks Favourites](./favourites.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/teachbooks_intro.md b/book/features/teachbooks_intro.md new file mode 100644 index 0000000..89d6b73 --- /dev/null +++ b/book/features/teachbooks_intro.md @@ -0,0 +1,35 @@ + +````{margin} +```{admonition} User types +:class: tip +This section is useful for user type 4-5. + +{bdg-link-secondary}`Python Package: TeachBooks` + +``` +```` + +(teachbooks_package)= +## TeachBooks Python Package + +The TeachBooks Python package is a collection of tools that are used to enhance the Jupyter Book 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](./deploy-book-workflow.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 {ref}`Deploy Book Workflow `, 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` 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 Manual](https://jupyterbook.org/en/stable/publish/web.html), for example, [this GitHub workflow](https://jupyterbook.org/en/stable/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 From 627f2f28b558666984bfa161ac868a5c43cb08c7 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 27 Sep 2025 14:00:43 +0200 Subject: [PATCH 04/24] Refactor and reorganize _toc.yml structure Moved basic features into a new 'Original Jupyter Book and Sphinx Features' section, consolidated and reordered feature sections, and updated references to external documentation. This improves the logical organization and clarity of the table of contents. --- book/_toc.yml | 45 +++++++++++++++++++++++---------------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/book/_toc.yml b/book/_toc.yml index 1cbe995..65066cc 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -44,25 +44,12 @@ parts: - file: features/overview.md sections: - file: features/teachbooks_intro.md - - file: features/DBW_intro.md + - file: external/deploy-book-workflow/README.md - file: features/favourites.md - - file: basic-features/overview.md - sections: - - file: basic-features/jupyterbook.md - - file: basic-features/figures.md - - file: basic-features/equations.md - - file: basic-features/videos.md - - file: basic-features/References.md - - file: basic-features/code.md - - file: basic-features/Code_block_figures - - file: basic-features/badges.md - - file: basic-features/banner - title: Banner or Announcement - file: features/easy-editing.md sections: - file: external/template/README.md - file: features/draft-release - - file: external/deploy-book-workflow/README.md - file: features/pull_request_build.md - file: features/local_server - file: features/external_toc @@ -110,17 +97,31 @@ parts: sections: - file: external/annotater/README.md - file: basic-features/hypothesis.md - + - caption: Original Jupyter Book and Sphinx Features + chapters: + - file: basic-features/overview.md + sections: + - file: basic-features/jupyterbook.md + - file: basic-features/figures.md + - file: basic-features/equations.md + - file: basic-features/videos.md + - file: basic-features/References.md + - file: basic-features/code.md + - file: basic-features/Code_block_figures + - file: basic-features/badges.md + - file: basic-features/banner + title: Banner or Announcement - caption: Examples chapters: - file: examples/overview.md - - file: examples/book_structure.md - - file: examples/live_code.md - - file: examples/example_gumbel.ipynb - - file: examples/theory_questions.md - - file: examples/example_quiz_interactive.ipynb - - file: examples/coding_theory_widgets.ipynb - - file: examples/parametric_questions.ipynb + sections: + - file: examples/book_structure.md + - file: examples/live_code.md + - file: examples/example_gumbel.ipynb + - file: examples/theory_questions.md + - file: examples/example_quiz_interactive.ipynb + - file: examples/coding_theory_widgets.ipynb + - file: examples/parametric_questions.ipynb - caption: Editing Tools chapters: From f075c648cf7117aa6329e373a5cc38d35761cd61 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 27 Sep 2025 14:02:30 +0200 Subject: [PATCH 05/24] typo --- book/features/favourites.md | 1 - 1 file changed, 1 deletion(-) diff --git a/book/features/favourites.md b/book/features/favourites.md index a855105..4371054 100644 --- a/book/features/favourites.md +++ b/book/features/favourites.md @@ -6,7 +6,6 @@ This page is useful for user type 3-5. {bdg-primary}`Sphinx Extension` -``` ```` # TeachBooks Favourites From e7c48faf2d43660e67f887b7ca917435b1fd37d2 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 27 Sep 2025 14:02:37 +0200 Subject: [PATCH 06/24] Add lnks to general tools --- book/features/overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/features/overview.md b/book/features/overview.md index 38a4857..71f1089 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -15,11 +15,11 @@ 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 <./DBW_intro.html>` +- {bdg-link-light}`GitHub Reusable Action: Deploy Book workflow ` - {bdg-light}`GitHub Template` - {bdg-dark}`Git Workflow` - {bdg-primary}`Sphinx Extension` -- {bdg-primary-line}`Part of TeachBooks Favourites` +- {bdg-link-primary-line}`Part of TeachBooks Favourites <./favourites.html>` - {bdg-danger}`iframe` - {bdg-success}`WebApp` From f26356200638cd1ff28dd8c2a3f1707250b800d2 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 27 Sep 2025 14:50:47 +0200 Subject: [PATCH 07/24] Update --- book/_toc.yml | 2 + book/external/deploy-book-workflow | 2 +- book/features/DBW_intro.md | 40 ----- book/features/overview.md | 6 +- book/features/release_book_online.md | 238 +++++++++++++++++++++++++++ book/features/write_online.md | 62 +++++++ 6 files changed, 306 insertions(+), 44 deletions(-) delete mode 100644 book/features/DBW_intro.md create mode 100644 book/features/release_book_online.md create mode 100644 book/features/write_online.md diff --git a/book/_toc.yml b/book/_toc.yml index 65066cc..289d240 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -49,6 +49,8 @@ parts: - file: features/easy-editing.md sections: - file: external/template/README.md + - file: features/write_online.md + - file: features/release_book_online.md - file: features/draft-release - file: features/pull_request_build.md - file: features/local_server diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow index ceb2bdb..1b35fe8 160000 --- a/book/external/deploy-book-workflow +++ b/book/external/deploy-book-workflow @@ -1 +1 @@ -Subproject commit ceb2bdbe9bed7d7d81ea7342c4bb93044f3879d5 +Subproject commit 1b35fe87afc980274f5731af7b7b74f7df27540c diff --git a/book/features/DBW_intro.md b/book/features/DBW_intro.md deleted file mode 100644 index fba7911..0000000 --- a/book/features/DBW_intro.md +++ /dev/null @@ -1,40 +0,0 @@ - -(deploy-book-workflow-intro)= -## Deploy Book Workflow - -The [Deploy Book Workflow](../external/deploy-book-workflow/README.md) is by default incorporated into any book that has been created using the [TeachBooks Template](../external/template/README.md). We also strongly encourage anyone to consider this tool as an alternative to the "standard" workflow provided by Jupyter Book, as ours automatically builds a different version of your book for every branch in your respository, along with a number of settings that can be used to customize the build process and URL structure of your book(s). This tool is described in more detail on [the Deploy Book Workflow page of this manual](../external/deploy-book-workflow/README.md), and one should note that it influences a number of other aspects of a TeachBook. - -### Related Features - -A list of tools and features that are dependent on, or related to, the Deploy Book Workflow (DBW) is provided here: - -Important for these features: -- [](../external/deploy-book-workflow/README.md): the main DBW page -- [](../external/template/README.md): books created from the Template include DBW by default -- [](./draft-release.md): can be configured directly using the DBW -- [](./update_env.md): behaviors of this tool may influence the DBW -- {ref}`TeachBooks Python Package `: included by default in the DBW -- [](./pull_request_build.md): created to provide DBW-like behavior for PR's from forked repositories -- [](./apa.md): a temporary fix is included in `teachbooks` to enable use in the DBW - -### Book Build Commands - -By default the DBW builds books using the following command: - -``` -teachbooks build book/ -``` - -To use the [Draft-Release Workflow](./draft-release.md) with the Deploy Book Workflow the `BRANCHES_TO_PREPROCESS` variable must be configured for a specific branch, which will then execute the following command: - -``` -teachbooks build --release book/ -``` - -### Environments and Caching - -As described on the [DBW page](../external/deploy-book-workflow/README.md), there is a lot going on "under the hood" with regards to caching of GitHub Action artifacts. This can lead to undesired behavior when using the DBW, especially if package version numbers are not precisely defined. In general we expect the risk of this occurring to be low, as it should only happen when multiple branches are being actively used (new commits on each branch at least once per week), a package from the `requirements.txt` file is updated in the time between creation of two or more branches, and that package _also_ has a significant impact on the book building process. As the Python virtual environment cache is replaced by default if older than one week, the issue should resolve itself within that time frame. - -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). \ No newline at end of file diff --git a/book/features/overview.md b/book/features/overview.md index 71f1089..a095121 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -16,10 +16,10 @@ Additionally, not all features are built and shared in the same way. We do our b - {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-light}`GitHub Template` +- {bdg-link-light}`GitHub Template: TeachBooks Template ` - {bdg-dark}`Git Workflow` - {bdg-primary}`Sphinx Extension` -- {bdg-link-primary-line}`Part of TeachBooks Favourites <./favourites.html>` +- {bdg-link-primary-line}`TeachBooks Favourites <./favourites.html>` - {bdg-danger}`iframe` - {bdg-success}`WebApp` @@ -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](./DBW_intro.md) and [TeachBooks Favourites](./favourites.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](https://teachbooks.io/manual/favourites/external/deploy-book-workflow/README.html) and [TeachBooks Favourites](./favourites.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 new file mode 100644 index 0000000..3171c07 --- /dev/null +++ b/book/features/release_book_online.md @@ -0,0 +1,238 @@ +````{margin} +```{admonition} User types +:class: tip +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 ` + +```` + +# 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/favourites/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. + +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](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` + - 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 banner feature](https://jupyterbook.org/en/stable/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](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. + +#### 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 redirects to the primary branch `main` (status: ✅ `Released`). +> +> ### Aliases +> | Alias ➡️ | Target 🎯 | Link 🔗 | Build status ☑️ | +> | :--- | :--- | :--- | :---- | +> | draft | main | [https://teachbooks.github.io/template/draft](https://teachbooks.github.io/template/draft) | ✅ `Released` | +> +> ### 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 +> ``` +> +> ### Repository configuration variables +> Variables can be set at +> +> ``` +> 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](https://teachbooks.io/manual/favourites/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. + +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](https://teachbooks.io/manual/features/update_env.html). \ No newline at end of file diff --git a/book/features/write_online.md b/book/features/write_online.md new file mode 100644 index 0000000..a50673a --- /dev/null +++ b/book/features/write_online.md @@ -0,0 +1,62 @@ +````{margin} +```{admonition} User types +:class: tip +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 ` + +```` + +# 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/favourites/external/template/README.html) after which they make use of the [Deploy Book Workflow](https://teachbooks.io/manual/favourites/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/favourites/external/deploy-book-workflow/README.html) + +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](https://teachbooks.io/manual/favourites/external/deploy-book-workflow/README.html) +- 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: +- Errors in the build process + +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! From f34b176742c155639cb4745f584de2a0de9f9794 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 27 Sep 2025 14:52:35 +0200 Subject: [PATCH 08/24] WIP --- book/basic-features/overview.md | 2 +- book/examples/overview.md | 6 +----- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md index a37acfb..eb60ffe 100644 --- a/book/basic-features/overview.md +++ b/book/basic-features/overview.md @@ -5,6 +5,6 @@ This section is useful for [user type 3-5](../installation-and-setup/user_types. ``` ```` -# Original Jupyter Book and Sphinx Features +# Overview These pages will provide a list of some common, basic book features which are all available in the original Jupyter book package. Additionally, this page includes also best-practices. diff --git a/book/examples/overview.md b/book/examples/overview.md index 595f6a1..d26cadb 100644 --- a/book/examples/overview.md +++ b/book/examples/overview.md @@ -1,7 +1,3 @@ -# TeachBooks Examples +# Overview This chapter will showcase some TeachBooks making great use of Jupyter Book and TeachBooks features. They can serve as an inspiring starting point for structuring your own TeachBook or just to get an idea of how other teachers and students are using it. Lastly some example pages are shown which combine theory and interactive questions and coding to different degrees. - - - - From be4473842a65135c7f03c0027310ee0ec17ce4ac Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 27 Sep 2025 15:57:36 +0200 Subject: [PATCH 09/24] Add exercise and proof feature documentation Added new pages for Sphinx exercise and Sphinx proof extensions, including installation and usage instructions. Updated references, credits, and feature pages to reflect inclusion in TeachBooks Template and Favourites. Improved consistency of external links and badges, and updated submodules to latest versions. --- book/_toc.yml | 4 +- book/basic-features/overview.md | 2 +- book/credits.md | 5 +- book/external/Download-Link-Replacer | 2 +- book/external/JupyterBook-Patches | 2 +- book/external/Nested-Books | 2 +- book/external/Sphinx-Image-Inverter | 2 +- book/external/Sphinx-Named-Colors | 2 +- book/external/Sphinx-launch-buttons | 2 +- book/external/deploy-book-workflow | 2 +- book/external/sphinx-iframes | 2 +- book/external/teachbooks-sphinx-tippy | 2 +- book/external/template | 2 +- book/features/apa.md | 3 + book/features/draft-release.md | 4 +- book/features/exercise.md | 88 +++++++++++++++++++++++++++ book/features/external_toc.md | 2 +- book/features/favourites.md | 62 ++++++++++++++++--- book/features/live_code.ipynb | 3 +- book/features/local_server.md | 2 +- book/features/overview.md | 6 +- book/features/release_book_online.md | 9 +-- book/features/sphinx-proof.md | 80 ++++++++++++++++++++++++ book/features/teachbooks_intro.md | 3 +- book/features/write_online.md | 11 ++-- book/references.bib | 15 +++++ 26 files changed, 278 insertions(+), 41 deletions(-) create mode 100644 book/features/exercise.md create mode 100644 book/features/sphinx-proof.md diff --git a/book/_toc.yml b/book/_toc.yml index 289d240..09cd976 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -46,9 +46,9 @@ parts: - file: features/teachbooks_intro.md - file: external/deploy-book-workflow/README.md - file: features/favourites.md + - file: external/template/README.md - file: features/easy-editing.md sections: - - file: external/template/README.md - file: features/write_online.md - file: features/release_book_online.md - file: features/draft-release @@ -84,7 +84,9 @@ parts: - file: external/Sphinx-PRIME-applets/README.md - external: https://github.com/TeachBooks/Sphinx-Dropdown-Toggle/blob/main/MANUAL.md - external: "https://github.com/TeachBooks/sphinx-code-examples/blob/main/MANUAL.ipynb" + - file: features/sphinx-proof.md - external: "https://github.com/TeachBooks/Sphinx-NB-Execution-Patterns/blob/Manual/README.md" + - file: features/exercise.md - file: features/visuals.md sections: - external: https://github.com/TeachBooks/Sphinx-Accessibility/blob/manual/README.md diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md index eb60ffe..8790d60 100644 --- a/book/basic-features/overview.md +++ b/book/basic-features/overview.md @@ -7,4 +7,4 @@ This section is useful for [user type 3-5](../installation-and-setup/user_types. # Overview -These pages will provide a list of some common, basic book features which are all available in the original Jupyter book package. Additionally, this page includes also best-practices. +These pages will provide a list of some common, basic book features which are all available in the original Jupyter book package without addition of any additional software. Additionally, this page includes also best-practices. diff --git a/book/credits.md b/book/credits.md index e98ad9c..0fe26e7 100644 --- a/book/credits.md +++ b/book/credits.md @@ -66,6 +66,5 @@ The following pages contain content written by others, part of has been reused a - Page {ref}`copyright_licenses`: {numref}`Figure %s` is included unmodified. Work is provided by Kennisland under a CC0 license. Accessed at [](https://wiki.creativecommons.org/wiki/File:CC_License_Compatibility_Chart.png) on December 17, 2024. - page [](./features/versioning.md): includes text from {cite:t}`semver` that has been modified. Original content licensed under CC BY 3.0. - page [](./features/external_toc.md): includes text from {cite:t}`teachbooks_package` that has been modified. Original content licensed under MIT. - - - +- Page [](./features/exercise.md): includes text from {cite:t}`sphinx-exercise` that has been modified. Original content licensed under MIT license. +- Page [](./features/sphinx-proof.md): includes text from {cite:t}`sphinx-proof` that has been modified. Original content licensed under MIT license. \ No newline at end of file diff --git a/book/external/Download-Link-Replacer b/book/external/Download-Link-Replacer index 10ff656..d6f318f 160000 --- a/book/external/Download-Link-Replacer +++ b/book/external/Download-Link-Replacer @@ -1 +1 @@ -Subproject commit 10ff656dc4b871330dd2271d00d2e8b9a9a57613 +Subproject commit d6f318f52cef2f64f44f195c95ea8a449cf37fe2 diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches index eb505b3..e6e2706 160000 --- a/book/external/JupyterBook-Patches +++ b/book/external/JupyterBook-Patches @@ -1 +1 @@ -Subproject commit eb505b3013d4019e01e448495e3eb1586f573a00 +Subproject commit e6e27067f60a576e3db745361601a1c43bbae5f4 diff --git a/book/external/Nested-Books b/book/external/Nested-Books index 9436769..abb9e70 160000 --- a/book/external/Nested-Books +++ b/book/external/Nested-Books @@ -1 +1 @@ -Subproject commit 943676969d6e42b9c6d9c25d5313d9c0fbceea97 +Subproject commit abb9e707d66ad26e55dfd037835f7f7cc86f2620 diff --git a/book/external/Sphinx-Image-Inverter b/book/external/Sphinx-Image-Inverter index eb21e6a..2351ab0 160000 --- a/book/external/Sphinx-Image-Inverter +++ b/book/external/Sphinx-Image-Inverter @@ -1 +1 @@ -Subproject commit eb21e6a80ed33f0102f9025b9ee983148370d753 +Subproject commit 2351ab0e25a067d6420be078232e5a6e3d9c3168 diff --git a/book/external/Sphinx-Named-Colors b/book/external/Sphinx-Named-Colors index 57ecdd8..c85d64e 160000 --- a/book/external/Sphinx-Named-Colors +++ b/book/external/Sphinx-Named-Colors @@ -1 +1 @@ -Subproject commit 57ecdd887e8bbc32a04aca20e9fc9cb60409b7d0 +Subproject commit c85d64eacbc6b0980530134b08406193f452cf0f diff --git a/book/external/Sphinx-launch-buttons b/book/external/Sphinx-launch-buttons index e6070de..2d85abc 160000 --- a/book/external/Sphinx-launch-buttons +++ b/book/external/Sphinx-launch-buttons @@ -1 +1 @@ -Subproject commit e6070ded6ca77662a3a951893cafe265fa333e5e +Subproject commit 2d85abc35c533a6e756d2c16344fe107be24e427 diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow index 1b35fe8..f983f1e 160000 --- a/book/external/deploy-book-workflow +++ b/book/external/deploy-book-workflow @@ -1 +1 @@ -Subproject commit 1b35fe87afc980274f5731af7b7b74f7df27540c +Subproject commit f983f1e3ec7d99b14fb50631ea48f1f23a15ee76 diff --git a/book/external/sphinx-iframes b/book/external/sphinx-iframes index 583163e..a572035 160000 --- a/book/external/sphinx-iframes +++ b/book/external/sphinx-iframes @@ -1 +1 @@ -Subproject commit 583163ebf970a83ff45d80bb9ace9922d1e1615b +Subproject commit a57203589e1acfaa216a436ea57d17b0b1e76824 diff --git a/book/external/teachbooks-sphinx-tippy b/book/external/teachbooks-sphinx-tippy index e4166e1..4d246da 160000 --- a/book/external/teachbooks-sphinx-tippy +++ b/book/external/teachbooks-sphinx-tippy @@ -1 +1 @@ -Subproject commit e4166e1389ab48ea9059e6576e56d270e66199dd +Subproject commit 4d246da43ec7848928e673ca9223458028d3e473 diff --git a/book/external/template b/book/external/template index 8424c5e..efa0edb 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit 8424c5e1fb5631474250859482b92fc1761c502f +Subproject commit efa0edbb1180081e8ab57ba95eeaece195d786af diff --git a/book/features/apa.md b/book/features/apa.md index 49bdf3f..547e547 100644 --- a/book/features/apa.md +++ b/book/features/apa.md @@ -5,6 +5,9 @@ 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 ` + + ```` (apa)= diff --git a/book/features/draft-release.md b/book/features/draft-release.md index c194753..7e8de38 100644 --- a/book/features/draft-release.md +++ b/book/features/draft-release.md @@ -6,7 +6,9 @@ This page is useful for user type 3-5. ``` -{bdg-secondary}`Python Package: teachbooks <./teachbooks_intro.html>` +{bdg-link-secondary}`Uses TeachBooks package ` +{bdg-link-light}`Included in TeachBooks Template ` +{bdg-link-light}`Supported by Deploy Book workflow ` ```` diff --git a/book/features/exercise.md b/book/features/exercise.md new file mode 100644 index 0000000..9f88cfd --- /dev/null +++ b/book/features/exercise.md @@ -0,0 +1,88 @@ +````{margin} +```{attributiongrey} Attribution +:class: attribution +This page reuses MIT licensed content from {cite:t}`sphinx-exercise`. {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 ` +{bdg-link-primary-line}`Included in TeachBooks Favourites ` +```` + +# Sphinx exercise + +This extensions provides an easy way to add exercises and solutions to your book. It is documented on https://ebp-sphinx-exercise.readthedocs.io/en/latest/. + +TeachBooks has made some small modifications to the original extension, such that it works well with translated books. + +## What does it do? + +This extension defines exercises and solutions as new admonition types: + +```{exercise} +:label: my-exercise + +Recall that $n!$ is read as "$n$ factorial" and defined as +$n! = n \times (n - 1) \times \cdots \times 2 \times 1$. + +There are functions to compute this in various modules, but let's +write our own version as an exercise. + +In particular, write a function `factorial` such that `factorial(n)` returns $n!$ +for any positive integer $n$. +``` + +````{solution} my-exercise +:label: my-solution + +Here's one solution. + +```{code-block} python +def factorial(n): + k = 1 + for i in range(n): + k = k * (i + 1) + return k + +factorial(4) +``` +```` + +More information can be found in the [official documentation](https://ebp-sphinx-exercise.readthedocs.io/en/latest/). + +## 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-exercise @ git+https://github.com/TeachBooks/sphinx-exercise.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-exercise @ git+https://github.com/TeachBooks/sphinx-exercise.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_exercise + . + . + . +``` diff --git a/book/features/external_toc.md b/book/features/external_toc.md index ea770fa..24dd53c 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}`Python Package: teachbooks <./teachbooks_intro.html>` +{bdg-link-secondary}`Uses TeachBooks package ` {bdg-success}`WebApp` ```` diff --git a/book/features/favourites.md b/book/features/favourites.md index 4371054..a0771d2 100644 --- a/book/features/favourites.md +++ b/book/features/favourites.md @@ -5,26 +5,70 @@ This page is useful for user type 3-5. ``` {bdg-primary}`Sphinx Extension` +{bdg-link-light}`Included in TeachBooks Template ` + ```` # TeachBooks Favourites -TeachBooks Favourites is a Sphinx extension which collects all of TeachBooks' favourite features in one place (including tools originally by TeachBooks and from other sources). It is included by default in the [TeachBooks Template](../external/template/README.md) and can be installed independently using `pip install teachbooks-favourites`. The features included are: +TeachBooks Favourites is a Sphinx extension which collects all of TeachBooks' favourite features in one place (including tools originally by TeachBooks and from other sources). It is included by default in the [TeachBooks Template](../external/template/README.md) or can be installed independently. The features included are: - [Sphinx-Thebe from TeachBooks](./live_code.ipynb) -- [Jupyterbook patches](../external/jupyterbook-patches/README.md) -- [Download link replacer](../external/download-link-replacer/README.md) -- [Sphinx image inverter](../external/sphinx-image-inverter/README.md) +- [Jupyterbook patches](../external/JupyterBook-Patches/README.md) +- [Download link replacer](../external/Download-Link-Replacer/README.md) +- [Sphinx image inverter](../external/Sphinx-Image-Inverter/README.md) - [Sphinx iframes](../external/sphinx-iframes/README.md) - [Sphinx exercise (TeachBooks contribution to the original)](https://ebp-sphinx-exercise.readthedocs.io/en/latest/) -- [Teachbooks Sphinx tippy](../external/teachbooks-sphinx-tippy/README.html) -- [Sphinx named colors](../external/sphinx-named-colors/README.md) +- [Teachbooks Sphinx tippy](../external/teachbooks-sphinx-tippy/README.md) +- [Sphinx named colors](../external/Sphinx-Named-Colors/README.md) - [Sphinx dropdown toggle](../_git/github.com_TeachBooks_Sphinx-Dropdown-Toggle/main/MANUAL.md) - [Sphinx proof (TeachBooks contribution to the original)](https://sphinx-proof.readthedocs.io/en/latest/) - [Sphinx code examples](../_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.md) -- [Sphinx accessibility](../_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.html) +- [Sphinx accessibility](../_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.md) - [Sphinx toggle button (TeachBooks contribution to the original)](https://sphinx-togglebutton.readthedocs.io/en/latest/) -- [Notebook execution patterns](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html) +- [Notebook execution patterns](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.md) -All features which are part of TeachBooks Favourites are indicated with {bdg-primary-line}`Part of TeachBooks Favourites`. If you'd like to use specific features, but not the entire TeachBooks Favourites, you can remove this extension and replace it with the individual extensions you want to use. \ No newline at end of file +All features which are part of TeachBooks Favourites are indicated with {bdg-primary-line}`Part of TeachBooks Favourites`. If you'd like to use specific features, but not the entire TeachBooks Favourites, you can remove this extension and replace it with the individual extensions you want to use. + +## Installation +To install TeachBooks-Favourites, follow these steps: + +**Step 1: Install the Package** + +Install the `teachbooks-favourites` package using `pip`: +``` +pip install git+https://github.com/TeachBooks/TeachBooks-Favourites +``` + +**Step 2: Add to `requirements.txt`** + +Make sure that the package is included in your project's `requirements.txt` to track the dependency: +``` +git+https://github.com/TeachBooks/TeachBooks-Favourites +``` + +**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: + - teachbooks_favourites +``` + +## Usage + +For using the various package we refer to the different manuals linked above. + +All extensions are loaded with their default settings. + +## Contribute + +Do you think we missed an extension that should really be included? Let us know by either + +- creating a fork of this repository and submitting a pull request, in which you added the extension to the files + - `README.md` + - `pyproject.toml` + - `src\teachbooks_favourites\__init__.py` +- opening an issue. \ No newline at end of file diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb index 5eb4eed..d0bfa2d 100644 --- a/book/features/live_code.ipynb +++ b/book/features/live_code.ipynb @@ -11,7 +11,8 @@ "```\n", "\n", "{bdg-primary}`Sphinx Extension`\n", - "{bdg-primary-line}`Part of TeachBooks Favourites`\n", + "{bdg-link-light}`Included in TeachBooks Template `\n", + "{bdg-link-primary-line}`Included in TeachBooks Favourites `\n", "\n", "```` \n", "\n", diff --git a/book/features/local_server.md b/book/features/local_server.md index ec21dcc..f3bf55e 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}`Python Package: teachbooks <./teachbooks_intro.html>` +{bdg-link-secondary}`Uses TeachBooks package ` ```` (setup-local-server)= diff --git a/book/features/overview.md b/book/features/overview.md index a095121..81a291f 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 ` +- {bdg-link-light}`GitHub Template: TeachBooks Template ` - {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/favourites/external/deploy-book-workflow/README.html) and [TeachBooks Favourites](./favourites.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](https://teachbooks.io/manual/external/deploy-book-workflow/README.html), [TeachBooks Favourites](./favourites.md) and the TeachBook template 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 3171c07..5f494c5 100644 --- a/book/features/release_book_online.md +++ b/book/features/release_book_online.md @@ -4,8 +4,9 @@ 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-light}`GitHub Reusable Action: Deploy Book workflow ` +{bdg-link-light}`Part of TeachBooks Template ` +{bdg-link-secondary}`Uses TeachBooks package ` ```` @@ -13,7 +14,7 @@ This section is useful for user type 3-5. 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/favourites/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](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. 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). @@ -210,7 +211,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/favourites/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](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. 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). diff --git a/book/features/sphinx-proof.md b/book/features/sphinx-proof.md new file mode 100644 index 0000000..fd0e0ce --- /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 ` +{bdg-link-primary-line}`Included in TeachBooks Favourites ` +```` + +# Sphinx proof + +This extensions provides an easy way to add proofs, theorem, axioms and much more to your book. It is documented on 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. + +## 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](https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html). + +## 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/teachbooks_intro.md b/book/features/teachbooks_intro.md index 89d6b73..e521c54 100644 --- a/book/features/teachbooks_intro.md +++ b/book/features/teachbooks_intro.md @@ -5,12 +5,13 @@ This section is useful for user type 4-5. {bdg-link-secondary}`Python Package: TeachBooks` +{bdg-link-light}`Included in TeachBooks Template ` ``` ```` (teachbooks_package)= -## TeachBooks Python Package +# TeachBooks Python Package The TeachBooks Python package is a collection of tools that are used to enhance the Jupyter Book 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](./deploy-book-workflow.md) and, therefore, any book created from the [TeachBooks Template](../external/template/README.md). This raises two important points: diff --git a/book/features/write_online.md b/book/features/write_online.md index a50673a..3b64812 100644 --- a/book/features/write_online.md +++ b/book/features/write_online.md @@ -4,23 +4,24 @@ 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-light}`Uses Deploy Book workflow ` +{bdg-link-light}`Uses TeachBooks Template ` + ```` # 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/favourites/external/template/README.html) after which they make use of the [Deploy Book Workflow](https://teachbooks.io/manual/favourites/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](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. ## 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/favourites/external/deploy-book-workflow/README.html) +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) 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](https://teachbooks.io/manual/favourites/external/deploy-book-workflow/README.html) +- 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 diff --git a/book/references.bib b/book/references.bib index 61219ae..292c741 100644 --- a/book/references.bib +++ b/book/references.bib @@ -183,3 +183,18 @@ 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.}, +} \ No newline at end of file From 476b2f5fc6659aecb1b31fd925de410681950d4c Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 27 Sep 2025 16:02:42 +0200 Subject: [PATCH 10/24] Update favourites.md --- book/features/favourites.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/features/favourites.md b/book/features/favourites.md index a0771d2..4645ac1 100644 --- a/book/features/favourites.md +++ b/book/features/favourites.md @@ -28,6 +28,7 @@ TeachBooks Favourites is a Sphinx extension which collects all of TeachBooks' fa - [Sphinx accessibility](../_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.md) - [Sphinx toggle button (TeachBooks contribution to the original)](https://sphinx-togglebutton.readthedocs.io/en/latest/) - [Notebook execution patterns](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.md) +- [Sphinx Launch Buttons](../external/Sphinx-launch-buttons/README.md) All features which are part of TeachBooks Favourites are indicated with {bdg-primary-line}`Part of TeachBooks Favourites`. If you'd like to use specific features, but not the entire TeachBooks Favourites, you can remove this extension and replace it with the individual extensions you want to use. From 6fb1d7231f83c1858fa96e3083fed273ad38d533 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 27 Sep 2025 16:03:55 +0200 Subject: [PATCH 11/24] Update feature docs for clarity and links Improved the overview and write_online feature documentation by clarifying the description of the TeachBook template and updating its link. Also refined the summary section to specify error reporting per branch and release location. --- book/features/overview.md | 2 +- book/features/write_online.md | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/book/features/overview.md b/book/features/overview.md index 81a291f..e86e124 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -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 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](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 diff --git a/book/features/write_online.md b/book/features/write_online.md index 3b64812..df0e1cb 100644 --- a/book/features/write_online.md +++ b/book/features/write_online.md @@ -26,8 +26,7 @@ After that, users can start writing and editing their book fully online in the G ## 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: -- Errors in the build process +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: From 3e4eb3e9ec7e3c0dcc9535f64f64b1ec3ed907ca Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 27 Sep 2025 16:05:23 +0200 Subject: [PATCH 12/24] Update deploy-book-workflow --- book/external/deploy-book-workflow | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow index f983f1e..e4e3249 160000 --- a/book/external/deploy-book-workflow +++ b/book/external/deploy-book-workflow @@ -1 +1 @@ -Subproject commit f983f1e3ec7d99b14fb50631ea48f1f23a15ee76 +Subproject commit e4e324964468a21493b92df6771f37b1d0ec69f3 From 1501b290cde246013cdeed55d55332a7d0830cf6 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 27 Sep 2025 16:40:56 +0200 Subject: [PATCH 13/24] fix relative links --- book/external/Download-Link-Replacer | 2 +- book/external/JupyterBook-Patches | 2 +- book/external/Nested-Books | 2 +- book/external/Sphinx-Grasple-public | 2 +- book/external/Sphinx-Image-Inverter | 2 +- book/external/Sphinx-Named-Colors | 2 +- book/external/Sphinx-PRIME-applets | 2 +- book/external/Sphinx-TUDelft-theme | 2 +- book/external/Sphinx-launch-buttons | 2 +- book/external/Useful_python_code | 2 +- book/external/deploy-book-workflow | 2 +- book/external/sphinx-iframes | 2 +- book/external/teachbooks-sphinx-tippy | 2 +- book/external/template | 2 +- book/features/apa.md | 2 +- book/features/draft-release.md | 6 +++--- book/features/exercise.md | 4 ++-- book/features/external_toc.md | 2 +- book/features/favourites.md | 2 +- book/features/live_code.ipynb | 4 ++-- book/features/local_server.md | 2 +- book/features/overview.md | 6 +++--- book/features/release_book_online.md | 18 ++++++++---------- book/features/sphinx-proof.md | 6 +++--- book/features/teachbooks_intro.md | 2 +- book/features/write_online.md | 8 ++++---- 26 files changed, 44 insertions(+), 46 deletions(-) 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 From 6acc6897947bbfbd5af41a685044120fcc04b201 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 27 Sep 2025 16:44:14 +0200 Subject: [PATCH 14/24] fixes --- book/features/favourites.md | 2 +- book/features/teachbooks_intro.md | 4 ++-- book/installation-and-setup/tools.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/book/features/favourites.md b/book/features/favourites.md index a5c4ec8..d747655 100644 --- a/book/features/favourites.md +++ b/book/features/favourites.md @@ -24,7 +24,7 @@ TeachBooks Favourites is a Sphinx extension which collects all of TeachBooks' fa - [Sphinx named colors](../external/Sphinx-Named-Colors/README.md) - [Sphinx dropdown toggle](../_git/github.com_TeachBooks_Sphinx-Dropdown-Toggle/main/MANUAL.md) - [Sphinx proof (TeachBooks contribution to the original)](https://sphinx-proof.readthedocs.io/en/latest/) -- [Sphinx code examples](../_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.md) +- [Sphinx code examples](../_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.ipynb) - [Sphinx accessibility](../_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.md) - [Sphinx toggle button (TeachBooks contribution to the original)](https://sphinx-togglebutton.readthedocs.io/en/latest/) - [Notebook execution patterns](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.md) diff --git a/book/features/teachbooks_intro.md b/book/features/teachbooks_intro.md index bf7d323..d4c86d2 100644 --- a/book/features/teachbooks_intro.md +++ b/book/features/teachbooks_intro.md @@ -13,9 +13,9 @@ This section is useful for user type 4-5. (teachbooks_package)= # TeachBooks Python Package -The TeachBooks Python package is a collection of tools that are used to enhance the Jupyter Book 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](./deploy-book-workflow.md) and, therefore, any book created from the [TeachBooks Template](../external/template/README.md). This raises two important points: +The TeachBooks Python package is a collection of tools that are used to enhance the Jupyter Book 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 {ref}`Deploy Book Workflow `, 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). +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` 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 Manual](https://jupyterbook.org/en/stable/publish/web.html), for example, [this GitHub workflow](https://jupyterbook.org/en/stable/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: diff --git a/book/installation-and-setup/tools.md b/book/installation-and-setup/tools.md index ff81171..0e83db0 100644 --- a/book/installation-and-setup/tools.md +++ b/book/installation-and-setup/tools.md @@ -61,7 +61,7 @@ Here's a table summarizing the information: |--|----------|-------------| | 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) with [DBW](deploy-book-workflow-intro) 🚀 | 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 🚫 | +| 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 ✅ | | 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 👥 👀 | From 0a525a1fb8dec0ba4ad9bb090054d4e7b224a139 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 27 Sep 2025 16:47:00 +0200 Subject: [PATCH 15/24] fixes --- book/external/JupyterBook-Patches | 2 +- book/external/template | 2 +- book/features/overview.md | 2 +- book/features/release_book_online.md | 1 + 4 files changed, 4 insertions(+), 3 deletions(-) diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches index 541f4a3..fe2dd75 160000 --- a/book/external/JupyterBook-Patches +++ b/book/external/JupyterBook-Patches @@ -1 +1 @@ -Subproject commit 541f4a3220f6d8d07ed2909de66a779fd46b23bf +Subproject commit fe2dd75143631d9b3d6501eb0294b94ba3348e3c diff --git a/book/external/template b/book/external/template index ba0733a..ca6fc6a 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit ba0733abc6e31eccd7a478f8dd2a433faf5333f7 +Subproject commit ca6fc6aed3fc852796c5ced256cf3c9946d1e022 diff --git a/book/features/overview.md b/book/features/overview.md index 49d95c1..229071c 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -22,7 +22,7 @@ Additionally, not all features are built and shared in the same way. We do our b - {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. To see examples for these features, go to the [Examples chapter](../examples/overview.md). diff --git a/book/features/release_book_online.md b/book/features/release_book_online.md index f8d7b23..e32c784 100644 --- a/book/features/release_book_online.md +++ b/book/features/release_book_online.md @@ -7,6 +7,7 @@ This section is useful for user type 3-5. {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 From 40cd85952b46f3e3ac4df4e4ea95f92894980105 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 27 Sep 2025 16:51:17 +0200 Subject: [PATCH 16/24] Update template --- book/external/template | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/template b/book/external/template index ca6fc6a..68eb3b3 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit ca6fc6aed3fc852796c5ced256cf3c9946d1e022 +Subproject commit 68eb3b31ccb8d9aa7e36cbb00509e033f7061f54 From cc6cccd366271c869ee252eec90456595fe11c92 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 27 Sep 2025 16:53:28 +0200 Subject: [PATCH 17/24] Typos --- book/external/template | 2 +- book/features/release_book_online.md | 6 +++--- book/features/sphinx-proof.md | 2 +- book/features/teachbooks_intro.md | 2 +- book/features/write_online.md | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/book/external/template b/book/external/template index 68eb3b3..5183c16 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit 68eb3b31ccb8d9aa7e36cbb00509e033f7061f54 +Subproject commit 5183c1616932c85a398e561124cf046288695101 diff --git a/book/features/release_book_online.md b/book/features/release_book_online.md index e32c784..b5dd27c 100644 --- a/book/features/release_book_online.md +++ b/book/features/release_book_online.md @@ -117,7 +117,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](./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.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? @@ -210,7 +210,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](./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.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). @@ -235,4 +235,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](./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.md). \ No newline at end of file diff --git a/book/features/sphinx-proof.md b/book/features/sphinx-proof.md index cc3110d..b65a796 100644 --- a/book/features/sphinx-proof.md +++ b/book/features/sphinx-proof.md @@ -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](../_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.ipynb). ## Installation To use this extenstion, follow these steps: diff --git a/book/features/teachbooks_intro.md b/book/features/teachbooks_intro.md index d4c86d2..878dc0e 100644 --- a/book/features/teachbooks_intro.md +++ b/book/features/teachbooks_intro.md @@ -26,7 +26,7 @@ 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 +## 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) diff --git a/book/features/write_online.md b/book/features/write_online.md index c42ec23..d919dd6 100644 --- a/book/features/write_online.md +++ b/book/features/write_online.md @@ -12,7 +12,7 @@ This section is useful for user type 3-5. # 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.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. +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 From 12e518259744ded26d33a13bb67859c751edf6ea Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Mon, 29 Sep 2025 08:59:46 -0700 Subject: [PATCH 18/24] feature overview page --- book/features/overview.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/book/features/overview.md b/book/features/overview.md index 229071c..c4f8b33 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -4,11 +4,11 @@ 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 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` @@ -22,9 +22,9 @@ Additionally, not all features are built and shared in the same way. We do our b - {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. -To see examples for these features, go to the [Examples chapter](../examples/overview.md). +For each feature, the purpose, installation process and usage is elaborated in the respective sub-sections. -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 +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 From 1cb1b805f861d04af3e233b760a41185abac281e Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Mon, 29 Sep 2025 09:02:19 -0700 Subject: [PATCH 19/24] basic-features/overview update --- book/basic-features/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md index 8790d60..eb75beb 100644 --- a/book/basic-features/overview.md +++ b/book/basic-features/overview.md @@ -7,4 +7,4 @@ This section is useful for [user type 3-5](../installation-and-setup/user_types. # Overview -These pages will provide a list of some common, basic book features which are all available in the original Jupyter book package without addition of any additional software. Additionally, this page includes also best-practices. +These pages itemize some of the more common, basic book features which are all available in the original Jupyter book 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. From 1b4b25461cac54b5dae585bf69ab82d74a6da6a0 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Mon, 29 Sep 2025 09:59:51 -0700 Subject: [PATCH 20/24] fix figmaker text --- book/tools/figmaker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/tools/figmaker.md b/book/tools/figmaker.md index 9e9be86..cdd73c8 100644 --- a/book/tools/figmaker.md +++ b/book/tools/figmaker.md @@ -7,7 +7,7 @@ This section is useful for user type 3-5. # Figure syntax maker -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: +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:
From 2fa1592de43e140b41682785afb47128c0f85cab Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Mon, 29 Sep 2025 10:02:06 -0700 Subject: [PATCH 21/24] scripts page text --- book/helper_code/intro.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/book/helper_code/intro.md b/book/helper_code/intro.md index 6e8f8e7..b06a321 100644 --- a/book/helper_code/intro.md +++ b/book/helper_code/intro.md @@ -1,6 +1,7 @@ # Scripts for automating workflow -This chapter contains a few scripts which can be useful in the book-editing process: +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 jupyter-book 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. From 708f14a6216c5e6c29386d8fc78e66b7816956cc Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Mon, 29 Sep 2025 10:10:00 -0700 Subject: [PATCH 22/24] sphinx exercise text --- book/features/exercise.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/features/exercise.md b/book/features/exercise.md index a798ee2..69d5636 100644 --- a/book/features/exercise.md +++ b/book/features/exercise.md @@ -16,9 +16,9 @@ This section is useful for user type 3-5. # Sphinx exercise -This extensions provides an easy way to add exercises and solutions to your book. It is documented on https://ebp-sphinx-exercise.readthedocs.io/en/latest/. +This extensions provides an easy way to add exercises and solutions to your book. It is created by the Executable Books team and is [documented here](https://ebp-sphinx-exercise.readthedocs.io/en/latest/). -TeachBooks has made some small modifications to the original extension, such that it works well with translated books. +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-exercise](https://github.com/TeachBooks/sphinx-exercise). ## What does it do? From 75221ef14dae075285d306285848431b5ad079df Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Mon, 29 Sep 2025 10:12:09 -0700 Subject: [PATCH 23/24] favourites text --- book/features/favourites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/features/favourites.md b/book/features/favourites.md index d747655..2d71de2 100644 --- a/book/features/favourites.md +++ b/book/features/favourites.md @@ -30,7 +30,7 @@ TeachBooks Favourites is a Sphinx extension which collects all of TeachBooks' fa - [Notebook execution patterns](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.md) - [Sphinx Launch Buttons](../external/Sphinx-launch-buttons/README.md) -All features which are part of TeachBooks Favourites are indicated with {bdg-primary-line}`Part of TeachBooks Favourites`. If you'd like to use specific features, but not the entire TeachBooks Favourites, you can remove this extension and replace it with the individual extensions you want to use. +All features which are part of TeachBooks Favourites are include the following label on their respective pages in this manual: {bdg-primary-line}`Part of TeachBooks Favourites`. If you'd like to use specific features, but not the entire TeachBooks Favourites, you can remove this extension and replace it with the individual extensions you want to use. ## Installation To install TeachBooks-Favourites, follow these steps: From 83256dda73772d08a99aaa8e81b69079af4e768c Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Mon, 29 Sep 2025 10:17:08 -0700 Subject: [PATCH 24/24] sphinx proof text - copy updated format of exercise --- book/features/sphinx-proof.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/features/sphinx-proof.md b/book/features/sphinx-proof.md index b65a796..7627adb 100644 --- a/book/features/sphinx-proof.md +++ b/book/features/sphinx-proof.md @@ -16,9 +16,9 @@ This section is useful for user type 3-5. # Sphinx proof -This extensions provides an easy way to add proofs, theorem, axioms and much more to your book. It is documented on https://sphinx-proof.readthedocs.io/en/latest/. +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. +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?