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

teachbooks info on overview page and manual/features/teachbooks URL breaks

Browse source 
Update teachbooks.md
This commit is contained in:
Robert Lanzafame 2025-03-23 08:35:08 +01:00 • committed by GitHub
commit 9b74a256e1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 36 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

3
book/_toc.yml
View file

@ -98,7 +98,6 @@ parts:
sections:
- file: external/annotater/README.md
- file: basic-features/hypothesis.md
- file: features/teachbooks
- caption: Examples
chapters:
@ -127,4 +126,4 @@ parts:
- file: references.md
- file: credits
- file: changelog
- file: contact
- file: contact

4
book/features/draft-release.md
View file

@ -6,7 +6,7 @@
This page is useful for user type 3-5.
```
{bdg-link-secondary}`Python Package: teachbooks <./teachbooks.html>`
{bdg-link-secondary}`Python Package: teachbooks <./overview#teachbooks-python-package>`
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).
@ -70,4 +70,4 @@ We recommend you install this in an environment that is specifically dedicated f
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.
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.

2
book/features/external_toc.md
View file

@ -6,7 +6,7 @@
This page is useful for user type 3-5.
```
{bdg-link-secondary}`Python Package: teachbooks <./teachbooks.html>`
{bdg-link-secondary}`Python Package: teachbooks <./overview#teachbooks-python-package>`
## Introduction

4
book/features/local_server.md
View file

@ -6,7 +6,7 @@
This section is useful for user type 4-5.
```
{bdg-link-secondary}`Python Package: teachbooks <./teachbooks.html>`
{bdg-link-secondary}`Python Package: teachbooks <./overview#teachbooks-python-package>`
Perhaps you have already noticed that when building a book and testing it locally on your computer, some features do not work the way you expect, or worse---do not work at all! This is because many interactive features rely on browser functionality to work properly, for example: Grasple/H5p iframe exercises, Sphinx-Thebe Python interactivity and HTML/Javascript elements. Although the website is _static_ (i.e., there is no code running on a webserver that generates the content), modern web browsers have their own internal computing environments that run processes to deliver the rich content we desire in our books.
@ -138,4 +138,4 @@ A Windows-specific command for the CMD prompt or Powershell is:
```
TASKKILL /IM python.exe /F
```
```

32
book/features/overview.md
View file

@ -13,7 +13,7 @@ Additionally, not all features are built and shared in the same way. We do our b
- {bdg-warning}`Javascript overlay`
- {bdg-success}`Chrome Extension`
- {bdg-white}`GitHub App and Javascript script`
- {bdg-link-secondary}`Python Package: teachbooks <./teachbooks.html>`
- {bdg-link-secondary}`Python Package: teachbooks <./overview.html#teachbooks-python-package>`
- {bdg-light}`GitHub Reusable Action`
- {bdg-light}`GitHub Template`
- {bdg-dark}`Git Workflow`
@ -22,4 +22,32 @@ Additionally, not all features are built and shared in the same way. We do our b
Finally, the purpose, installation process and usage of each features is elaborated on in the respective sub-sections.
To see examples for these features, go to the [Examples chapter](../examples/overview.md).
To see examples for these features, go to the [Examples chapter](../examples/overview.md).
(teachbooks_package)=
## TeachBooks Python Package
```{admonition} User types
:class: tip
This section is useful for user type 4-5.
```
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](./teachbooks-template.md). This raises two important points:
1. If you are a book user using the [TeachBooks Template](./teachbooks-template.md) or the [Deploy Book Workflow](./deploy-book-workflow.md), your book is by default built with the `teachbooks` package, and the way your book is built and features that are included in the book may change automatically when it is updated (these will be non-breaking changes; if not, we will notify our mailing list).
2. If you are using the `jupyter-book` package to build your book, some of the features described in this Manual may not be available to you (i.e., those listed on this page). This will be the case if you are using a [setup described in the Jupyter Book Manual](https://jupyterbook.org/en/stable/publish/web.html), for example, [this GitHub workflow](https://jupyterbook.org/en/stable/publish/gh-pages.html).
For those who wish to use the package, it is available on [PyPI](https://pypi.org/project/teachbooks/) and can be installed using `pip install teachbooks`. It adds a few commands to the CLI (e.g., `serve`), but otherwise is meant to be used instead of the `jupyter-book` commands. It is conventionally used in an identical way:
```
teachbooks build book
```
### List of Features
Items in the list here are currently implemented in the TeachBooks package and described on other pages of this manual:
- Draft-Release Workflow: read more here
- External Contents:
- Local Server:
The package is also set up to handle [APA references](./apa) when using the Draft-Release Workflow (the `_ext` subdirectory and its contents are manually copied during the pre-build phase). This will not be necessary once the APA Reference feature is turned into a proper Sphinx extension or Pybtext plugin.

28
book/features/teachbooks.md
View file

@ -1,28 +0,0 @@
# TeachBooks Python Package
```{admonition} User types
:class: tip
This section is useful for user type 4-5.
```
{bdg-secondary}`Python Package: teachbooks`
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](./teachbooks-template.md). This raises two important points:
1. If you are a book user using the [TeachBooks Template](./teachbooks-template.md) or the [Deploy Book Workflow](./deploy-book-workflow.md), your book is by default built with the `teachbooks` package, and the way your book is built and features that are included in the book may change automatically when it is updated (these will be non-breaking changes; if not, we will notify our mailing list).
2. If you are using the `jupyter-book` package to build your book, some of the features described in this Manual may not be available to you (i.e., those listed on this page). This will be the case if you are using a [setup described in the Jupyter Book Manual](https://jupyterbook.org/en/stable/publish/web.html), for example, [this GitHub workflow](https://jupyterbook.org/en/stable/publish/gh-pages.html).
For those who wish to use the package, it is available on [PyPI](https://pypi.org/project/teachbooks/) and can be installed using `pip install teachbooks`. It adds a few commands to the CLI (e.g., `serve`), but otherwise is meant to be used instead of the `jupyter-book` commands. It is conventionally used in an identical way:
```
teachbooks build book
```
## List of Features
Items in the list here are currently implemented in the TeachBooks package and described on other pages of this manual:
- Draft-Release Workflow: read more here
- External Contents:
- Local Server:
The package is also set up to handle [APA references](./apa) when using the Draft-Release Workflow (the `_ext` subdirectory and its contents are manually copied during the pre-build phase). This will not be necessary once the APA Reference feature is turned into a proper Sphinx extension or Pybtext plugin.