Merge pull request #131 from TeachBooks/external-content-teachbooks-v0.2.0

rlanzafame · web-flow · commit 96b5daaa964f · 2025-04-07T15:50:38.000+02:00
Prepare for teachbooks v0.2.0 https://github.com/TeachBooks/TeachBooks/releases/tag/v0.2.0
diff --git 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!
+
diff --git 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
@@ -128,4 +128,4 @@ parts:
     - file: references.md
     - file: credits
     - file: changelog
-    - file: contact
+    - file: contact
diff --git a/book/features/draft-release.md b/book/features/draft-release.md
@@ -1,11 +1,13 @@
+(draft-release)=
+# Draft-Release Workflow
 ````{margin}
 
 ```{admonition} User types
 :class: tip
 This page is useful for user type 3-5.
 ```
 
-{bdg-secondary}`Python Package: teachbooks`
+{bdg-link-secondary}`Python Package: teachbooks <./overview#teachbooks-python-package>`
 
 ````
 
@@ -74,4 +76,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.
+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.
diff --git a/book/features/external_toc.md b/book/features/external_toc.md
@@ -4,7 +4,7 @@
 This page is useful for user type 3-5.
 ```
 
-{bdg-secondary}`Python Package: teachbooks`
+{bdg-link-secondary}`Python Package: teachbooks <./overview#teachbooks-python-package>`
 ````
 
 (external-toc)=
@@ -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 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 the teachbooks package starting with version `0.2.0`.
 
 ## What does it do?
 
diff --git 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-secondary}`Python Package: teachbooks`
+{bdg-link-secondary}`Python Package: teachbooks <./overview#teachbooks-python-package>`
 ````
 
 (setup-local-server)=
@@ -140,4 +140,4 @@ A Windows-specific command for the CMD prompt or Powershell is:
 
 ```
 TASKKILL /IM python.exe /F
-```
+```
diff --git a/book/features/overview.md b/book/features/overview.md
@@ -14,7 +14,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 <./overview.html#teachbooks-python-package>`
 - {bdg-light}`GitHub Reusable Action`
 - {bdg-light}`GitHub Template`
 - {bdg-dark}`Git Workflow`
@@ -23,4 +23,76 @@ 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).
+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
+
+````{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 <deploy-book-workflow-intro>`, 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 <teachbooks_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/
+```
+
+### 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.
+
+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).
diff --git a/book/features/sphinx_extensions.md b/book/features/sphinx_extensions.md
@@ -7,4 +7,4 @@ This section is useful for user type 4-5.
 
 # Additional functionality
 
-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.
+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.
diff --git 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:
diff --git 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.
diff --git 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

Original file line number	Diff line number	Diff line change
`@@ -20,3 +20,4 @@ The released book can be found on on https://teachbooks.io/manual. This page sho`
`20`	`20`	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`
`21`	`21`
`22`	`22`	`Happy book building!`
	`23`	`+`
Original file line number	Diff line number	Diff line change
`@@ -7,4 +7,4 @@ This section is useful for user type 4-5.`
`7`	`7`
`8`	`8`	`# Additional functionality`
`9`	`9`
`10`		-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.
	`10`	+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.