From 2229dd7a7b1ad9abc612bd1c31c9d05af84b63a5 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 21:32:39 +0100 Subject: [PATCH 01/15] 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 02/15] 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 03/15] 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 04/15] 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 05/15] 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 06/15] 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 07/15] 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 08/15] 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 09/15] 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 10/15] 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 11/15] 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 12/15] 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 13/15] 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 14/15] 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 15/15] 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.