Update book/_toc.yml to move the TeachBooks-Fetch MANUAL.md external entry into the features/visuals section and remove the duplicate entry later in the file. This tidies the table of contents and ensures the Fetch manual is grouped with the visuals-related externals.
Include TeachBooks-Fetch in the documentation and favourites list: add its MANUAL external link to book/_toc.yml and add a favourites entry in book/features/favourites.md so the extension is discoverable from the docs.
Add TeachBooks-Questions to the book TOC and TeachBooks Favourites list, and include Sphinx Gated Directives and TeachBooks Zoomies in the favourites page. Also tidy requirements.txt by removing an inline bump comment from the TeachBooks-Favourites git dependency. Changes touch book/_toc.yml, book/features/favourites.md, and requirements.txt to surface the new/manual links and clean up metadata.
Switched teachbooks dependency to use a specific Git branch (issue-127) instead of the released version. This allows for testing or using unreleased changes from the repository.
Cleaned up book/_config.yml by removing unused or unnecessary Sphinx configuration options related to sphinx_gated_directives and sphinx_codex. This helps simplify the configuration file.
The sphinx_tudelft_theme extension has been removed from the list of Sphinx extensions in the configuration file, possibly because it is no longer needed or has been replaced.
Deleted the custom 'include_remove_yaml' Sphinx extension and its configuration. Cleaned up YAML front matter from intro.md. Updated requirements.txt to use released teachbooks package, added sphinx-gated-directives, and removed duplicate or outdated dependencies.
Introduced a custom Sphinx extension 'include_remove_yaml' to strip YAML front matter from included files. Updated _config.yml to register the extension, and added YAML front matter to intro.md for demonstration.
Deleted instructie.ipynb, instructie_2.ipynb, and lesoefeningen.ipynb from the book. Updated _toc.yml to remove references to these files and moved the Sphinx-Gated-Directives manual link to the correct section. Minor update to intro.md.
Added an external manual link to the table of contents. Updated requirements to use TeachBooks from the 'issue-127' branch and adjusted comments for clarity.
Removed the local sphinx_gated_directives extension and updated configuration to use the external package. Added Sphinx-Gated-Directives as a dependency in requirements.txt and adjusted _config.yml to load it as an extra extension.
Deleted the code-align.css file that enforced left alignment for docutils code cells. Updated the requirements.txt comment for TeachBooks-Favourites to reference 'patches' instead of 'codex'.
Extracted suffix_separator, suffix_start, and suffix_end from cfg to local variables for improved readability and maintainability in directive name construction.
Extracted suffix_separator, suffix_start, and suffix_end from cfg at the start of the function to avoid repeated dictionary lookups and improve code readability.
Refactor the sphinx_gated_directives extension to support configurable suffixes and separator for start/end directives, and add an 'override_existing' option for more flexible directive registration. Update the registry naming and logic throughout the extension, add configuration validation, and update the book config and intro to demonstrate new exercise directives and nesting.
Improved code structure and comments in sphinx_gated_directives/__init__.py, clarified logic, and removed unused/legacy code. Updated intro.md to remove commented-out directive examples and replaced them with active ones for better demonstration and testing.
Changed the label from 'A child theorem' to 'A child axiom' in the intro.md file for clarity. Added 'sphinx-tudelft-theme==1.2.1' to requirements.txt to specify the documentation theme.
Added a robust validate_SE function to check for correct nesting of start and end directives, with detailed error reporting. Updated the CheckGatedDirectivesTransform to use this validation and improved error messages for mismatched or incorrectly nested directives. Extended intro.md with comprehensive examples of nested directives, including both valid and invalid cases, to document and test the new behavior. Also added the sphinx_tudelft_theme extension in _config.yml.
Added a new SVG file 'nothing.svg' and updated the intro.md to use this image in place of the previous logo-wide.svg. Adjusted figure attributes and alt text accordingly.
Debug logging statements were removed from MergeGatedDirectivesTransform in sphinx_gated_directives. The intro.md file was updated to include new theorem and figure directive examples, code cells, and additional documentation content.
Commented out the code related to the 'sphinx_gated_directives_registry' in favor of using only the 'sphinx_gated_directives_super_registry'. Updated purge and transform logic accordingly. Added clarifying comments to code-align.css regarding left alignment enforcement.
Introduces the custom Sphinx extension 'sphinx_gated_directives' for start/end directive gating and validation, registering it in the Sphinx local extensions. Also adds a CSS file to enforce left alignment for code cells. Updates _config.yml to configure the new extension and set the documentation language to English.
Pinned TeachBooks-Favourites to version v1.7.3 in requirements.txt for reproducibility. Added a missing comma and newline in references.bib to correct BibTeX formatting.
author:TeachBooks Development Team and TeachBooks users, built with <a href="https://teachbooks.io/">TeachBooks</a>, <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer"">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt=""></a>
@ -28,7 +28,7 @@ This page is useful for user type 3-5.
(draft-release)=
# Draft-Release Workflow
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 <deploy-book-workflow>`, which builds our TeachBooks).
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 <deploy-book-workflow>`, which builds our TeachBooks).
- [Sphinx to do (from core sphinx](https://www.sphinx-doc.org/en/master/usage/extensions/todo.html)
The extension [Open in new tab](https://pypi.org/project/sphinx-new-tab-link/) is nice, but is not compatible with all setups (dependency clash) so is not included in TeachBooks-Favourites.
"The use of the [plotly](https://plotly.com/python/getting-started/) package is an example which allows you to create HTML/Javascript widgets from python code without any knowledge on HTML/Javascript."
"The use of the [plotly](https://plotly.com/python/getting-started/) package is an example which allows you to create HTML/Javascript widgets from python code without any knowledge on HTML/Javascript. The example below is taken from the FEM-module by Frans van der Meer."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The example below is taken from the FEM-module by Frans van der Meer.\n",
"When using Plotly graphs, make sure the notebook is executed in Jupyter Lab / Jupyter Notebook for the figures to be shown in the book. Running the code in VS code might break the result in the book, although the output is visible in VS code. Alternatively, add the following lines of code to your notebook to have a valid output in the book as well:\n",
"If you want to create the plot during the build of the book, don't use `fig.show()` but use the code below:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import os\n",
"from IPython.display import HTML\n",
"\n",
"def show_plotly(fig):\n",
" # Use HTML when building book in CI environment\n",
" # Local execution in Jupyter Notebook / JupyterLab / VS Code\n",
" fig.show()\n",
"\n",
"....\n",
"\n",
"show_plotly(fig)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Make sure you have in your `_config.yml`:\n",
"\n",
"```yaml\n",
"execute:\n",
" execute_notebooks: \"auto\"\n",
"```\n",
"\n",
"Eventually in combination with [](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.md)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Alternatively, you can run the notebook locally before building the book. This is not recommended for the combination with git because you will be committing binary output to the repository. When pre-generating Plotly graphs, make sure the notebook is executed in Jupyter Lab / Jupyter Notebook for the figures to be shown in the book. Running the code in VS code might break the result in the book, although the output is visible in VS code. Add the following lines of code to your notebook to have a valid output in the book as well:\n",
@ -9,26 +9,26 @@ This page is useful for user type 4-5.
The setup of tools and URLs is dependent on agreements you've made on [collaboration](./collab.md).
Choosing between GitHub and GitLab depends on multiple criteria. GitHub provides more functionalities, but you might prefer the TU Delft-closed GitLab system if you're a TU Delft employee.
Choosing between GitHub and GitLab depends on multiple criteria. GitHub provides more functionalities, but you might prefer the TU Delft(-closed) GitLab system if you're a TU Delft employee.
## Account
GitHub is owned by Microsoft and anyone can make an account. This allows anyone to interact with the source code of your book by posting issues, forking (duplicating while allowing to sync) your book and suggesting changes with pull requests.
For the TU-Delft closed GitLab system only TU Delft account holders can interact with the source code your book, making it not as open as GitHub: collaboration and reuse is inly pissible with manual exports of the source code. Individual external accounts can be requested for.
For the TU-Delft closed GitLab system, only TU Delft account holders can interact with the source code your book, making it not as open as GitHub: collaboration and reuse is only possible with manual exports of the source code. Individual external accounts can be requested for.
## Book URL
Github allows you to host your book on the GitHub server using GitHub pages (to be recognized by the `<organization/username>.github.io/<book>` url, for example the [template book](https://teachbooks.github.io/template/)), which takes all the steps of hosting out of your hands. Next to GitHub-provided URLs, you can set up a custom owned URL, although this requires some additional skills on a domain which you should own.
If you're part of TU Delft, you can put your book in the [TUDelft-Book organisation](https://github.com/tudelft-books), which allows you to host your book at `oit.tudelft.nl/<book>`. If you've a private book which is part of the [GitHub Enterprise TU Delft](https://github.com/enterprises/tudelft) and is using SSO, a random url is generated `<random>.github.io/<book>`. For courses we advise you to create a organization with the course name so that the URL represent that course.
If you're part of TU Delft, you can put your book in the [TUDelft-Book organisation](https://github.com/tudelft-books), which allows you to host your book at `oit.tudelft.nl/<book>`. If you've a private book which is part of the [GitHub Enterprise TU Delft](https://github.com/enterprises/tudelft) and is using SSO, a random url is generated `<random>.github.io/<book>`. For courses we advise you to create an organization with the course name so that the URL represent that course.
On TU Delft's GitLab you need a webserver, which was offered by TeachBooks in the past (to be recognized by the url `teachbooks.tudelft.nl/<book>`), and is still offered by the TU Delft OIT team (to be recognized by the url `interactivetextbooks.tudelft.nl/<book>`).
## Real-time editing book
Editing the book can happen both locally as online on GitHub/GitLab. If done locally, the book can be generated and viewed locally too (typically takes around 1 minute) but this requires you to be at least user type 4 or 5 depending on the book content. The built book can also be viewed online separate from the released version.
Editing the book can be done both locally and online on GitHub/GitLab. If done locally, the book can be generated and viewed locally too (typically takes around 1 minute) but this requires you to be at least user type 4 or 5 depending on the book content. The built book can also be viewed online separate from the released version.
On GitHub we developed a [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). For a private repository, there is an extensive but limited amount of actions-minutes required for published your book. If this proves to be a limit, consider applying for [Teacher benefits](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers) or joining the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft).
On GitHub we developed an [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). For a private repository, there is an extensive but limited amount of actions-minutes required for publishing your book. If this proves to be a limit, consider applying for [Teacher benefits](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers) or joining the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft).
On GitLab a webserver is required to process book-changes online. Both we and other people at TU Delft have a simplistic workflow which can be used when you're set up on those Git environments and webservers. This simplistic workflow doesn't build all branches, is not easily adaptable, doesn't cache environments, doesn't give a visual summary, and doesn't allow for parallel processes (for every build a runner needs to be assigned for which there's typically only one available). If you want to use GitLab but still want to make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in an active editing-phase since constant copyright checks have to be performed. The amount of computing power available is dependent on how you set the server yourself.
For GitLab a webserver is required, if GitLab pages is not enabled, to process book-changes online. Both we and other people at TU Delft have a simplistic workflow which can be used when you're set up on those Git environments and webservers. This simplistic workflow doesn't build all branches, is not easily adaptable, doesn't cache environments, doesn't give a visual summary, and doesn't allow for parallel processes (for every build a runner needs to be assigned for which there's typically only one available). If you want to use GitLab but still want to make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in an active editing-phase since constant copyright checks have to be performed. The amount of computing power available is dependent on how you set the server yourself.
## Setting up book repository and website
On GitHub you can start right away with a git environment and online book using our [template](../external/template/README.md) without the need for any webserver setup!
@ -6,8 +6,10 @@ If you plan on maintaining only one public version, it is advisable to set `BEHA
To share the built book / website of old versions for your book on GitHub you have a few options:
- Create a branch for each version. When doing this, [the GitHub workflow](../external/deploy-book-workflow/README.md) will build it on GitHub pages. Here's a few tips:
- It's advised to use the version as branch name. In case of versions per academic year, you can just name each branch to the current academic year, this leads to the URL with the same academic year..
- It is recommended to update the primary branch as the `PRIMARY BRANCH` when using the [GitHub workflow](gh-workflow-settings) whenever a new version is considered to be the most primary one. This ensures that readers are redirected to a consistent URL, even when new versions of the book are added later.
- It's advised to use the version as branch name, making it very clear which branch to which website. In case of versions per academic year, you can just name each branch to the current academic year, this leads to the URL with the same academic year. In case of book which are more stable over year, you could consider a simpler v1.1. See the page on [TeachBooks versioning](./versioning_changelog.md) for more information about how to name versions (and thus branches).
- You might consider a draft version for each version, in which you collect contributions leading up to a new release of the non-draft versoin. It's advised to name the draft branches so that the link with the non-draft version is obvious. Furthermore, you might consider the [Draft-Release Workflow](../features/draft-release.md)
- Whenever a new version is considered to be the most primary one, it is recommended to update the branch `PRIMARY BRANCH` when using the [GitHub workflow](gh-workflow-settings). This ensures that readers which have visited your book before are redirected to a consistent URL, even when new versions of the book are added later. Furthermore, it revert new readers to the most primary one.
- Set the primary branch (or its draft branch) as the default branch in git, so that that branch is directly visible when people visit your repository. Furthermore, this is probably the branch where you'd like contributers to start from when forking / opening a pull request.
- Eventually, you can add old branches to the list of `BRANCHES_ARCHIVED` when using the [GitHub workflow](gh-workflow-settings) to include a banner on the page indicating its archived state. Alternatively, you can add a banner manually to `_config.yml`, as explained [here](../basic-features/banner.md).
- If you're using tags (as will be explained in [later](./versioning_changelog.md)), you can create a branch from a tag locally by running: `git branch <new_branch name> <tag/version>`.
- If you have many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store.
