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

update teachbooks info

Browse source
This commit is contained in:
Robert Lanzafame 2024-12-11 06:06:01 +01:00
parent 9ae8a35563
commit 8ffb0816c7
3 changed files with 231 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

3
book/_toc.yml
View file

@ -44,8 +44,9 @@ parts:
- file: basic-features/utterances.md
- file: features/easy-editing.md
sections:
- file: external/TeachBooks/README.md
- file: features/teachbooks
- file: external/deploy-book-workflow/README.md
- file: features/local_server
- file: external/Nested-Books/README.md
- file: features/sphinx_extensions.md
sections:

95
book/features/local_server.md Normal file
View file

@ -0,0 +1,95 @@
(setup-local-server)=
# Use a Local Server
```{admonition} User types
:class: tip
This section is useful for user type 4-5.
```
{bdg-secondary}`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.
Technically what is needed to facilitate this during the editing and checking of your book locally is a **static web server** that can serve the files in the `./book/_build/html` directory of your book (this subdirectory is created as a result of the command `build book`). We refer to this as a **local server** because it is running on your local machine.
```{admonition} Why do you need a local server?
:class: tip
A Jupyter Book is really just a _static website._ This means that all book content _and interactivity_ is available via the (static) files that are provided to you by a webserver when you visit a specific URL. After this initial request, all required files are available in your web browser, however, some features require the request and response protocol to work properly.
```
We recommend you use the **TeachBooks Python Package**, which has a `serve` command in the CLI tool to start and stop local servers. Find out more on {ref}`the TeachBooks Package page <teachbooks-serve>`.
This page presents just a few additional examples that are used by TeachBooks collaborators. There are many more options available out there, for example, [this list illustrates many esrvers that can be activated with a single line of code!](https://gist.github.com/willurd/5720255).
```{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`.
```
## TeachBooks Server: `teachbooks serve`
If you have the TeachBooks Python package installed (`pip install teachbooks`), starting a server is as simple as:
```bash
teachbooks serve
```
See the {ref}`TeachBooks Package page <teachbooks-serve>` for additional guidance on using the CLI tool.
## 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.
````{admonition} Install Live Serve Extension
:class: tip
You can install this extension by searching for `Live Server` (or even easier, extension ID `ritwickdey.LiveServer`)in the Visual Studio Code extensions marketplace.
```{figure} https://github.com/ritwickdey/live-server-web-extension/raw/master/img/icon.png
---
width: 10%
name: live-server-icon
```
````
## Python Server: `python -m http.server`
The Python standard library has a built-in server that can be activated from the command line. This is a simple way to serve a book locally
```
python -m http.server
```
If you don't mind typing a bit more, you can specify the port number and the directory to serve:
```
python -m http.server 8000 --directory book/_build/html
```
This is actually what the `teachbooks serve` command is using, but there we have added additional features to make the process more user-friendly for the book edit and check workflow.
### Stopping the Python Server
It can be challenging to stop the Python server, especially when using Windows OS. Even though you may force end the process (e.g., with `CMD+C`), the server may still be running in the background.
For Mac and Linux users (or for Windows if you have Git Bash installed or another Unix-type terminal), you can try this:
```bash
pid=$(ps aux | grep http.server | head -n 1 | awk '{ print $2 }')
kill -9 $pid
```
Or this:
```bash
tskill python
```
A Windows-specific command for the CMD prompt or Powershell is:
```
TASKKILL /IM python.exe /F
```

142
book/features/teachbooks.md
View file

@ -1,18 +1,144 @@
(teachbooks-package)=
# TeachBooks: Our Custom Python Package
# TeachBooks Package
```{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.
```
{bdg-secondary}`Python Package`
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:
TeachBooks has created a Python package and released it on PyPI. It can easily be used like this:
```
pip install teachbooks
```
The source code is hosted in a repository on GitHub, [github.com/teachBooks/teachbooks](https://github.com/teachBooks/teachbooks), and is accompanied by a documentation website, [teachbooks.github.io/TeachBooks/](https://teachbooks.github.io/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:
The features and documentation will increase with time; until then, note there are two important reasons to use the teachbooks package:
1. Use the `REMOVE-FROM-PUBLISH` feature to more easily maintain draft and published versions of your TeachBook (see {ref}`this page <remove-from-publish>` for more details).
2. Easily start and stop a local Python server to better test your book while writing (e.g., the interactive Python features require a local server to properly check certain TeachBooks features)
```bash
pip install --upgrade teachbooks
```
For case 1, the `teachbooks` package is meant to be used instead of `jupyter book build book` to build your book (it executes `jupyter book build book` for you).
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.
Case 2 is meant to be used independently, for example, once you have successfully built a book, simply run `teachbooks serve` and open the resulting URL that is printed in the terminal. To stop the server use `teachbooks serve stop`; see {ref}`this page <setup-local-server>` for additional explanation for how to use this feature and why it is needed.
## 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?
:class: tip
Consider a case where you have been using two branches to develop and maintain a book: `release` (shared with students) and `draft` (shared with colleagues to review contents before release). You are probably also using other branches to develop contents, but rely on the `draft` branch as a way to collect the "finalized-but-not-yet-released" material. Things go smoothly as long as you add pages to the `draft` branch one at a time, then merge the branch into `release` as they are needed.
But what happens when you have 2 pages: one is ready to share with students, but the other is still being reviewed by your colleague. The only way to get the proper page into release is to comment the undesired page in the ToC using a commit on `draft`, merge the commit into `release`, then uncomment the ToC in a new commit on `draft`. This is very tedious, and prone to error as there it is not straightforward to tell which pages are available in the `draft` versus `release` books!
The Draft-Release workflow solves this problem by using commented tags to clearly denote which pages are available in the `draft` book and which are left out of the `release` book.
```
The workflow is enabled by a `teachbooks` CLI feature that identifies and removes any lines from the files `_config.yml` and `_toc.yml` file that are surrounded by `REMOVE-FROM-RELEASE` tags.
For example, pages in a developed book (e.g., `draft` branch) can be manually stripped out of the table of contents when a merge request from `draft` to `release` is made. This prevents the page being included in the released book. Pages marked with this feature are still visible in the `draft` book. Lines tagged in the configuration file `_config.yml` can be used in exactly the same manner. The tag is applied as follows:
```
format: jb-book
root: intro
parts:
- caption: ...
chapters:
- file: ...
...
# START REMOVE-FROM-PUBLISH
- file: files_to_remove
# END REMOVE-FROM-PUBLISH
```
There is no limit to the number of stripped sections, they can be sequential and indentation does not matter.
To invoke the tag and remove content during the book build process, use the following optional argument when building the book with the `teachbooks` package:
```
teachbooks build --publish book
```
Note that `teachbooks build book` would build a book without stripping the tagged lines, just as `jupyter-book build book` would. This is called "draft mode" and is the default behavior. You can recognize it in the stdout after running the `build` command:
```bash
TeachBooks: running build with strategy 'draft'
```
(teachbooks-serve)=
### Local Python server
```{tip}
Visit the {ref}`Local Server page <setup-local-server>` for an explanation of why you need a local server.
```
The TeachBooks Python package includes a command line interface (CLI) that can be used to start a local server:
```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
```
```{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).