From c12b41c965095ca6ea89fa38f3cb284239befdc5 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 25 Feb 2025 16:26:57 +0100 Subject: [PATCH 01/17] Update update_env.md From fd5745dc712e75051ba7dca26d8d54dcdba713c6 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 25 Feb 2025 16:36:42 +0100 Subject: [PATCH 02/17] Create external_toc.md --- book/features/external_toc.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 book/features/external_toc.md diff --git a/book/features/external_toc.md b/book/features/external_toc.md new file mode 100644 index 0000000..e69de29 From ca24038f8263490ea32d5ccd548e225e760a346c Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 25 Feb 2025 16:36:52 +0100 Subject: [PATCH 03/17] Update Nested-Books From 48b178930aec1ebe26edc935cd97e212b156323f Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 25 Feb 2025 16:37:42 +0100 Subject: [PATCH 04/17] Merge branch 'release' into reorder_teachbooks From 988953f5ae445015033defa1f29be648d903c1e7 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 25 Feb 2025 16:38:01 +0100 Subject: [PATCH 05/17] Merge branch 'reorder_teachbooks' into docs_external_toc From 1aa6c8df533a6f1e4128e45b5d206fdbd14b7f3a Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 25 Feb 2025 17:00:45 +0100 Subject: [PATCH 06/17] Move submodules to subpages as deprecated --- book/_toc.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index ea8ac52..f1ce221 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -57,7 +57,10 @@ parts: - file: external/deploy-book-workflow/README.md - file: features/pull_request_build.md - file: features/local_server - - file: external/Nested-Books/README.md + - file: features/external_toc + sections: + - file: external/Nested-Books/README.md + title: Deprecated: Share content between books using submodules - file: features/update_env - file: features/sphinx_extensions.md sections: From 3d1fe40dba34df92925a5bbf352f426d2bf86ff0 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 25 Feb 2025 17:02:43 +0100 Subject: [PATCH 07/17] Add explanation --- book/features/external_toc.md | 67 +++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/book/features/external_toc.md b/book/features/external_toc.md index e69de29..bef310f 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -0,0 +1,67 @@ +(teachbooks-package)= +# Sharing content between books in table of contents + +```{admonition} User types +:class: tip +This page is useful for user type 3-5. +``` + +{bdg-secondary}`Python Package` + +## Introduction +When creating books, you might want to reuse material from other people or from other books you made. In some cases you might even want to have the exact same material into your book. You could do so by manually copying material over. However, whenever the source material is updated, you have to do that again. As an alternative, you can use the underlying git system to refer to the source file directly. This allows you to pick a specific version, or keep the most up-to-date version of it. This pages explains how to do so directly in the table of contents using the TeachBooks package. Previously, this was implemented using [submodules] (../external/Nested-Books/README.md), but this implementation is more difficult to use. + +## What does it do? + +This functionality, part of the [TeachBooks package](https://github.com/TeachBooks/TeachBooks) allows you to refer to `.ipynb` and `.md` files stored on public repositories. These files are then handles as if they were normal files in your book, leading to a the file as a page in your built book. + +## Installation +To use this extenstion, follow these steps: + +**Step 1: Install the Package** + +Install the module `teachbooks` package using `pip`: +``` +pip install git+https://github.com/BSchilperoort/TeachBooks@external-git-content +``` + +**Step 2: Add to `requirements.txt`** + +Make sure that the package is included in your project's `requirements.txt` to track the dependency: +``` +git+https://github.com/BSchilperoort/TeachBooks@external-git-content +``` + +## Usage + +To use the functionality, take the URL of a file and add it to your `_toc.yml` as follows: + +```yaml +format: jb-book +root: . + +parts: + - caption: ... + chapters: + - file: ... + . + . + . + - external: + . + . + . +``` + +The link can be pointing to a file on a branch (which will take the most recent version of that file on the branch) or a commit or tag (which will take a specific version of the file). For example: +- `external: https://github.com/TeachBooks/manual/blob/release/book/intro.md` will take the most recent version of the intro page of this book on the release branch +- `external: https://github.com/TeachBooks/manual/blob/06d67e8a0110c94d9147ce07090656dedc7d0e64/README.md` will take the file during the state of a specific commit (06d67e8). +- `external: https://github.com/TeachBooks/manual/blob/v1.1.1/README.md` will take the file during the state of a specific tag (v1.1.1) + +If you're building your book online in GitHub, the [deploy-book-workflow](../external/deploy-book-workflow/README.md) will deal with these files during the `teachbooks build` command. If you want to build the book locally, run the command `teachbooks build`. + +If the source file is from another book, the contents of the `requirements.txt`, `_config.yml` and `*.bib` file are merged to make sure the page has the same functionality as in the source repository. If this leads to compatibility issue, you'll be warned during the build. Furthermore, licenses of external books will be checked to avoid copyright issues. + +## Contribute + +This tool's repository is stored on [GitHub](https://github.com/TeachBooks/TeachBooks). If you'd like to contribute, you can create a fork and open a pull request on the [GitHub repository](https://github.com/TeachBooks/TeachBooks). \ No newline at end of file From 26d1d7876692ab9e2b9d05d0b3f371cc1ceee657 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 25 Feb 2025 17:07:33 +0100 Subject: [PATCH 08/17] Update _toc.yml --- book/_toc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index f1ce221..af02515 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -60,7 +60,7 @@ parts: - file: features/external_toc sections: - file: external/Nested-Books/README.md - title: Deprecated: Share content between books using submodules + title: (Deprecated) Share content between books using submodules - file: features/update_env - file: features/sphinx_extensions.md sections: From a3131c2ff6e5c349bc4106002c1fbe3370ceb441 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 27 Feb 2025 07:35:15 +0100 Subject: [PATCH 09/17] Add functionalities --- 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 bef310f..04d75d6 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -13,7 +13,7 @@ When creating books, you might want to reuse material from other people or from ## What does it do? -This functionality, part of the [TeachBooks package](https://github.com/TeachBooks/TeachBooks) allows you to refer to `.ipynb` and `.md` files stored on public repositories. These files are then handles as if they were normal files in your book, leading to a the file as a page in your built book. +This functionality, part of the [TeachBooks package](https://github.com/TeachBooks/TeachBooks) allows you to refer to `.ipynb` and `.md` files stored on public repositories. These files are then handles as if they were normal files in your book, leading to a the file as a page in your built book. To prevent issues it warns you if there's a mismatch in `requirements.txt`, combines `.bib`-files, merges plugins in `_config.yml` and checks licenses. ## Installation To use this extenstion, follow these steps: From f361a639830cb534f9a92616af174c6212ccdd8b Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 28 Feb 2025 09:04:45 +0100 Subject: [PATCH 10/17] Update external_toc.md --- book/features/external_toc.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/book/features/external_toc.md b/book/features/external_toc.md index 04d75d6..7434e37 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -9,7 +9,9 @@ This page is useful for user type 3-5. {bdg-secondary}`Python Package` ## Introduction -When creating books, you might want to reuse material from other people or from other books you made. In some cases you might even want to have the exact same material into your book. You could do so by manually copying material over. However, whenever the source material is updated, you have to do that again. As an alternative, you can use the underlying git system to refer to the source file directly. This allows you to pick a specific version, or keep the most up-to-date version of it. This pages explains how to do so directly in the table of contents using the TeachBooks package. Previously, this was implemented using [submodules] (../external/Nested-Books/README.md), but this implementation is more difficult to use. +When creating books, you might want to reuse material from other people or from other books you made. In some cases you might even want to have the exact same material into your book. You could do so by manually copying material over. However, whenever the source material is updated, you have to do that again. As an alternative, you can use the underlying git system to refer to the source file directly. This allows you to pick a specific version, or keep the most up-to-date version of it. This pages explains how to do so directly in the table of contents using the TeachBooks package. + +Previously, this was implemented using [submodules] (../external/Nested-Books/README.md), but this implementation was more difficult to use. However, the approach using submodules allows to embed pages which: refer to content in the `_static` folder of the other book, include local images referenced with raw-HTML code, are part of a private book. Furthermore, if you'd like to be notified on updates of the other book, the approach using submodules allows notifications in any case, while the approach described on this page only allows for notifications by 'watching' the other book repository and requiring the other repo owner to release new version with 'releases'. ## What does it do? @@ -64,4 +66,4 @@ If the source file is from another book, the contents of the `requirements.txt`, ## Contribute -This tool's repository is stored on [GitHub](https://github.com/TeachBooks/TeachBooks). If you'd like to contribute, you can create a fork and open a pull request on the [GitHub repository](https://github.com/TeachBooks/TeachBooks). \ No newline at end of file +This tool's repository is stored on [GitHub](https://github.com/TeachBooks/TeachBooks). If you'd like to contribute, you can create a fork and open a pull request on the [GitHub repository](https://github.com/TeachBooks/TeachBooks). From b82e6b9c1979468143a1caa5c5a85a7639b2bf87 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 5 Mar 2025 07:13:10 +0100 Subject: [PATCH 11/17] Update book/features/external_toc.md Co-authored-by: Bart Schilperoort --- book/features/external_toc.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/book/features/external_toc.md b/book/features/external_toc.md index 7434e37..5da5f89 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -11,7 +11,12 @@ This page is useful for user type 3-5. ## Introduction When creating books, you might want to reuse material from other people or from other books you made. In some cases you might even want to have the exact same material into your book. You could do so by manually copying material over. However, whenever the source material is updated, you have to do that again. As an alternative, you can use the underlying git system to refer to the source file directly. This allows you to pick a specific version, or keep the most up-to-date version of it. This pages explains how to do so directly in the table of contents using the TeachBooks package. -Previously, this was implemented using [submodules] (../external/Nested-Books/README.md), but this implementation was more difficult to use. However, the approach using submodules allows to embed pages which: refer to content in the `_static` folder of the other book, include local images referenced with raw-HTML code, are part of a private book. Furthermore, if you'd like to be notified on updates of the other book, the approach using submodules allows notifications in any case, while the approach described on this page only allows for notifications by 'watching' the other book repository and requiring the other repo owner to release new version with 'releases'. +Previously, this was implemented using [submodules](../external/Nested-Books/README.md), but this implementation was more difficult to use. However, the approach using submodules allows to embed pages which: +- refer to content in the `_static` folder of the other book. +- include local images referenced with raw-HTML code. +- are part of a private book. +- _automatically_ notify you upon changes in the source book using Github's "Dependabot". +These features are not incorporated in the new workflow yet. ## What does it do? From 36aafe5c59697311a09c7eb94ebbe017fd341b2b Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 5 Mar 2025 07:13:34 +0100 Subject: [PATCH 12/17] Update book/features/external_toc.md Co-authored-by: Bart Schilperoort --- 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 5da5f89..cb6080f 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -20,7 +20,7 @@ These features are not incorporated in the new workflow yet. ## What does it do? -This functionality, part of the [TeachBooks package](https://github.com/TeachBooks/TeachBooks) allows you to refer to `.ipynb` and `.md` files stored on public repositories. These files are then handles as if they were normal files in your book, leading to a the file as a page in your built book. To prevent issues it warns you if there's a mismatch in `requirements.txt`, combines `.bib`-files, merges plugins in `_config.yml` and checks licenses. +This functionality, part of the [TeachBooks package](https://github.com/TeachBooks/TeachBooks) allows you to refer to `.ipynb`, `.md` and `.rst` files stored on public repositories. These files are then handles as if they were normal files in your book, leading to a the file as a page in your built book. To prevent issues it validates that the external content has a permissive license, automatically combines any `reference.bib` files, and warns you if there's a mismatch in `requirements.txt` or with plugins in `_config.yml`. ## Installation To use this extenstion, follow these steps: From 93b74fda6cefd26ecb8d018500f4364d148f9a11 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 5 Mar 2025 07:16:23 +0100 Subject: [PATCH 13/17] Update book/features/external_toc.md Co-authored-by: Bart Schilperoort --- book/features/external_toc.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/book/features/external_toc.md b/book/features/external_toc.md index cb6080f..940f918 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -67,7 +67,8 @@ The link can be pointing to a file on a branch (which will take the most recent If you're building your book online in GitHub, the [deploy-book-workflow](../external/deploy-book-workflow/README.md) will deal with these files during the `teachbooks build` command. If you want to build the book locally, run the command `teachbooks build`. -If the source file is from another book, the contents of the `requirements.txt`, `_config.yml` and `*.bib` file are merged to make sure the page has the same functionality as in the source repository. If this leads to compatibility issue, you'll be warned during the build. Furthermore, licenses of external books will be checked to avoid copyright issues. +If the source file is from another book, the contents of the `requirements.txt`, `_config.yml` are checked for any missing/incompatible entries. If this leads to compatibility issue, you'll be warned during the build which will help you solve these dependencies or plugins manually by updating your main book's `_config.yml` and `requirements.txt` +Additionally, any `references.bib` files are merged into your main book's `references.bib` file, and the licenses of the external content are validated to allow for re-use. External content without a permissive license will result in an error to try to prevent any accidental copyright infringement. ## Contribute From bd141d0c69e9407790d20c0d3bff2541a1823841 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Thu, 6 Mar 2025 05:26:36 +0100 Subject: [PATCH 14/17] clarify teachbooks package button and improve general explanation --- book/features/external_toc.md | 2 +- book/features/local_server.md | 2 +- book/features/overview.md | 4 ++-- book/features/teachbooks.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/book/features/external_toc.md b/book/features/external_toc.md index 940f918..7e70b36 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` +{bdg-secondary}`Python Package: teachbooks` ## Introduction When creating books, you might want to reuse material from other people or from other books you made. In some cases you might even want to have the exact same material into your book. You could do so by manually copying material over. However, whenever the source material is updated, you have to do that again. As an alternative, you can use the underlying git system to refer to the source file directly. This allows you to pick a specific version, or keep the most up-to-date version of it. This pages explains how to do so directly in the table of contents using the TeachBooks package. diff --git a/book/features/local_server.md b/book/features/local_server.md index cea8930..cc7760c 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` +{bdg-secondary}`Python Package: teachbooks` 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 7ad3782..4a6cd20 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -9,11 +9,11 @@ Since the list of TeachBook features is getting quite long, we have grouped them - Book styling - TeachBooks student-view features -Additionally, not all features are built using the same type of sourcecode. For transparency, tags will help differentiate between the different backgrounds of the features: +Additionally, not all features are built and shared in the same way. We do our best to make sure that as many tools as possible are included automatically when using our TeachBooks Template Book; if you are not using the Template, we try to make sure each of our tools can be used independently. For transparency, tags will help differentiate between the different backgrounds of the features: - {bdg-warning}`Javascript overlay` - {bdg-success}`Chrome Extension` - {bdg-white}`GitHub App and Javascript script` -- {bdg-secondary}`Python Package` +- {bdg-secondary}`Python Package: teachbooks` - {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 index 4caf9a8..e182063 100644 --- a/book/features/teachbooks.md +++ b/book/features/teachbooks.md @@ -6,7 +6,7 @@ This page is useful for all users to understand how the book building process works and can be influenced, although the implementation is likely going to be carried out by User Types 3, 4 or 5. ``` -{bdg-secondary}`Python Package` +{bdg-secondary}`Python Package: teachbooks` 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. From e86e5977152007455e2e18108b5d7d108ba2c43b Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Thu, 6 Mar 2025 05:57:45 +0100 Subject: [PATCH 15/17] pip install teachbooks>=0.2.0 --- book/features/external_toc.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/features/external_toc.md b/book/features/external_toc.md index 7e70b36..94f3f0d 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -29,14 +29,14 @@ To use this extenstion, follow these steps: Install the module `teachbooks` package using `pip`: ``` -pip install git+https://github.com/BSchilperoort/TeachBooks@external-git-content +pip install teachbooks>=0.2.0 ``` **Step 2: Add to `requirements.txt`** Make sure that the package is included in your project's `requirements.txt` to track the dependency: ``` -git+https://github.com/BSchilperoort/TeachBooks@external-git-content +teachbooks>=0.2.0 ``` ## Usage From 65687a36a1111d0828c9681c66f1e3b498fc96eb Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Thu, 6 Mar 2025 06:15:00 +0100 Subject: [PATCH 16/17] simplify submodules part and clarify not in workflow --- book/features/external_toc.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/book/features/external_toc.md b/book/features/external_toc.md index 94f3f0d..0b594b6 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -1,4 +1,4 @@ -(teachbooks-package)= +(external-toc)= # Sharing content between books in table of contents ```{admonition} User types @@ -9,14 +9,14 @@ This page is useful for user type 3-5. {bdg-secondary}`Python Package: teachbooks` ## Introduction -When creating books, you might want to reuse material from other people or from other books you made. In some cases you might even want to have the exact same material into your book. You could do so by manually copying material over. However, whenever the source material is updated, you have to do that again. As an alternative, you can use the underlying git system to refer to the source file directly. This allows you to pick a specific version, or keep the most up-to-date version of it. This pages explains how to do so directly in the table of contents using the TeachBooks package. -Previously, this was implemented using [submodules](../external/Nested-Books/README.md), but this implementation was more difficult to use. However, the approach using submodules allows to embed pages which: -- refer to content in the `_static` folder of the other book. -- include local images referenced with raw-HTML code. -- are part of a private book. -- _automatically_ notify you upon changes in the source book using Github's "Dependabot". -These features are not incorporated in the new workflow yet. +When creating books, you might want to reuse material from other people or from other books you made. In some cases you might even want to have the exact same material into your book. You could do so by manually copying material over. However, whenever the source material is updated, you have to do that again. As an alternative, you can use the underlying git system to refer to the source file directly. This allows you to pick a specific version, or keep the most up-to-date version of it. This pages explains how to do so directly in the table of contents using the **External Content** (or **External TOC**) feature which is part of the TeachBooks Python package. + +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. + +```{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`). +``` ## What does it do? From 857dbd5d61bfcef6ad8188aaafe914683e61293d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 6 Mar 2025 07:36:43 +0100 Subject: [PATCH 17/17] Mention explicitly missing features --- 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 0b594b6..c0a2a50 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -12,7 +12,7 @@ This page is useful for user type 3-5. When creating books, you might want to reuse material from other people or from other books you made. In some cases you might even want to have the exact same material into your book. You could do so by manually copying material over. However, whenever the source material is updated, you have to do that again. As an alternative, you can use the underlying git system to refer to the source file directly. This allows you to pick a specific version, or keep the most up-to-date version of it. This pages explains how to do so directly in the table of contents using the **External Content** (or **External TOC**) feature which is part of the TeachBooks Python package. -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. +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`).