From f6afbfcd58558f49cc25ba5422c6019810469225 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Sun, 9 Mar 2025 07:28:48 +0100 Subject: [PATCH 01/34] prep note for v0.2.0 --- book/features/external_toc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/features/external_toc.md b/book/features/external_toc.md index c0a2a50..9175ff4 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -15,7 +15,7 @@ When creating books, you might want to reuse material from other people or from Previously, this book feature was implemented using [submodules](../external/Nested-Books/README.md), but the implementation was more difficult to use. Despite this, submodules are still a widely used Git feature that can be very useful for book authors, so check out the [submodules page](../external/Nested-Books/README.md) to learn more, especially if the External TOC tool does not satisfy your needs. Submodules have a few additional features not (yet) implemented using the External TOC. ```{warning} -The External TOC features are not incorporated in the new deploy book workflow yet (this will happen once the workflow specifies `teachbooks>=0.2.0`). +The External TOC features are incorporated in `v0.2.0` of the TeachBooks package. If you are using a TeachBooks Template book or our deploy-book-workflow this will become part of your book builds in GitHub Actions as the cache for your book expires (typically around 1 week after not editing your book branch). We do not expect it to cause issues with existing books, but if it does, you can use the following in your requirements file: `teachbooks<0.2.0`. ``` ## What does it do? From 22eacbfe2738536294f97d98d35c41351a854d0a Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Sun, 9 Mar 2025 07:31:47 +0100 Subject: [PATCH 02/34] typo --- book/features/teachbooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/features/teachbooks.md b/book/features/teachbooks.md index 2561e70..b2780f8 100644 --- a/book/features/teachbooks.md +++ b/book/features/teachbooks.md @@ -8,7 +8,7 @@ This page is useful for user type 3-5. {bdg-secondary}`Python Package: teachbooks` -Often it is necessary to prepare, review and edit materials in parallel to material that is currently being used by students, or another target audience. This workflow enables an author to easily maintain separate versions of a book without having to repeatedly comment out lines of a table of contents or page when building different versions. It is also easy to implement in CI/CD settings (it is already implemented in the {ref}Deploy Book Workflow `, which builds our TeachBooks). +Often it is necessary to prepare, review and edit materials in parallel to material that is currently being used by students, or another target audience. This workflow enables an author to easily maintain separate versions of a book without having to repeatedly comment out lines of a table of contents or page when building different versions. It is also easy to implement in CI/CD settings (it is already implemented in the {ref}`Deploy Book Workflow `, which builds our TeachBooks). ```{admonition} Why is this useful? :class: tip From a25cdfe4c5de3f8a8d2b3b21e23601b3d428c08a Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Sun, 9 Mar 2025 07:31:57 +0100 Subject: [PATCH 03/34] filename change --- book/_toc.yml | 2 +- book/features/{teachbooks.md => draft-release.md} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename book/features/{teachbooks.md => draft-release.md} (100%) diff --git a/book/_toc.yml b/book/_toc.yml index 0219d36..223bb61 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -57,7 +57,7 @@ parts: - file: features/easy-editing.md sections: - file: external/template/README.md - - file: features/teachbooks + - file: features/draft-release - file: external/deploy-book-workflow/README.md - file: features/pull_request_build.md - file: features/local_server diff --git a/book/features/teachbooks.md b/book/features/draft-release.md similarity index 100% rename from book/features/teachbooks.md rename to book/features/draft-release.md From 53fdeda76078ac204f91e0899cb524a64ca2ffb2 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Sun, 9 Mar 2025 07:45:36 +0100 Subject: [PATCH 04/34] add draft-release page ref --- book/features/draft-release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/features/draft-release.md b/book/features/draft-release.md index b2780f8..9b62b51 100644 --- a/book/features/draft-release.md +++ b/book/features/draft-release.md @@ -1,4 +1,4 @@ -(teachbooks-package)= +(draft-release)= # Draft-Release Workflow ```{admonition} User types From e5426cc81e8f878da913146ea88fd453bc3f97f2 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Sat, 22 Mar 2025 07:26:52 +0100 Subject: [PATCH 05/34] small notes sphinx-extrensions page --- book/features/sphinx_extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/features/sphinx_extensions.md b/book/features/sphinx_extensions.md index fa53945..f74ed20 100644 --- a/book/features/sphinx_extensions.md +++ b/book/features/sphinx_extensions.md @@ -5,4 +5,4 @@ This section is useful for user type 4-5. ``` -This sections includes the features developed by TeachBooks which add functionality to the book. Most of them are implemented as sphinx extensions, which are plugins developed for the Sphinx documentation ecosystem (which Jupyter Book is built upon). They extend or modify Sphinx’s capabilities. Since Sphinx extensions are not an integral part of jupyter-book, as opposed to original jupyter-book features, they must be installed and configured explicitly, for example in the `_config.yml` file. \ No newline at end of file +This sections includes the features developed by TeachBooks which add functionality to the book. Most of them are implemented as sphinx extensions {bdg-primary}`Sphinx Extension`, which are plugins developed for the Sphinx documentation ecosystem (which Jupyter Book is built upon). They extend or modify Sphinx’s capabilities. Since Sphinx extensions are not an integral part of jupyter-book, as opposed to original jupyter-book features, they must be installed and configured explicitly, for example in the `_config.yml` and `requirements.txt` files. \ No newline at end of file From 40c9f63cb94b5c7abdfc80a98e6342f70545e43a Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Sat, 22 Mar 2025 17:10:41 +0100 Subject: [PATCH 06/34] WIP --- book/_toc.yml | 1 + book/features/draft-release.md | 2 +- book/features/external_toc.md | 2 +- book/features/local_server.md | 2 +- book/features/overview.md | 2 +- book/features/teachbooks.md | 28 ++++++++++++++++++++++++++++ 6 files changed, 33 insertions(+), 4 deletions(-) create mode 100644 book/features/teachbooks.md diff --git a/book/_toc.yml b/book/_toc.yml index 223bb61..e04ffc8 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -98,6 +98,7 @@ parts: sections: - file: external/annotater/README.md - file: basic-features/hypothesis.md + - file: features/teachbooks - caption: Examples chapters: diff --git a/book/features/draft-release.md b/book/features/draft-release.md index 9b62b51..8e36ea5 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-secondary}`Python Package: teachbooks` +{bdg-link-secondary}`Python Package: teachbooks <./teachbooks.html>` Often it is necessary to prepare, review and edit materials in parallel to material that is currently being used by students, or another target audience. This workflow enables an author to easily maintain separate versions of a book without having to repeatedly comment out lines of a table of contents or page when building different versions. It is also easy to implement in CI/CD settings (it is already implemented in the {ref}`Deploy Book Workflow `, which builds our TeachBooks). diff --git a/book/features/external_toc.md b/book/features/external_toc.md index 9175ff4..30a460a 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -6,7 +6,7 @@ This page is useful for user type 3-5. ``` -{bdg-secondary}`Python Package: teachbooks` +{bdg-link-secondary}`Python Package: teachbooks <./teachbooks.html>` ## Introduction diff --git a/book/features/local_server.md b/book/features/local_server.md index fcdbbc1..8539b0b 100644 --- a/book/features/local_server.md +++ b/book/features/local_server.md @@ -6,7 +6,7 @@ This section is useful for user type 4-5. ``` -{bdg-secondary}`Python Package: teachbooks` +{bdg-link-secondary}`Python Package: teachbooks <./teachbooks.html>` Perhaps you have already noticed that when building a book and testing it locally on your computer, some features do not work the way you expect, or worse---do not work at all! This is because many interactive features rely on browser functionality to work properly, for example: Grasple/H5p iframe exercises, Sphinx-Thebe Python interactivity and HTML/Javascript elements. Although the website is _static_ (i.e., there is no code running on a webserver that generates the content), modern web browsers have their own internal computing environments that run processes to deliver the rich content we desire in our books. diff --git a/book/features/overview.md b/book/features/overview.md index 4a6cd20..e59742d 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -13,7 +13,7 @@ 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-secondary}`Python Package: teachbooks` +- {bdg-link-secondary}`Python Package: teachbooks <./teachbooks.html>` - {bdg-light}`GitHub Reusable Action` - {bdg-light}`GitHub Template` - {bdg-dark}`Git Workflow` diff --git a/book/features/teachbooks.md b/book/features/teachbooks.md new file mode 100644 index 0000000..9a7d127 --- /dev/null +++ b/book/features/teachbooks.md @@ -0,0 +1,28 @@ +# TeachBooks Python Package + +```{admonition} User types +:class: tip +This section is useful for user type 4-5. +``` + +{bdg-secondary}`Python Package: teachbooks` + +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](./teachbooks-template.md). This raises two important points: + +1. If you are a book user using the [TeachBooks Template](./teachbooks-template.md) or the [Deploy Book Workflow](./deploy-book-workflow.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`. It adds a few commands to the CLI (e.g., `serve`), but otherwise is meant to be used instead of the `jupyter-book` commands. It is conventionally used in an identical way: + +``` +teachbooks build book +``` + +## 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: read more here +- External Contents: +- Local Server: + +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 2229dd7a7b1ad9abc612bd1c31c9d05af84b63a5 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 21:32:39 +0100 Subject: [PATCH 07/34] Update teachbooks.md --- book/features/teachbooks.md | 43 +++++++++++++------------------------ 1 file changed, 15 insertions(+), 28 deletions(-) diff --git a/book/features/teachbooks.md b/book/features/teachbooks.md index 9a7d127..7cb8b65 100644 --- a/book/features/teachbooks.md +++ b/book/features/teachbooks.md @@ -1,28 +1,15 @@ -# TeachBooks Python Package - -```{admonition} User types -:class: tip -This section is useful for user type 4-5. -``` - -{bdg-secondary}`Python Package: teachbooks` - -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](./teachbooks-template.md). This raises two important points: - -1. If you are a book user using the [TeachBooks Template](./teachbooks-template.md) or the [Deploy Book Workflow](./deploy-book-workflow.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`. It adds a few commands to the CLI (e.g., `serve`), but otherwise is meant to be used instead of the `jupyter-book` commands. It is conventionally used in an identical way: - -``` -teachbooks build book -``` - -## 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: read more here -- External Contents: -- Local Server: - -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 + + + + + + + Page Redirection + + + + If you are not redirected automatically, follow this link to example. + + From 92b026d9053ab140631ca30ae8287615db15488a Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 21:34:06 +0100 Subject: [PATCH 08/34] Update overview.md --- book/features/overview.md | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/book/features/overview.md b/book/features/overview.md index e59742d..78dc3e1 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -22,4 +22,32 @@ Additionally, not all features are built and shared in the same way. We do our b 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). \ No newline at end of file +To see examples for these features, go to the [Examples chapter](../examples/overview.md). + +(teachbooks_package)= +## TeachBooks Python Package + +```{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](./teachbooks-template.md). This raises two important points: + +1. If you are a book user using the [TeachBooks Template](./teachbooks-template.md) or the [Deploy Book Workflow](./deploy-book-workflow.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`. It adds a few commands to the CLI (e.g., `serve`), but otherwise is meant to be used instead of the `jupyter-book` commands. It is conventionally used in an identical way: + +``` +teachbooks build book +``` + +### 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: read more here +- External Contents: +- Local Server: + +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. From 50131ee8479bb832b9fefc5255b66ad8d5675f3d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 21:37:47 +0100 Subject: [PATCH 09/34] Update teachbooks.md --- book/features/teachbooks.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/features/teachbooks.md b/book/features/teachbooks.md index 7cb8b65..1443ae7 100644 --- a/book/features/teachbooks.md +++ b/book/features/teachbooks.md @@ -1,3 +1,4 @@ +# TeachBooks Python Package From de6ba9e0fade30ae24e0716e52dd126159d2ce29 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 21:42:56 +0100 Subject: [PATCH 10/34] Update teachbooks.md --- book/features/teachbooks.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/features/teachbooks.md b/book/features/teachbooks.md index 1443ae7..8e652a4 100644 --- a/book/features/teachbooks.md +++ b/book/features/teachbooks.md @@ -3,14 +3,14 @@ - + Page Redirection - If you are not redirected automatically, follow this link to example. + If you are not redirected automatically, follow this link to example. From b78aa6ac84cfaee90e12557187a75525b6eb83ba Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 21:46:25 +0100 Subject: [PATCH 11/34] Update teachbooks.md --- book/features/teachbooks.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/features/teachbooks.md b/book/features/teachbooks.md index 8e652a4..2683330 100644 --- a/book/features/teachbooks.md +++ b/book/features/teachbooks.md @@ -3,14 +3,14 @@ - + Page Redirection - If you are not redirected automatically, follow this link to example. + If you are not redirected automatically, follow this link to example. From d572a0fd644ae61d38ffa3ab971d56383a684f25 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 21:49:37 +0100 Subject: [PATCH 12/34] Update teachbooks.md --- book/features/teachbooks.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/features/teachbooks.md b/book/features/teachbooks.md index 2683330..b60553d 100644 --- a/book/features/teachbooks.md +++ b/book/features/teachbooks.md @@ -3,14 +3,14 @@ - + Page Redirection - If you are not redirected automatically, follow this link to example. + If you are not redirected automatically, follow this link to example. From 9b82c05b553100ec795e32d18e0a2ae847868b03 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 21:50:40 +0100 Subject: [PATCH 13/34] Update overview.md --- book/features/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/features/overview.md b/book/features/overview.md index 78dc3e1..aa8c7a4 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -13,7 +13,7 @@ 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 <./teachbooks.html>` +- {bdg-link-secondary}`Python Package: teachbooks <./overview.html#teachbooks-python-package>` - {bdg-light}`GitHub Reusable Action` - {bdg-light}`GitHub Template` - {bdg-dark}`Git Workflow` From 3f77301b61e9ee4d01e9274a7f47ddad77b431f0 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 21:57:21 +0100 Subject: [PATCH 14/34] Delete book/features/teachbooks.md --- book/features/teachbooks.md | 16 ---------------- 1 file changed, 16 deletions(-) delete mode 100644 book/features/teachbooks.md diff --git a/book/features/teachbooks.md b/book/features/teachbooks.md deleted file mode 100644 index b60553d..0000000 --- a/book/features/teachbooks.md +++ /dev/null @@ -1,16 +0,0 @@ -# TeachBooks Python Package - - - - - - - Page Redirection - - - - If you are not redirected automatically, follow this link to example. - - From ef4b94c9ce1a0493866fec0b4292f9f5c9297925 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 21:58:45 +0100 Subject: [PATCH 15/34] Update _toc.yml --- book/_toc.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/book/_toc.yml b/book/_toc.yml index e04ffc8..28e8a80 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -98,7 +98,6 @@ parts: sections: - file: external/annotater/README.md - file: basic-features/hypothesis.md - - file: features/teachbooks - caption: Examples chapters: @@ -127,4 +126,4 @@ parts: - file: references.md - file: credits - file: changelog - - file: contact \ No newline at end of file + - file: contact From 05f0045b400cd0573f5bb87545acce472a8a09ac Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 21:59:52 +0100 Subject: [PATCH 16/34] Update draft-release.md --- book/features/draft-release.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/features/draft-release.md b/book/features/draft-release.md index 8e36ea5..3666efa 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 <./teachbooks.html>` +{bdg-link-secondary}`Python Package: teachbooks <./overview#teachBooks-python-package>` Often it is necessary to prepare, review and edit materials in parallel to material that is currently being used by students, or another target audience. This workflow enables an author to easily maintain separate versions of a book without having to repeatedly comment out lines of a table of contents or page when building different versions. It is also easy to implement in CI/CD settings (it is already implemented in the {ref}`Deploy Book Workflow `, which builds our TeachBooks). @@ -70,4 +70,4 @@ We recommend you install this in an environment that is specifically dedicated f The package is a CLI tool that primarily provides a wrapper around the Jupyter Book package which is used for pre- and postprocessing. In this case "wrapper" refers to the CLI usage: CLI commands generally invoke `jupyter-book` commands internally; the `jupyter-book` package is _not_ distributed within the `teachbooks` package. -The source code and function of the package will eventually be documented on a Sphinx-built website ([teachbooks.io/TeachBooks/](https://teachbooks.io/TeachBooks/)), however, this is currently still under construction. \ No newline at end of file +The source code and function of the package will eventually be documented on a Sphinx-built website ([teachbooks.io/TeachBooks/](https://teachbooks.io/TeachBooks/)), however, this is currently still under construction. From b33bd13be5bf62ae621819aa941721e9ed85c8f9 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 22:00:14 +0100 Subject: [PATCH 17/34] Update external_toc.md --- book/features/external_toc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/features/external_toc.md b/book/features/external_toc.md index 30a460a..46fa6cb 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -6,7 +6,7 @@ This page is useful for user type 3-5. ``` -{bdg-link-secondary}`Python Package: teachbooks <./teachbooks.html>` +{bdg-link-secondary}`Python Package: teachbooks <./overview#teachBooks-python-package>` ## Introduction From fac95545dbbec7d8953f368884cfdc2eeb01bb55 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 22:00:38 +0100 Subject: [PATCH 18/34] Update local_server.md --- book/features/local_server.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/features/local_server.md b/book/features/local_server.md index 8539b0b..cd90463 100644 --- a/book/features/local_server.md +++ b/book/features/local_server.md @@ -6,7 +6,7 @@ This section is useful for user type 4-5. ``` -{bdg-link-secondary}`Python Package: teachbooks <./teachbooks.html>` +{bdg-link-secondary}`Python Package: teachbooks <./overview#teachBooks-python-package>` Perhaps you have already noticed that when building a book and testing it locally on your computer, some features do not work the way you expect, or worse---do not work at all! This is because many interactive features rely on browser functionality to work properly, for example: Grasple/H5p iframe exercises, Sphinx-Thebe Python interactivity and HTML/Javascript elements. Although the website is _static_ (i.e., there is no code running on a webserver that generates the content), modern web browsers have their own internal computing environments that run processes to deliver the rich content we desire in our books. @@ -138,4 +138,4 @@ A Windows-specific command for the CMD prompt or Powershell is: ``` TASKKILL /IM python.exe /F -``` \ No newline at end of file +``` From e1f25a8a48e6d1341bf6c28326db8e07638afc7e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 22:04:14 +0100 Subject: [PATCH 19/34] Update draft-release.md --- book/features/draft-release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/features/draft-release.md b/book/features/draft-release.md index 3666efa..fb7f3db 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-link-secondary}`Python Package: teachbooks <./overview#teachbooks-python-package>` Often it is necessary to prepare, review and edit materials in parallel to material that is currently being used by students, or another target audience. This workflow enables an author to easily maintain separate versions of a book without having to repeatedly comment out lines of a table of contents or page when building different versions. It is also easy to implement in CI/CD settings (it is already implemented in the {ref}`Deploy Book Workflow `, which builds our TeachBooks). From 55b68627bb5c5379a55d11c1ea4f51640341afdb Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 22:04:44 +0100 Subject: [PATCH 20/34] Update external_toc.md --- book/features/external_toc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/features/external_toc.md b/book/features/external_toc.md index 46fa6cb..c80c8c8 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.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-link-secondary}`Python Package: teachbooks <./overview#teachbooks-python-package>` ## Introduction From 62ddb348f6161784012481bf232ca24325191107 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 22:05:08 +0100 Subject: [PATCH 21/34] Update local_server.md --- book/features/local_server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/features/local_server.md b/book/features/local_server.md index cd90463..2efb418 100644 --- a/book/features/local_server.md +++ b/book/features/local_server.md @@ -6,7 +6,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 <./overview#teachbooks-python-package>` Perhaps you have already noticed that when building a book and testing it locally on your computer, some features do not work the way you expect, or worse---do not work at all! This is because many interactive features rely on browser functionality to work properly, for example: Grasple/H5p iframe exercises, Sphinx-Thebe Python interactivity and HTML/Javascript elements. Although the website is _static_ (i.e., there is no code running on a webserver that generates the content), modern web browsers have their own internal computing environments that run processes to deliver the rich content we desire in our books. From 4cc865170afadebf65ab2679bb21e71705ca97a0 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Wed, 2 Apr 2025 05:43:32 +0200 Subject: [PATCH 22/34] update teachbooks text on overview --- book/features/overview.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/features/overview.md b/book/features/overview.md index aa8c7a4..0bfc8ce 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -37,7 +37,7 @@ The TeachBooks Python package is a collection of tools that are used to enhance 1. If you are a book user using the [TeachBooks Template](./teachbooks-template.md) or the [Deploy Book Workflow](./deploy-book-workflow.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`. It adds a few commands to the CLI (e.g., `serve`), but otherwise is meant to be used instead of the `jupyter-book` commands. It is conventionally used in an identical way: +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 @@ -46,8 +46,8 @@ teachbooks build book ### 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: read more here -- External Contents: -- Local Server: +- [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. From 6d3e647a94ca63bf1442cfad8ada0fa9f6d808a1 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Wed, 2 Apr 2025 06:14:24 +0200 Subject: [PATCH 23/34] update updated_env text for clarity --- book/features/update_env.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/book/features/update_env.md b/book/features/update_env.md index 8f7000c..ca661ec 100644 --- a/book/features/update_env.md +++ b/book/features/update_env.md @@ -9,18 +9,21 @@ This page is useful for user type 4-5. # Auto-updating packages -When building your book, your making use of packages: the teachbooks and jupyterbook packages themselves, but also packages for extensions. These are regularly updated, while those updates are not necessarily taken into your book. This is all defined in the `requirements.txt` file, which is provided as part of the [template](../external/template/README.md). There are three options: -1. `requirements.txt` only contains names of packages like: `download_link_replacer`. In that case, your [deploy-book-workflow](../external/deploy-book-workflow/README.md) will take the most up-to-date version when making your book website once a week (as the chache will be cleared once a week). This might lead to unexpected changes when new version come out, although new version are in general backwards compatible. +When building your book, you are making use of various Python packages: the `teachbooks` and `jupyter-book` packages themselves, but also packages for extensions. These are regularly updated, however, those updates are not necessarily incorporated into your book automatically. The list of packages and their versions are defined in the `requirements.txt` file, which is provided as part of the [template](../external/template/README.md). Consider the following three options for how packages can be specified: +1. `requirements.txt` only contains names of packages like: `download_link_replacer`. In that case, your [deploy-book-workflow](../external/deploy-book-workflow/README.md) will take the most up-to-date version when making your book website once a week (as the chache will be cleared once a week). This might lead to unexpected changes when a new version has been released (although new versions will generally be backwards compatible). 1. `requirements.txt` contains names of packages with a specified version like: `download_link_replacer==1.0.4`. In that case, your [deploy-book-workflow](../external/deploy-book-workflow/README.md) always uses that specific version. In doing so, you'll never get a new update unless you explicitly adapt the version in `requirements.txt`. If you'd like to get notified for updates, you might consider using GitHub's Dependabot. -1. A combination of 1. and 2.: In that case (once a week at most) you will receive new versions for only the unfixed packages, no updates for the fixed versions. In this case you can also use GitHub's Dependabot. +1. A combination of 1. and 2.: In that case (once a week at most) you will receive new versions for only the unfixed packages, no updates for the fixed versions. + +For the case of specified versions, you can use GitHub's Dependabot to notify you that a new version is available _and_ to automatically set up a Pull Request to update your book with the new version. ## Notifications updated packages with Dependabot -Dependabot checks the specified version of packages in your `requirements.txt` file and opens a branch and pull requests whenever there's an update available for that package. Note that package without a fixed version are ignored by Dependabot. +Dependabot checks the specified version of packages in your `requirements.txt` file and, if a new version is found, will create a new branch, update the `requirements.txt` file and open a Pull Request whenever there's an update available for that package. Note that packages without a fixed version are ignored by Dependabot. To activate this feature: 1. Specify version for all packages you want to be notified on in your `requirements.txt` file. See [`requirements.txt`](https://github.com/TeachBooks/manual/blob/release/requirements.txt) of this manual as an example 1. In the `.github/` directory, add a file named `dependabot.yml` with the following content (note that sphinx-thebe (used in [python live coding](./live_code.ipynb)) and docutils (using in [APA referencing](./apa.md)) are ignored because these require a very specific version to work): + ```yaml version: 2 updates: @@ -35,11 +38,12 @@ updates: - dependency-name: "docutils" ``` -This will check every sunday around midnight (UTC) whether any of the fixed-version packages are updated. If so, several things will happen: -1. A new branch starting with _dependabot_ will be created in the repository and any relevant workflows will be triggered. -1. A _pull request_ will be created to pull the new branch into the _default_ branch. This pull request must be manually reviewed and merged. Afterwards the _dependabot_ branch can be deleted (automatically). +This check will run every Sunday around midnight (UTC) whether any of the fixed-version packages are updated. If so, several things will happen: +1. A new branch is created with a name that begins with `dependabot...` in the repository +1. A commit is made updating `requirements.txt` (e.g., `jupyterbook_patches==1.4.2` is changed to `jupyterbook_patches==1.4.4`) +1. A _pull request_ will be created to merge the new branch into the _default_ branch. This pull request must be manually reviewed and merged. Afterwards the _dependabot_ branch can be deleted (automatically). -If the workflow `call-deploy-book` is used, and you don't want the _dependabot_ branches to be built and deployed (and all other branches you do want), you can achieve this by adding the next to the file `call-deploy-book.yml`: +Note that these activities will occur automatically and may trigger other workflows in your repository (for example, the building of a book on another branch). If the workflow `call-deploy-book` is used, and you don't want the _dependabot_ branches to be built and deployed (and all other branches you do want), you can achieve this by adding the following text to the file `call-deploy-book.yml`: ```yaml on: From 6f3294e66fc9573c49bdd4085d03cbc7b1a68afa Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Wed, 2 Apr 2025 06:51:15 +0200 Subject: [PATCH 24/34] overview update --- book/features/overview.md | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/book/features/overview.md b/book/features/overview.md index a13fbda..c048368 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -25,6 +25,8 @@ 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. + (teachbooks_package)= ## TeachBooks Python Package @@ -33,9 +35,9 @@ To see examples for these features, go to the [Examples chapter](../examples/ove 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](./teachbooks-template.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](./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](./teachbooks-template.md) or the [Deploy Book Workflow](./deploy-book-workflow.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). +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: @@ -52,3 +54,25 @@ Items in the list here are currently implemented in the TeachBooks package and d - [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 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 + +### Environmnets and Caching + +_Work in progress._ \ No newline at end of file From bc23d90cccfbde4469e94c83daa48481dead1315 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Wed, 2 Apr 2025 14:03:37 +0200 Subject: [PATCH 25/34] meaningless bump: should reuse cache but still check dependencies --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 6ec7aee..832a3c7 100644 --- a/README.md +++ b/README.md @@ -20,3 +20,4 @@ The released book can be found on on https://teachbooks.io/manual. This page sho Some parts of this book are taken from other sources in the form of submodules (linked in the folder [book/external](book/external)). To contribute to those pages, contribute to the source repository directly with a fork and merge/pull request. If you intent to clone this book including its submodules, clone using: `git clone --recurse-submodules git@github.com:TeachBooks/manual.git` Happy book building! + From 31d96bd25bdafa85cb9fa3fde56412179cab3681 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Wed, 2 Apr 2025 14:11:37 +0200 Subject: [PATCH 26/34] meaningless change to book: should result in new venv created, even though requirements not changed --- book/intro.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/intro.md b/book/intro.md index f5784e3..a918590 100644 --- a/book/intro.md +++ b/book/intro.md @@ -16,4 +16,4 @@ There are several "parts" to the manual: - The **Features** part describes a suite of tools that are useful for teachers, many of which are developed by TeachBooks contributors specifically for use in education. Many of these tools are illustrated in the **Examples**. - A few special tools are included in the **Editing Tools** that are useful when writing content. -See the final chapters of this book (under **Miscellaneous**) for additional information about References, Credits, etc. +See the final chapters of this book (under **Miscellaneous**) for additional information about References, Credits, etc. \ No newline at end of file From 374bd794d27672be57cd6d74694bede934233b9b Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Wed, 2 Apr 2025 14:20:01 +0200 Subject: [PATCH 27/34] last check didnt work. this one will confirm that requirements.txt change makes new venv created --- requirements.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/requirements.txt b/requirements.txt index 0451ff4..7edb00d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -12,5 +12,4 @@ sphinx-prime-applets == 1.0.2 git+https://github.com/TeachBooks/Sphinx-Thebe -docutils==0.17.1 - +docutils==0.17.1 \ No newline at end of file From a6045e7d1efe1c0258c49bb24ab43f059a947d5e Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Fri, 4 Apr 2025 16:49:13 +0200 Subject: [PATCH 28/34] DBW and packages note ready --- book/features/overview.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/book/features/overview.md b/book/features/overview.md index c048368..dbfc3c8 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -66,7 +66,7 @@ A list of tools and features that are dependent on, or related to, the Deploy Bo Important for these features: - [](../external/deploy-book-workflow/README.md): the main DBW page -- [](../external/template/README.md): books created from Template include DBW by default +- [](../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 @@ -75,4 +75,6 @@ Important for these features: ### Environmnets and Caching -_Work in progress._ \ No newline at end of file +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. As this would mostly occur when multiple branches are being actively used (new commits on each branch at least once per week), and a package from the `requirements.txt` file is updated in the time between creation of two or more branches, which _also_ has a significant impact on the book building process...we except this to have a relatively low risk of occurring. + +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. \ No newline at end of file From a9d7fab8b44899493cbb5ca0d10fc849b99e2a25 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Fri, 4 Apr 2025 16:54:34 +0200 Subject: [PATCH 29/34] remove warning on external toc page --- book/features/external_toc.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/book/features/external_toc.md b/book/features/external_toc.md index 1df92ea..b2287e8 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -16,9 +16,7 @@ When creating books, you might want to reuse material from other people or from Previously, this book feature was implemented using [submodules](../external/Nested-Books/README.md), but the implementation was more difficult to use. Despite this, submodules are still a widely used Git feature that can be very useful for book authors, so check out the [submodules page](../external/Nested-Books/README.md) to learn more, especially if the External TOC tool does not satisfy your needs. Submodules have a few additional features not (yet) implemented using the External TOC. -```{warning} -The External TOC features are incorporated in `v0.2.0` of the TeachBooks package. If you are using a TeachBooks Template book or our deploy-book-workflow this will become part of your book builds in GitHub Actions as the cache for your book expires (typically around 1 week after not editing your book branch). We do not expect it to cause issues with existing books, but if it does, you can use the following in your requirements file: `teachbooks<0.2.0`. -``` +The External TOC features are incorporated in the teachbooks package starting with version `0.2.0`. ## What does it do? From b7352c2d6ac137e95adc78ed9fce85f377ac50f8 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Fri, 4 Apr 2025 16:54:45 +0200 Subject: [PATCH 30/34] add note about deleting cache --- book/features/overview.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/book/features/overview.md b/book/features/overview.md index dbfc3c8..2fa3ce8 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -77,4 +77,6 @@ Important for these features: 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. As this would mostly occur when multiple branches are being actively used (new commits on each branch at least once per week), and a package from the `requirements.txt` file is updated in the time between creation of two or more branches, which _also_ has a significant impact on the book building process...we except this to have a relatively low risk of occurring. -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. \ No newline at end of file +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 From e5bed622e03a20f11bb988cb2c9761608137a3df Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 4 Apr 2025 17:13:32 +0200 Subject: [PATCH 31/34] remove duplicate text --- book/features/draft-release.md | 1 - 1 file changed, 1 deletion(-) diff --git a/book/features/draft-release.md b/book/features/draft-release.md index adfaed7..88b61be 100644 --- a/book/features/draft-release.md +++ b/book/features/draft-release.md @@ -9,7 +9,6 @@ This page is useful for user type 3-5. {bdg-link-secondary}`Python Package: teachbooks <./overview#teachbooks-python-package>` -Often it is necessary to prepare, review and edit materials in parallel to material that is currently being used by students, or another target audience. This workflow enables an author to easily maintain separate versions of a book without having to repeatedly comment out lines of a table of contents or page when building different versions. It is also easy to implement in CI/CD settings (it is already implemented in the {ref}`Deploy Book Workflow `, which builds our TeachBooks). ```` (teachbooks-package)= From f6f8164f9b89721b67fd12fc2413d26824617ab7 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 4 Apr 2025 17:14:51 +0200 Subject: [PATCH 32/34] User type in margin --- book/features/overview.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/book/features/overview.md b/book/features/overview.md index 2fa3ce8..9b43a92 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -30,10 +30,12 @@ As the TeachBooks Python Package and the Deploy Book Workflow are important tool (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: From 4dfffb1206359aa5e9554466c55cb1c7de0d4e2d Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Sat, 5 Apr 2025 06:03:52 +0200 Subject: [PATCH 33/34] clarify that an venv issue will be 1 week max --- book/features/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/features/overview.md b/book/features/overview.md index 9b43a92..3b442fb 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -77,7 +77,7 @@ Important for these features: ### Environmnets 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. As this would mostly occur when multiple branches are being actively used (new commits on each branch at least once per week), and a package from the `requirements.txt` file is updated in the time between creation of two or more branches, which _also_ has a significant impact on the book building process...we except this to have a relatively low risk of occurring. +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. From b3183b8e858ad338438a0c503bd5b481948186c0 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Sat, 5 Apr 2025 06:12:07 +0200 Subject: [PATCH 34/34] note build commands --- book/features/overview.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/book/features/overview.md b/book/features/overview.md index 3b442fb..49c62c5 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -48,6 +48,8 @@ For those who wish to use the package, it is available on [PyPI](https://pypi.or 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: @@ -75,6 +77,18 @@ Important for these features: - [](./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/ +``` + ### Environmnets 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.