admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-13 23:05:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'release' into docs_external_toc

Browse source
This commit is contained in:
Tom van Woudenberg 2025-03-06 07:47:34 +01:00 • committed by GitHub
commit 271b4924fe
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
20 changed files with 286 additions and 114 deletions
Download patch file Download diff file Expand all files Collapse all files

BIN
book/features/figures/toolbar.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 3.4 KiB

46
book/features/local_server.md
View file

@ -28,6 +28,7 @@ Remember that the browser is serving static files provided by the local server a
You should reload the page if you are editing and rebuilding the book. You can try `CTRL+R` `ctrl`+`F5`. If this does not work, on Chrome try right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`.
```
(teachbooks-serve)=
## TeachBooks Server: `teachbooks serve`
If you have the TeachBooks Python package installed (`pip install teachbooks`), starting a server is as simple as:
@ -38,6 +39,51 @@ teachbooks serve
See the {ref}`TeachBooks Package page <teachbooks-serve>` for additional guidance on using the CLI tool.
By default it assumes you have a book in `./book/`, are running the command from the root `./` of your repository and will serve `./book/_build/html`. If not, it will serve the repository root. You can also specify the directory to serve:
```bash
teachbooks serve path unconventional_book_dir/_build/html
```
```{tip}
Remember that the browser is serving static files provided by the local server and does not always keep track when they are updated.
You should reload the page if you are editing and rebuilding the book. You can try `CTRL+R` `ctrl`+`F5`. If this does not work, on Chrome try right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`.
```
To stop the server, simply run
```bash
teachbooks serve stop
```
The CLI tool is set up to make the book edit and check workflow as easy as possible locally:
- you can rebuild the book without restarting the server.
- it reuses an existing server if already running.
- it prints the URL where the book is served after building the book to easily access it by clicking the link in standard output.
- the `teachbooks serve stop` command prevents Python processes running in the backgroudn and slowing down your computer (it saves the server state in a pickle file).
### Installation of TeachBooks
The TeachBooks package is currently [available on PyPI](https://pypi.org/project/teachbooks/) and can be installed as follows:
```
pip install teachbooks
```
The first stable release (`v1.0.0`) is expected to be released in Spring 2025. Until then the package is very much useable but will be updated frequently. Therefore, get in the habit of updating the package regularly:
```bash
pip install --upgrade teachbooks
```
We recommend you install this in an environment that is specifically dedicated for building books. Python virtual environments are a good way to manage this and would be consistent with what is used by the GitHub servers via the {ref}`Deploy Book Workflow <deploy-book-workflow>`. However, if you use non-Python tools to edit and check your book, a Conda environment may be a better choice.
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.
The source code and function of the package will eventually be documented on a Sphinx-built website ([teachbooks.io/TeachBooks/](https://teachbooks.io/TeachBooks/)), however, this is currently still under construction.
## Live Server: a VS Code Extension
A local server is easy to initialize directly in VS Code using the Live Server extension. Once installed, it can be activated with a "Go Live" button in the bottom right corner of VS Code. The extension will automatically serve index.html, so depending on your book build settings you may need to navigate to the correct directory/file manually using the URL address in the browser.

95
book/features/teachbooks.md
View file

@ -1,68 +1,13 @@
(teachbooks-package)=
# Pre- and postprocessing book
# Draft-Release Workflow
```{admonition} User types
:class: tip
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.
This page is useful for user type 3-5.
```
{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.
The source code and function of the package will eventually be documented on a Sphinx-built website ([teachbooks.io/TeachBooks/](https://teachbooks.io/TeachBooks/)), however, this is currently still under construction.
## Primary Features
Key features (described in the sections below) include:
- pre- and post-processing steps for the Jupyter Book package
- Draft-Release Workflow (`teachbooks build --release book`)
- Start and stop a local server to check your book (`teachbooks serve`)
This list will be updated periodically as features are added. Check the [Release Notes](https://github.com/TeachBooks/TeachBooks/releases) in the GitHub repository for the most up-to-date information.
## Installation
The package is currently only [available on PyPI](https://pypi.org/project/teachbooks/) and can be installed as follows:
```
pip install teachbooks
```
The first stable release (`v1.0.0`) is expected to be released in Spring 2025. Until then the package is very much useable but will be updated frequently. Therefore, get in the habit of updating the package regularly:
```bash
pip install --upgrade teachbooks
```
We recommend you install this in an environment that is specifically dedicated for building books. Python virtual environments are a good way to manage this and would be consistent with what is used by the GitHub servers via the {ref}`Deploy Book Workflow <deploy-book-workflow>`. However, if you use non-Python tools to edit and check your book, a Conda environment may be a better choice.
## Contribute
This tool's repository is stored on [GitHub](https://github.com/TeachBooks/TeachBooks). The `README.md` of the repository describes how you can contribute---don't hesitate to make an issue if you would like to request new features!
## Description of Features
(teachbooks-pre-post)=
### Jupyter Book Pre- and Post-Processing
Using the teachbooks CLI in the book building process generally invokes Jupyter Book. Many of the features in this package are then invoked in the stages before and after this command. The process generally includes the following steps:
1. Edit source code and prepare to build a book
2. Execute `teachbooks [OPTIONS] COMMAND [ARGS]`
3. Pre-processing step: carried out by `teachbooks`
4. Build step: book is built using `jupyter book [OPTIONS] COMMAND [ARGS]`
5. Post-processing step: carried out by `teachbooks`
Additional options like those used in jupyterbook (`--all` for example) can be used with `teachbooks` in an identical usage as with the `jupyter-book` command.
```{note}
The pre- and post-processing steps have not yet bet formally defined; they only exist implicitly in the source code for the `build` CLI command. If you are interested in suggesting a feature or contributing to the package, please visit the [GitHub repository](https://github.com/teachbooks/teachbooks) and take a look at the Discussions and Issues. For example, [this one](https://github.com/orgs/TeachBooks/discussions/28).
```
(teachbooks-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).
```{admonition} Why is this useful?
@ -107,38 +52,22 @@ Note that `teachbooks build book` would build a book without stripping the tagge
TeachBooks: running build with strategy 'draft'
```
(teachbooks-serve)=
### Local Python server
## Installation
```{tip}
Visit the {ref}`Local Server page <setup-local-server>` for an explanation of why you need a local server.
The package is currently [available on PyPI](https://pypi.org/project/teachbooks/) and can be installed as follows:
```
pip install teachbooks
```
The TeachBooks Python package includes a command line interface (CLI) that can be used to start a local server:
The first stable release (`v1.0.0`) is expected to be released in Spring 2025. Until then the package is very much useable but will be updated frequently. Therefore, get in the habit of updating the package regularly:
```bash
teachbooks serve
```
By default it assumes you have a book in `./book/`, are running the command from the root `./` of your repository and will serve `./book/_build/html`. If not, it will serve the repository root. You can also specify the directory to serve:
```bash
teachbooks serve path unconventional_book_dir/_build/html
pip install --upgrade teachbooks
```
```{tip}
Remember that the browser is serving static files provided by the local server and does not always keep track when they are updated.
We recommend you install this in an environment that is specifically dedicated for building books. Python virtual environments are a good way to manage this and would be consistent with what is used by the GitHub servers via the {ref}`Deploy Book Workflow <deploy-book-workflow>`. However, if you use non-Python tools to edit and check your book, a Conda environment may be a better choice.
You should reload the page if you are editing and rebuilding the book. You can try `CTRL+R` `ctrl`+`F5`. If this does not work, on Chrome try right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`.
```
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.
To stop the server, simply run
```bash
teachbooks serve stop
```
The CLI tool is set up to make the book edit and check workflow as easy as possible locally:
- you can rebuild the book without restarting the server.
- it reuses an existing server if already running.
- it prints the URL where the book is served after building the book to easily access it by clicking the link in standard output.
- the `teachbooks serve stop` command prevents Python processes running in the backgroudn and slowing down your computer (it saves the server state in a pickle file).
The source code and function of the package will eventually be documented on a Sphinx-built website ([teachbooks.io/TeachBooks/](https://teachbooks.io/TeachBooks/)), however, this is currently still under construction.

38
book/features/versioning.md Normal file
View file

@ -0,0 +1,38 @@
# TeachBooks Versioning
> This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
Inspired by versioning systems in software management (i.e. semantic and CalVer versioning) TeachBooks suggests a versioning guideline in which the version number tells the reader about the impact of the change. This might more suitable for your online books than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. We recommend TeachBooks versioning, which comes in two flavors:
1. `academic_year.additions.errata` versioning for books tailed-made for courses in which content is added / adapted during the course and might be restructured extensively every year while remaining to be available in the original form.
2. `major.errata` versioning for books which are more stable over years, in which big changes are covered only by the version number.
We have come up with guidelines how to use the two TeachBooks-versioning options (adapted from {cite:p}`semver`):
`````{tab-set}
````{tab-item} academic_year.additions.errata
1. A normal version number MUST take the form `academic_year.additions.errata` where `academic_year` is the academic year in which the book is used, and `additions`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 2025.9.0 -> 2025.10.0 -> 2025.11.0
2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.
3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next errata or additions version.
4. Additions version MUST be incremented if an addition is made to the book. It MUST be communicated in both the source code and in the book itself. It MAY include errata level changes. The errata version MUST be reset to 0 when the addition version is incremented.
5. Academic year version MUST be incremented if a fresh book is started for which additions will follow later. It MUST be communicated in both the source code and in the book itself. Additions and errata versions MUST be reset to 0 when academic version is incremented.
6. Precedence refers to how versions are compared to each other when ordered.
1. Precedence MUST be calculated by separating the version into academic year, additions and errata identifiers in that order.
2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Academic year, additions and errata versions are always compared numerically. Example: 2024.0.0 < 2025.0.0 < 2025.1.0 < 2025.1.1.
7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself.
An example can be seen in [the source repository of the Engineering Systems Optimization book](https://github.com/TUDelft-books/CME4501/tags) showing tags for different versions.
````
````{tab-item} major.errata
1. A normal version number MUST take the form `major.errata` where `major`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 9.0 -> 10.0 -> 11.0
2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.
3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next major version.
5. Major versions MUST be incremented if a substantial restructure or additions is made. It MUST be communicated in both the source code and in the book itself. Errata versions MUST be reset to 0 when the major version is incremented.
6. Precedence refers to how versions are compared to each other when ordered.
1. Precedence MUST be calculated by separating the version into major and errata identifiers in that order.
2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: major and errata versions are always compared numerically. Example: 1.0 < 2.0 < 2.1.
7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself.
````
`````
Read [](../installation-and-setup/versioning_changelog.md) on how to combine this with a changelog, tags and releases!

19
book/features/widgets.ipynb
View file

@ -40,7 +40,24 @@
"```python\n",
"input_slider = widgets.FloatSlider(value=0, min=0, max=10, step=1, description='Input variable:') # Defines a widget, more options than just FloatSlider\n",
"widgets.interact(update_plot, input_variable_from_widget = input_slider);\n",
"```\n"
"```\n",
"\n",
"Finally, When using `%matplotlib widget`, there's the following toolbar:\n",
"\n",
"![](./figures/toolbar.png)\n",
"\n",
"Which only shows up when you hoover above. If you want to disable the toolbar you can use:\n",
"```python\n",
"fig = plt.gcf()\n",
"fig.canvas.toolbar_visible = False\n",
"```\n",
"\n",
"If you want it to be visible even if you don't hoover above it, use:\n",
"\n",
"```python\n",
"fig = plt.gcf()\n",
"fig.canvas.toolbar_visible = True\n",
"```"
]
},
{