From f7db33d333df197bc606cab95c1af6e009c7c8c0 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sat, 19 Jul 2025 13:49:05 +0200 Subject: [PATCH 1/7] Create 007.md --- book/exercises/007.md | 67 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 book/exercises/007.md diff --git a/book/exercises/007.md b/book/exercises/007.md new file mode 100644 index 0000000..92bc525 --- /dev/null +++ b/book/exercises/007.md @@ -0,0 +1,67 @@ +# Exercise 8: Add extensions to your book + +TeachBooks supports many useful extensions, but sometimes you may want more functionality. In this exercise, you'll learn how to add an external extension to your book that is not already built-in. We will use the [`Sphinx-Indexed-Definitions`](https://github.com/TeachBooks/Sphinx-Indexed-Definitions) extension as an example, which allows you to define glossary-style entries with indexed labels. + +\::::::{topic} Exercise objective +Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` in your TeachBooks book? +\:::::: + +1. In your book repository, open the `requirements.txt` file. This file lists the Python packages that will be installed to build your book. + +2. Add the following line to the bottom of the `requirements.txt` file: + + ``` + git+https://github.com/TeachBooks/Sphinx-Indexed-Definitions.git + ``` + + This tells the build system to install the extension directly from GitHub. + +3. Next, open `_config.yml` and add the extension to your `sphinx` configuration block: + + ```yaml + sphinx: + extra_extensions: + - indexed_definitions + ``` + + This ensures Sphinx loads the extension when building your book. + +4. Now you can use the new directive provided by the extension. Try adding the following to one of your Markdown files in the `book/` directory: + + `````md + ````{definition} Term + :label: term-definition + A word or phrase used to describe a concept or object. + ````` + + This will render a labelled, indexed definition that you can refer to from other parts of your book. + +5. Try to reference the definition in another file using `{ref}` followed by the given label, as shown below: + + + ```md + For more details, see the definition of {ref}`term-definition`. + ``` + + This will appear as a hyperlink that takes the reader directly to the definition. + +6. The same steps you followed here can be used to install any other extension of your choice. Simply add the extension to your `requirements.txt` (using either a GitHub link or PyPI package name), and list it under `extra_extensions` in `_config.yml`. Then use its features in your Markdown files according to the extension’s documentation. + + +7. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +8. Add a commit message. + +9. To see your changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). +10. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. + + +```{admonition} Check your understanding +:class: note + +Before moving on, make sure you understand: + +* How do you add a new extension to a TeachBooks book? +* What is the purpose of the `requirements.txt` and `_config.yml` files? +* How can you confirm that your extension is working correctly? +``` From 5bf79adc0b252dd7ed49f84ef080fd57f4737943 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sat, 19 Jul 2025 13:52:48 +0200 Subject: [PATCH 2/7] Update _toc.yml --- book/_toc.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/book/_toc.yml b/book/_toc.yml index c3263ab..e93a13f 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -16,6 +16,7 @@ parts: - file: exercises/005.md - file: exercises/005a.md - file: exercises/006.md + - file: exercises/007.md - file: exercises/summary - file: syntax_exercises.md sections: From 71b50414fa2a0013078b9ae4a83b8f6a7a608410 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sat, 19 Jul 2025 13:58:21 +0200 Subject: [PATCH 3/7] Update 007.md --- book/exercises/007.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/exercises/007.md b/book/exercises/007.md index 92bc525..0336bd1 100644 --- a/book/exercises/007.md +++ b/book/exercises/007.md @@ -2,9 +2,9 @@ TeachBooks supports many useful extensions, but sometimes you may want more functionality. In this exercise, you'll learn how to add an external extension to your book that is not already built-in. We will use the [`Sphinx-Indexed-Definitions`](https://github.com/TeachBooks/Sphinx-Indexed-Definitions) extension as an example, which allows you to define glossary-style entries with indexed labels. -\::::::{topic} Exercise objective +::::::{topic} Exercise objective Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` in your TeachBooks book? -\:::::: +:::::: 1. In your book repository, open the `requirements.txt` file. This file lists the Python packages that will be installed to build your book. From 11e56e836e0a1c04fa64ddb8962b6cfd81a6ee4e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 28 Jul 2025 10:37:32 +0200 Subject: [PATCH 4/7] Update 007.md --- book/exercises/007.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/book/exercises/007.md b/book/exercises/007.md index 0336bd1..d7b5256 100644 --- a/book/exercises/007.md +++ b/book/exercises/007.md @@ -1,6 +1,6 @@ # Exercise 8: Add extensions to your book -TeachBooks supports many useful extensions, but sometimes you may want more functionality. In this exercise, you'll learn how to add an external extension to your book that is not already built-in. We will use the [`Sphinx-Indexed-Definitions`](https://github.com/TeachBooks/Sphinx-Indexed-Definitions) extension as an example, which allows you to define glossary-style entries with indexed labels. +TeachBooks supports many useful extensions, but sometimes you may want more functionality. In this exercise, you'll learn how to add an external extension to your book that is not already built-in. We will use the [`Sphinx-Indexed-Definitions`](https://github.com/TeachBooks/Sphinx-Indexed-Definitions) extension as an example, which allows you to define glossary-style entries with indexed labels in an easy way. ::::::{topic} Exercise objective Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` in your TeachBooks book? @@ -11,10 +11,10 @@ Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` 2. Add the following line to the bottom of the `requirements.txt` file: ``` - git+https://github.com/TeachBooks/Sphinx-Indexed-Definitions.git + sphinx-indexed-definitions ``` - This tells the build system to install the extension directly from GitHub. + This tells the build system to install the extension from PyPi, a repository which contains Python software 3. Next, open `_config.yml` and add the extension to your `sphinx` configuration block: @@ -26,7 +26,9 @@ Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` This ensures Sphinx loads the extension when building your book. -4. Now you can use the new directive provided by the extension. Try adding the following to one of your Markdown files in the `book/` directory: +4. Now you can use the new directive provided by the extension. First, read the documentation to understand how to apply it. In most cases, the documentation can be found in the README of the source repository of the software. For our example that is here: https://github.com/TeachBooks/Sphinx-Indexed-Definitions + +5. Try adding the following to one of your Markdown files in the `book/` directory: `````md ````{definition} Term @@ -36,7 +38,7 @@ Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` This will render a labelled, indexed definition that you can refer to from other parts of your book. -5. Try to reference the definition in another file using `{ref}` followed by the given label, as shown below: +6. Try to reference the definition in another file using `{ref}` followed by the given label, as shown below: ```md @@ -45,15 +47,14 @@ Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` This will appear as a hyperlink that takes the reader directly to the definition. -6. The same steps you followed here can be used to install any other extension of your choice. Simply add the extension to your `requirements.txt` (using either a GitHub link or PyPI package name), and list it under `extra_extensions` in `_config.yml`. Then use its features in your Markdown files according to the extension’s documentation. +7. The same steps you followed here can be used to install any other extension of your choice. Simply add the extension to your `requirements.txt` (using either a GitHub link or PyPI package name), and list it under `extra_extensions` in `_config.yml`. Then use its features in your Markdown files according to the extension’s documentation. Check out the ever-growing list of TeachBooks extensions in the [TeachBooks manual](https://teachbooks.io/manual/features/overview.html)! +8. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -7. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. +9. Add a commit message. -8. Add a commit message. - -9. To see your changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). -10. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +10. To see your changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). +11. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. ```{admonition} Check your understanding From f5d17483f5c75f403e90e2894fa341b10adcc31c Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Mon, 11 Aug 2025 22:02:58 +0200 Subject: [PATCH 5/7] automatic indexing --- book/exercises/007.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/book/exercises/007.md b/book/exercises/007.md index d7b5256..d6c5d47 100644 --- a/book/exercises/007.md +++ b/book/exercises/007.md @@ -47,7 +47,16 @@ Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` This will appear as a hyperlink that takes the reader directly to the definition. -7. The same steps you followed here can be used to install any other extension of your choice. Simply add the extension to your `requirements.txt` (using either a GitHub link or PyPI package name), and list it under `extra_extensions` in `_config.yml`. Then use its features in your Markdown files according to the extension’s documentation. Check out the ever-growing list of TeachBooks extensions in the [TeachBooks manual](https://teachbooks.io/manual/features/overview.html)! + +7. The extension can also automatically index terms based on text formatting. In another `.md` file, try writing: + + ```md + This is a **strong term**, this is an *emphasised term*, and this is a `literal term`. + ``` + + When the book is built, these terms will be included in the generated index without needing to define them manually. You can view the index in the build output to confirm. + +8. The same steps you followed here can be used to install any other extension of your choice. Simply add the extension to your `requirements.txt` (using either a GitHub link or PyPI package name), and list it under `extra_extensions` in `_config.yml`. Then use its features in your Markdown files according to the extension’s documentation. Check out the ever-growing list of TeachBooks extensions in the [TeachBooks manual](https://teachbooks.io/manual/features/overview.html)! 8. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. From fe120cfe0a7a01ef401723acf3b9434931c73191 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 18 Aug 2025 10:50:10 +0200 Subject: [PATCH 6/7] close brackets --- book/exercises/007.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/exercises/007.md b/book/exercises/007.md index d6c5d47..d505f62 100644 --- a/book/exercises/007.md +++ b/book/exercises/007.md @@ -34,6 +34,7 @@ Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` ````{definition} Term :label: term-definition A word or phrase used to describe a concept or object. + ```` ````` This will render a labelled, indexed definition that you can refer to from other parts of your book. From 590cdc1474772b2c084fc4defc5085c562945a6d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 18 Aug 2025 10:51:47 +0200 Subject: [PATCH 7/7] Update summary.md --- book/exercises/summary.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/exercises/summary.md b/book/exercises/summary.md index a166a9d..d3cd5b0 100644 --- a/book/exercises/summary.md +++ b/book/exercises/summary.md @@ -15,12 +15,12 @@ Here is how these exercises relate to the workflow. | :---: | :---: | :---: | :---: | | 1 | Get and idea | 4 | Create an issue | | 2 | Create _your_ version of the book | 4 | Create a branch | -| 3 | Edit the book | 1, 2, 3, 6| Editing `.md`-files, the `_toc.yml` and the `_config.yml` | -| 4 | Check changes online | 1, 2, 3, 6 | Workflows and Actions Summary | -| 5 | Repeat edit and checking | 1, 2, 3, 4, 5 | Keep on doing all the steps until it's ready| +| 3 | Edit the book | 1, 2, 3, 6, 8| Editing `.md`-files, the `_toc.yml` and the `_config.yml` | +| 4 | Check changes online | 1, 2, 3, 6, 8 | Workflows and Actions Summary | +| 5 | Repeat edit and checking | 1, 2, 3, 4, 5, 8 | Keep on doing all the steps until it's ready| | 6 | Submit for review | 5, 7 | Open and merge a Pull Request, from a branch or forks | ## Keep practicing For additional practice, there are more exercises relating to the capacities of each user type. -Have a look in the [manual](https://teachbooks.io/manual/installation-and-setup/user_types.html) to see which user type you are! \ No newline at end of file +Have a look in the [manual](https://teachbooks.io/manual/installation-and-setup/user_types.html) to see which user type you are!