diff --git a/book/_toc.yml b/book/_toc.yml index 289d240..09cd976 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -46,9 +46,9 @@ parts: - file: features/teachbooks_intro.md - file: external/deploy-book-workflow/README.md - file: features/favourites.md + - file: external/template/README.md - file: features/easy-editing.md sections: - - file: external/template/README.md - file: features/write_online.md - file: features/release_book_online.md - file: features/draft-release @@ -84,7 +84,9 @@ parts: - file: external/Sphinx-PRIME-applets/README.md - external: https://github.com/TeachBooks/Sphinx-Dropdown-Toggle/blob/main/MANUAL.md - external: "https://github.com/TeachBooks/sphinx-code-examples/blob/main/MANUAL.ipynb" + - file: features/sphinx-proof.md - external: "https://github.com/TeachBooks/Sphinx-NB-Execution-Patterns/blob/Manual/README.md" + - file: features/exercise.md - file: features/visuals.md sections: - external: https://github.com/TeachBooks/Sphinx-Accessibility/blob/manual/README.md diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md index eb60ffe..8790d60 100644 --- a/book/basic-features/overview.md +++ b/book/basic-features/overview.md @@ -7,4 +7,4 @@ This section is useful for [user type 3-5](../installation-and-setup/user_types. # Overview -These pages will provide a list of some common, basic book features which are all available in the original Jupyter book package. Additionally, this page includes also best-practices. +These pages will provide a list of some common, basic book features which are all available in the original Jupyter book package without addition of any additional software. Additionally, this page includes also best-practices. diff --git a/book/credits.md b/book/credits.md index e98ad9c..0fe26e7 100644 --- a/book/credits.md +++ b/book/credits.md @@ -66,6 +66,5 @@ The following pages contain content written by others, part of has been reused a - Page {ref}`copyright_licenses`: {numref}`Figure %s` is included unmodified. Work is provided by Kennisland under a CC0 license. Accessed at [](https://wiki.creativecommons.org/wiki/File:CC_License_Compatibility_Chart.png) on December 17, 2024. - page [](./features/versioning.md): includes text from {cite:t}`semver` that has been modified. Original content licensed under CC BY 3.0. - page [](./features/external_toc.md): includes text from {cite:t}`teachbooks_package` that has been modified. Original content licensed under MIT. - - - +- Page [](./features/exercise.md): includes text from {cite:t}`sphinx-exercise` that has been modified. Original content licensed under MIT license. +- Page [](./features/sphinx-proof.md): includes text from {cite:t}`sphinx-proof` that has been modified. Original content licensed under MIT license. \ No newline at end of file diff --git a/book/external/Download-Link-Replacer b/book/external/Download-Link-Replacer index 10ff656..d6f318f 160000 --- a/book/external/Download-Link-Replacer +++ b/book/external/Download-Link-Replacer @@ -1 +1 @@ -Subproject commit 10ff656dc4b871330dd2271d00d2e8b9a9a57613 +Subproject commit d6f318f52cef2f64f44f195c95ea8a449cf37fe2 diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches index eb505b3..e6e2706 160000 --- a/book/external/JupyterBook-Patches +++ b/book/external/JupyterBook-Patches @@ -1 +1 @@ -Subproject commit eb505b3013d4019e01e448495e3eb1586f573a00 +Subproject commit e6e27067f60a576e3db745361601a1c43bbae5f4 diff --git a/book/external/Nested-Books b/book/external/Nested-Books index 9436769..abb9e70 160000 --- a/book/external/Nested-Books +++ b/book/external/Nested-Books @@ -1 +1 @@ -Subproject commit 943676969d6e42b9c6d9c25d5313d9c0fbceea97 +Subproject commit abb9e707d66ad26e55dfd037835f7f7cc86f2620 diff --git a/book/external/Sphinx-Image-Inverter b/book/external/Sphinx-Image-Inverter index eb21e6a..2351ab0 160000 --- a/book/external/Sphinx-Image-Inverter +++ b/book/external/Sphinx-Image-Inverter @@ -1 +1 @@ -Subproject commit eb21e6a80ed33f0102f9025b9ee983148370d753 +Subproject commit 2351ab0e25a067d6420be078232e5a6e3d9c3168 diff --git a/book/external/Sphinx-Named-Colors b/book/external/Sphinx-Named-Colors index 57ecdd8..c85d64e 160000 --- a/book/external/Sphinx-Named-Colors +++ b/book/external/Sphinx-Named-Colors @@ -1 +1 @@ -Subproject commit 57ecdd887e8bbc32a04aca20e9fc9cb60409b7d0 +Subproject commit c85d64eacbc6b0980530134b08406193f452cf0f diff --git a/book/external/Sphinx-launch-buttons b/book/external/Sphinx-launch-buttons index e6070de..2d85abc 160000 --- a/book/external/Sphinx-launch-buttons +++ b/book/external/Sphinx-launch-buttons @@ -1 +1 @@ -Subproject commit e6070ded6ca77662a3a951893cafe265fa333e5e +Subproject commit 2d85abc35c533a6e756d2c16344fe107be24e427 diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow index 1b35fe8..f983f1e 160000 --- a/book/external/deploy-book-workflow +++ b/book/external/deploy-book-workflow @@ -1 +1 @@ -Subproject commit 1b35fe87afc980274f5731af7b7b74f7df27540c +Subproject commit f983f1e3ec7d99b14fb50631ea48f1f23a15ee76 diff --git a/book/external/sphinx-iframes b/book/external/sphinx-iframes index 583163e..a572035 160000 --- a/book/external/sphinx-iframes +++ b/book/external/sphinx-iframes @@ -1 +1 @@ -Subproject commit 583163ebf970a83ff45d80bb9ace9922d1e1615b +Subproject commit a57203589e1acfaa216a436ea57d17b0b1e76824 diff --git a/book/external/teachbooks-sphinx-tippy b/book/external/teachbooks-sphinx-tippy index e4166e1..4d246da 160000 --- a/book/external/teachbooks-sphinx-tippy +++ b/book/external/teachbooks-sphinx-tippy @@ -1 +1 @@ -Subproject commit e4166e1389ab48ea9059e6576e56d270e66199dd +Subproject commit 4d246da43ec7848928e673ca9223458028d3e473 diff --git a/book/external/template b/book/external/template index 8424c5e..efa0edb 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit 8424c5e1fb5631474250859482b92fc1761c502f +Subproject commit efa0edbb1180081e8ab57ba95eeaece195d786af diff --git a/book/features/apa.md b/book/features/apa.md index 49bdf3f..547e547 100644 --- a/book/features/apa.md +++ b/book/features/apa.md @@ -5,6 +5,9 @@ This page is useful for user type 4 and 5. ``` {bdg-primary}`(To be converted into) Sphinx Extension` +{bdg-link-secondary}`Supported by TeachBooks package ` + + ```` (apa)= diff --git a/book/features/draft-release.md b/book/features/draft-release.md index c194753..7e8de38 100644 --- a/book/features/draft-release.md +++ b/book/features/draft-release.md @@ -6,7 +6,9 @@ This page is useful for user type 3-5. ``` -{bdg-secondary}`Python Package: teachbooks <./teachbooks_intro.html>` +{bdg-link-secondary}`Uses TeachBooks package ` +{bdg-link-light}`Included in TeachBooks Template ` +{bdg-link-light}`Supported by Deploy Book workflow ` ```` diff --git a/book/features/exercise.md b/book/features/exercise.md new file mode 100644 index 0000000..9f88cfd --- /dev/null +++ b/book/features/exercise.md @@ -0,0 +1,88 @@ +````{margin} +```{attributiongrey} Attribution +:class: attribution +This page reuses MIT licensed content from {cite:t}`sphinx-exercise`. {fa}`quote-left`{ref}`Find out more here.` +``` + +```{admonition} User types +:class: tip +This section is useful for user type 3-5. +``` ++++ +{bdg-primary}`Sphinx Extension` +{bdg-link-light}`Included in TeachBooks Template ` +{bdg-link-primary-line}`Included in TeachBooks Favourites ` +```` + +# Sphinx exercise + +This extensions provides an easy way to add exercises and solutions to your book. It is documented on https://ebp-sphinx-exercise.readthedocs.io/en/latest/. + +TeachBooks has made some small modifications to the original extension, such that it works well with translated books. + +## What does it do? + +This extension defines exercises and solutions as new admonition types: + +```{exercise} +:label: my-exercise + +Recall that $n!$ is read as "$n$ factorial" and defined as +$n! = n \times (n - 1) \times \cdots \times 2 \times 1$. + +There are functions to compute this in various modules, but let's +write our own version as an exercise. + +In particular, write a function `factorial` such that `factorial(n)` returns $n!$ +for any positive integer $n$. +``` + +````{solution} my-exercise +:label: my-solution + +Here's one solution. + +```{code-block} python +def factorial(n): + k = 1 + for i in range(n): + k = k * (i + 1) + return k + +factorial(4) +``` +```` + +More information can be found in the [official documentation](https://ebp-sphinx-exercise.readthedocs.io/en/latest/). + +## Installation +To use this extenstion, follow these steps: + +**Step 1: Install the Package** + +Install the TeachBooks' version of `sphinx-exercise` package using `pip`: +``` +pip install sphinx-exercise @ git+https://github.com/TeachBooks/sphinx-exercise.git +``` + +**Step 2: Add to `requirements.txt`** + +Make sure that the package is included in your project's `requirements.txt` to track the dependency: +``` +sphinx-exercise @ git+https://github.com/TeachBooks/sphinx-exercise.git +``` + +**Step 3: Enable in `_config.yml`** + +In your `_config.yml` file, add the extension to the list of Sphinx extra extensions (**important**: underscore, not dash this time): +``` +sphinx: + extra_extensions: + . + . + . + - sphinx_exercise + . + . + . +``` diff --git a/book/features/external_toc.md b/book/features/external_toc.md index ea770fa..24dd53c 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -9,7 +9,7 @@ This page reuses MIT licensed content from {cite:t}`teachbooks_package`. {fa}`qu This page is useful for user type 3-5. ``` -{bdg-link-secondary}`Python Package: teachbooks <./teachbooks_intro.html>` +{bdg-link-secondary}`Uses TeachBooks package ` {bdg-success}`WebApp` ```` diff --git a/book/features/favourites.md b/book/features/favourites.md index 4371054..a0771d2 100644 --- a/book/features/favourites.md +++ b/book/features/favourites.md @@ -5,26 +5,70 @@ This page is useful for user type 3-5. ``` {bdg-primary}`Sphinx Extension` +{bdg-link-light}`Included in TeachBooks Template ` + ```` # TeachBooks Favourites -TeachBooks Favourites is a Sphinx extension which collects all of TeachBooks' favourite features in one place (including tools originally by TeachBooks and from other sources). It is included by default in the [TeachBooks Template](../external/template/README.md) and can be installed independently using `pip install teachbooks-favourites`. The features included are: +TeachBooks Favourites is a Sphinx extension which collects all of TeachBooks' favourite features in one place (including tools originally by TeachBooks and from other sources). It is included by default in the [TeachBooks Template](../external/template/README.md) or can be installed independently. The features included are: - [Sphinx-Thebe from TeachBooks](./live_code.ipynb) -- [Jupyterbook patches](../external/jupyterbook-patches/README.md) -- [Download link replacer](../external/download-link-replacer/README.md) -- [Sphinx image inverter](../external/sphinx-image-inverter/README.md) +- [Jupyterbook patches](../external/JupyterBook-Patches/README.md) +- [Download link replacer](../external/Download-Link-Replacer/README.md) +- [Sphinx image inverter](../external/Sphinx-Image-Inverter/README.md) - [Sphinx iframes](../external/sphinx-iframes/README.md) - [Sphinx exercise (TeachBooks contribution to the original)](https://ebp-sphinx-exercise.readthedocs.io/en/latest/) -- [Teachbooks Sphinx tippy](../external/teachbooks-sphinx-tippy/README.html) -- [Sphinx named colors](../external/sphinx-named-colors/README.md) +- [Teachbooks Sphinx tippy](../external/teachbooks-sphinx-tippy/README.md) +- [Sphinx named colors](../external/Sphinx-Named-Colors/README.md) - [Sphinx dropdown toggle](../_git/github.com_TeachBooks_Sphinx-Dropdown-Toggle/main/MANUAL.md) - [Sphinx proof (TeachBooks contribution to the original)](https://sphinx-proof.readthedocs.io/en/latest/) - [Sphinx code examples](../_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.md) -- [Sphinx accessibility](../_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.html) +- [Sphinx accessibility](../_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.md) - [Sphinx toggle button (TeachBooks contribution to the original)](https://sphinx-togglebutton.readthedocs.io/en/latest/) -- [Notebook execution patterns](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html) +- [Notebook execution patterns](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.md) -All features which are part of TeachBooks Favourites are indicated with {bdg-primary-line}`Part of TeachBooks Favourites`. If you'd like to use specific features, but not the entire TeachBooks Favourites, you can remove this extension and replace it with the individual extensions you want to use. \ No newline at end of file +All features which are part of TeachBooks Favourites are indicated with {bdg-primary-line}`Part of TeachBooks Favourites`. If you'd like to use specific features, but not the entire TeachBooks Favourites, you can remove this extension and replace it with the individual extensions you want to use. + +## Installation +To install TeachBooks-Favourites, follow these steps: + +**Step 1: Install the Package** + +Install the `teachbooks-favourites` package using `pip`: +``` +pip install git+https://github.com/TeachBooks/TeachBooks-Favourites +``` + +**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/TeachBooks/TeachBooks-Favourites +``` + +**Step 3: Enable in `_config.yml`** + +In your `_config.yml` file, add the extension to the list of Sphinx extra extensions (**important**: underscore, not dash this time): +``` +sphinx: + extra_extensions: + - teachbooks_favourites +``` + +## Usage + +For using the various package we refer to the different manuals linked above. + +All extensions are loaded with their default settings. + +## Contribute + +Do you think we missed an extension that should really be included? Let us know by either + +- creating a fork of this repository and submitting a pull request, in which you added the extension to the files + - `README.md` + - `pyproject.toml` + - `src\teachbooks_favourites\__init__.py` +- opening an issue. \ No newline at end of file diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb index 5eb4eed..d0bfa2d 100644 --- a/book/features/live_code.ipynb +++ b/book/features/live_code.ipynb @@ -11,7 +11,8 @@ "```\n", "\n", "{bdg-primary}`Sphinx Extension`\n", - "{bdg-primary-line}`Part of TeachBooks Favourites`\n", + "{bdg-link-light}`Included in TeachBooks Template `\n", + "{bdg-link-primary-line}`Included in TeachBooks Favourites `\n", "\n", "```` \n", "\n", diff --git a/book/features/local_server.md b/book/features/local_server.md index ec21dcc..f3bf55e 100644 --- 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-link-secondary}`Python Package: teachbooks <./teachbooks_intro.html>` +{bdg-link-secondary}`Uses TeachBooks package ` ```` (setup-local-server)= diff --git a/book/features/overview.md b/book/features/overview.md index a095121..81a291f 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -15,8 +15,8 @@ Additionally, not all features are built and shared in the same way. We do our b - {bdg-success}`Chrome Extension` - {bdg-white}`GitHub App and Javascript script` - {bdg-link-secondary}`Python Package: teachbooks <./teachbooks_intro.html>` -- {bdg-link-light}`GitHub Reusable Action: Deploy Book workflow ` -- {bdg-link-light}`GitHub Template: TeachBooks Template ` +- {bdg-link-light}`GitHub Reusable Action: Deploy Book workflow ` +- {bdg-link-light}`GitHub Template: TeachBooks Template ` - {bdg-dark}`Git Workflow` - {bdg-primary}`Sphinx Extension` - {bdg-link-primary-line}`TeachBooks Favourites <./favourites.html>` @@ -27,4 +27,4 @@ Finally, the purpose, installation process and usage of each features is elabora To see examples for these features, go to the [Examples chapter](../examples/overview.md). -As the [TeachBooks Python Package](./teachbooks_intro.md), the [Deploy Book Workflow](https://teachbooks.io/manual/favourites/external/deploy-book-workflow/README.html) and [TeachBooks Favourites](./favourites.md) are important tools that incorporate and deploy more than one feature, an additional explanation is provided here in subpages in more detail, with links to the pages in this manual where individual features are described. \ No newline at end of file +As the [TeachBooks Python Package](./teachbooks_intro.md), the [Deploy Book Workflow](https://teachbooks.io/manual/external/deploy-book-workflow/README.html), [TeachBooks Favourites](./favourites.md) and the TeachBook template are important tools that incorporate and deploy more than one feature, an additional explanation is provided here in subpages in more detail, with links to the pages in this manual where individual features are described. \ No newline at end of file diff --git a/book/features/release_book_online.md b/book/features/release_book_online.md index 3171c07..5f494c5 100644 --- a/book/features/release_book_online.md +++ b/book/features/release_book_online.md @@ -4,8 +4,9 @@ This section is useful for user type 3-5. ``` -{bdg-link-light}`GitHub Reusable Action: Deploy Book workflow ` -{bdg-link-light}`Part of TeachBooks Template ` +{bdg-link-light}`GitHub Reusable Action: Deploy Book workflow ` +{bdg-link-light}`Part of TeachBooks Template ` +{bdg-link-secondary}`Uses TeachBooks package ` ```` @@ -13,7 +14,7 @@ This section is useful for user type 3-5. As you'll start working on your TeachBook, you'll probably want to share it online. And over time you'll create more and more versions of your book, for example for different academic years. -Our Deploy Book Workflow (described in general [here](https://teachbooks.io/manual/favourites/external/deploy-book-workflow/README.html)) allows you to do so. It builds your book for all branches in your repository and releases them online via GitHub Pages. In simplified terms, it automatically builds the book website based on updates to your repository, creates multiple instances of your book (defined by each branch) and provides the ability to customize the URL's at which each instance of the book can be accessed. This tool is designed specifically for educational contexts, for example, when you may want to preserve book versions from multiple academic years so that students are able to access it later. +Our Deploy Book Workflow (described in general [here](https://teachbooks.io/manual/external/deploy-book-workflow/README.html)) allows you to do so. It builds your book for all branches in your repository and releases them online via GitHub Pages. In simplified terms, it automatically builds the book website based on updates to your repository, creates multiple instances of your book (defined by each branch) and provides the ability to customize the URL's at which each instance of the book can be accessed. This tool is designed specifically for educational contexts, for example, when you may want to preserve book versions from multiple academic years so that students are able to access it later. Sharing your book online has many features and customizations: - Automatic and manual building and releasing of your book online via GitHub Pages using a Reusable GitHub Actions. See explanation [below](how_to_start). @@ -210,7 +211,7 @@ Once created during a successful build action, an existing cached environment wi Note that any change to the `requirements.txt` file will trigger creation of a new environment, not necessarily one that specifies the version number of a package. -Note that Specifying package version numbers explicitly and updating them via [Dependabot](https://teachbooks.io/manual/favourites/features/update_env.html) is an excellent way to ensure that environments in the DBW are always up to date and this issue is avoided. +Note that Specifying package version numbers explicitly and updating them via [Dependabot](https://teachbooks.io/manual/features/update_env.html) 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-proof.md b/book/features/sphinx-proof.md new file mode 100644 index 0000000..fd0e0ce --- /dev/null +++ b/book/features/sphinx-proof.md @@ -0,0 +1,80 @@ +````{margin} +```{attributiongrey} Attribution +:class: attribution +This page reuses MIT licensed content from {cite:t}`sphinx-proof`. {fa}`quote-left`{ref}`Find out more here.` +``` + +```{admonition} User types +:class: tip +This section is useful for user type 3-5. +``` ++++ +{bdg-primary}`Sphinx Extension` +{bdg-link-light}`Included in TeachBooks Template ` +{bdg-link-primary-line}`Included in TeachBooks Favourites ` +```` + +# Sphinx proof + +This extensions provides an easy way to add proofs, theorem, axioms and much more to your book. It is documented on https://sphinx-proof.readthedocs.io/en/latest/. + +TeachBooks has made some small modifications to the original extension, such that it works well with translated books. + +## What does it do? + +This extension defines proofs, theorems, axioms and other similar concepts as new admonition types: + +````{prf:example} +:label: my-example + +Next, we shut down randomness in demand and assume that the demand shock +$\nu_t$ follows a deterministic path: + + +```{math} +\nu_t = \alpha + \rho \nu_{t-1} +``` + +Again, we’ll compute and display outcomes in some figures + +```python +ex2 = SmoothingExample(C2=[[0], [0]]) + +x0 = [0, 1, 0] +ex2.simulate(x0) +``` +```` + +More information can be found in the [official documentation](https://sphinx-proof.readthedocs.io/en/latest/index.html). It can be [configured in combination the TeachBooks extension to include examples with executable code and visuals](https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html). + +## Installation +To use this extenstion, follow these steps: + +**Step 1: Install the Package** + +Install the TeachBooks' version of `sphinx-exercise` package using `pip`: +``` +pip install sphinx-proof @ git+https://github.com/TeachBooks/sphinx-proof.git +``` + +**Step 2: Add to `requirements.txt`** + +Make sure that the package is included in your project's `requirements.txt` to track the dependency: +``` +sphinx-proof @ git+https://github.com/TeachBooks/sphinx-proof.git +``` + +**Step 3: Enable in `_config.yml`** + +In your `_config.yml` file, add the extension to the list of Sphinx extra extensions (**important**: underscore, not dash this time): +``` +sphinx: + extra_extensions: + . + . + . + - sphinx_proof + . + . + . +``` diff --git a/book/features/teachbooks_intro.md b/book/features/teachbooks_intro.md index 89d6b73..e521c54 100644 --- a/book/features/teachbooks_intro.md +++ b/book/features/teachbooks_intro.md @@ -5,12 +5,13 @@ This section is useful for user type 4-5. {bdg-link-secondary}`Python Package: TeachBooks` +{bdg-link-light}`Included in TeachBooks Template ` ``` ```` (teachbooks_package)= -## TeachBooks Python Package +# TeachBooks Python Package 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: diff --git a/book/features/write_online.md b/book/features/write_online.md index a50673a..3b64812 100644 --- a/book/features/write_online.md +++ b/book/features/write_online.md @@ -4,23 +4,24 @@ This section is useful for user type 3-5. ``` -{bdg-link-light}`GitHub Reusable Action: Deploy Book workflow ` -{bdg-link-light}`Part of TeachBooks Template ` +{bdg-link-light}`Uses Deploy Book workflow ` +{bdg-link-light}`Uses TeachBooks Template ` + ```` # Write book fully in GitHub interface -Using the GitHub tooling in combination with TeachBook's software, users are able to write their book fully online, without the need to install any software locally. This is especially useful for users that are not familiar with Git and GitHub, or do not have the rights to install software on their computer. To make this possible, users can start with the [TeachBooks Template](https://teachbooks.io/manual/favourites/external/template/README.html) after which they make use of the [Deploy Book Workflow](https://teachbooks.io/manual/favourites/external/deploy-book-workflow/README.html) to automatically build and release their book online. +Using the GitHub tooling in combination with TeachBook's software, users are able to write their book fully online, without the need to install any software locally. This is especially useful for users that are not familiar with Git and GitHub, or do not have the rights to install software on their computer. To make this possible, users can start with the [TeachBooks Template](https://teachbooks.io/manual/external/template/README.html) after which they make use of the [Deploy Book Workflow](https://teachbooks.io/manual/external/deploy-book-workflow/README.html) to automatically build and release their book online. ## How to do this New users can start writing their book by following the steps shown in the [TeachBooks Template repository](https://github.com/TeachBooks/template). -Users who already have a TeachBook repository can add the Deploy Book Workflow as explained [here](https://teachbooks.io/manual/favourites/external/deploy-book-workflow/README.html) +Users who already have a TeachBook repository can add the Deploy Book Workflow as explained [here](https://teachbooks.io/manual/external/deploy-book-workflow/README.html) After that, users can start writing and editing their book fully online in the GitHub interface. This is supported with: -- [Automatic book builds for all version](https://teachbooks.io/manual/favourites/external/deploy-book-workflow/README.html) +- Automatic book builds for all version. See [](./release_book_online.md) for more information - A summary describing where the TeachBook is released, errors in the build process per branch and how the release step is configured ## Example of summary diff --git a/book/references.bib b/book/references.bib index 61219ae..292c741 100644 --- a/book/references.bib +++ b/book/references.bib @@ -183,3 +183,18 @@ note = {Retrieved April, 2025. MIT License.}, } +@misc{sphinx-proof, + author = {{executablebooks}}, + title = {Sphinx Proof}, + url = {https://github.com/executablebooks/sphinx-exercise}, + year = {2024}, + note = {Retrieved September, 2025. MIT License.}, +} + +@misc{sphinx-exercise, + author = {{executablebooks}}, + title = {Sphinx Exercise}, + url = {https://github.com/executablebooks/sphinx-exercise}, + year = {2024}, + note = {Retrieved September, 2025. MIT License.}, +} \ No newline at end of file