From b5baeca981349e16f734226c294d6a5023c2a04e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 23 Apr 2025 15:52:53 +0200 Subject: [PATCH 1/5] Add recombiner to share content page --- book/features/external_toc.md | 11 ++++++++--- book/features/overview.md | 1 + 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/book/features/external_toc.md b/book/features/external_toc.md index b2287e8..b60c445 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -5,6 +5,7 @@ This page is useful for user type 3-5. ``` {bdg-link-secondary}`Python Package: teachbooks <./overview#teachbooks-python-package>` +{bdg-succes}`WebApp` ```` (external-toc)= @@ -12,18 +13,20 @@ 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 **External Content** (or **External TOC**) feature which is part of the TeachBooks Python package. +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, or with making use of the [TeachBooks Recombiner](https://teachbooks.io/recombiner/) 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. -The External TOC features are incorporated in the teachbooks package starting with version `0.2.0`. +The External TOC features are incorporated in the teachbooks package starting with version `0.2.0`. The [TeachBooks Recombiner](https://teachbooks.io/recombiner/) is a webapp to ease that process. ## What does it do? 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`. +To ease the process, the webapp [TeachBooks Recombiner](https://teachbooks.io/recombiner/) allows you to select the pages to take from other books and generate the syntax to add them to your book. + ## Installation -To use this extenstion, follow these steps: +To use this extension, follow these steps: **Step 1: Install the Package** @@ -65,6 +68,8 @@ The link can be pointing to a file on a branch (which will take the most recent - `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) +These links can be created manually, copied from your browser, or by using the [TeachBooks Recombiner](https://teachbooks.io/recombiner/). For the TeachBooks Recombiner: add the book you want to take content from, select the chapters and follow the instructions which gives you the syntax to add to your `_toc.yml`. + 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` 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` diff --git a/book/features/overview.md b/book/features/overview.md index 33e603f..4512da2 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -20,6 +20,7 @@ Additionally, not all features are built and shared in the same way. We do our b - {bdg-dark}`Git Workflow` - {bdg-primary}`Sphinx Extension` - {bdg-danger}`iframe` +- {bdg-succes}`WebApp` Finally, the purpose, installation process and usage of each features is elaborated on in the respective sub-sections. From d90c0287f5fb7b006bd6f774f52d7f9cf6bf59f9 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 23 Apr 2025 15:57:23 +0200 Subject: [PATCH 2/5] Update external_toc.md --- book/features/external_toc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/features/external_toc.md b/book/features/external_toc.md index b60c445..3d68754 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -5,6 +5,7 @@ This page is useful for user type 3-5. ``` {bdg-link-secondary}`Python Package: teachbooks <./overview#teachbooks-python-package>` + {bdg-succes}`WebApp` ```` From 59d2320eee697d08dee89fae6d1b1029a1873f0e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 23 Apr 2025 15:57:44 +0200 Subject: [PATCH 3/5] typo fix --- book/features/external_toc.md | 2 +- book/features/overview.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/book/features/external_toc.md b/book/features/external_toc.md index 3d68754..fb9dd22 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-succes}`WebApp` +{bdg-success}`WebApp` ```` (external-toc)= diff --git a/book/features/overview.md b/book/features/overview.md index 4512da2..f7cf5db 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -20,7 +20,7 @@ Additionally, not all features are built and shared in the same way. We do our b - {bdg-dark}`Git Workflow` - {bdg-primary}`Sphinx Extension` - {bdg-danger}`iframe` -- {bdg-succes}`WebApp` +- {bdg-success}`WebApp` Finally, the purpose, installation process and usage of each features is elaborated on in the respective sub-sections. From 8e1420603813f6e0a1a579b219faa2973f7471ab Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 23 Apr 2025 17:03:15 +0200 Subject: [PATCH 4/5] 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 fb9dd22..15d0cb7 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -14,7 +14,7 @@ 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 **External Content** (or **External TOC**) feature which is part of the TeachBooks Python package, or with making use of the [TeachBooks Recombiner](https://teachbooks.io/recombiner/) +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, or by making use of the [TeachBooks Recombiner](https://teachbooks.io/recombiner/). 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. From c2f38e8c417d72aca294693cac203dc240d9a056 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 23 Apr 2025 17:03:29 +0200 Subject: [PATCH 5/5] 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 15d0cb7..40c28fc 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -69,7 +69,7 @@ The link can be pointing to a file on a branch (which will take the most recent - `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) -These links can be created manually, copied from your browser, or by using the [TeachBooks Recombiner](https://teachbooks.io/recombiner/). For the TeachBooks Recombiner: add the book you want to take content from, select the chapters and follow the instructions which gives you the syntax to add to your `_toc.yml`. +These links can be created manually, copied from your browser, or generated using the [TeachBooks Recombiner](https://teachbooks.io/recombiner/). For the TeachBooks Recombiner: add the book you want to take content from, select the chapters and follow the instructions which gives you the syntax to add to your `_toc.yml`. 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`.