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 description in teachbooks package

Browse source
This commit is contained in:
Tom van Woudenberg 2024-10-31 16:58:34 +01:00
parent bda88a9e31
commit ec6ca7ddf9
5 changed files with 18 additions and 76 deletions
Download patch file Download diff file Expand all files Collapse all files

2
book/_toc.yml
View file

@ -46,8 +46,6 @@ parts:
- file: external/TeachBooks/README.md
title: TeachBooks Package
- file: external/deploy-book-workflow/README.md
- file: features/remove_from_publish
- file: features/custom_toc.md
- file: features/custom_download.md
- file: external/Nested-Books/README.md
- file: external/Sphinx-Image-Inverter/README.md

2
book/external/TeachBooks vendored

@ -1 +1 @@
Subproject commit 21a67f72539aa144de54bf05b9b8d24771590771
Subproject commit 6fcc3b860e78500d74b14bc5617c2e21ac7981ac

37
book/features/custom_toc.md
View file

@ -1,37 +0,0 @@
(remove-from-publish)=
# Exclude parts of book from published book
```{admonition} User types
:class: tip
This section is useful for user type 3-5.
```
A feature to enable viewing of work-in-progress (e.g., in the draft book) or testing of content (e.g., interactive programming pages) while preventing students from seeing it is available via the {ref}`teachbooks-package <TeachBooks Python package>`. Lines of text in a `*.yml` file can be removed prior to the book build process by surrounding the lines with a tag `REMOVE-FROM-PUBLISH`. For example, pages in a draft book (e.g., `main` branch) can be manually stripped out of the table of contents when a merge request from `main` to `publish` is made. This prevents the page being included in the published book. Pages marked with this feature are still visible in the draft book and books build from source on personal computers. 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.
```{note}
The `REMOVE-FROM-PUBLISH` feature was originally deployed using Bash and Shell scripts in the pipeline of our book build processes. The MUDE book contained the scripts on the server, whereas the `interactivetextbooks-citg` contained this in the GitLab CI files or `*.sh` scripts. These workflows will eventually be replaced with a simplified pipeline setup (i.e., a GitLab CI file or GitHub workflow) that uses the commands `teachbooks build book` and `teachbook build --publish book` for the published and draft versions of the book, resepctively. We recommend you do the same. A working example can be found in our [Template repository workflow on GitHub](https://github.com/TeachBooks/deploy-book-workflow/blob/main/.github/workflows/deploy-book.yml) or in the [MUDE book on GitLab](https://gitlab.tudelft.nl/mude/book/-/blob/main/.gitlab-ci.yml?ref_type=heads).
```

26
book/installation-and-setup/jupyter-book-setup.md
View file

@ -19,7 +19,7 @@ Don't forget to add the package `teachbooks` in the `requirements.txt` files in
As soon as you've installed your book environment with jupyter-book you can build your book locally. The official <a href="https://jupyterbook.org/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book"></a> documentation is quite extensive. You can navigate to the directory where your book is to leave out the `path-to-book`.
```
teachbooks build <path-to-book> --all
teachbooks build <path-to-book>
```
Alternatively:
```
@ -45,27 +45,3 @@ Terminal
:class: tip, dropdown
Bookmark the (local) file location for easy access!
```
(setup-local-server)=
## View the book using a local webserver
```{admonition} Note
:class: tip
If your book consists only of markdown files the local python server is not necessary and you can just view the book locally.
```
Some features like JupyterLite and Grasple only work when a webserver serves the HTML content for a book. Rather than building the book in your repository and updating the website on the internet, you can use a local webserver to view the book:
1. Make sure you have the TeachBooks Python package installed (e.g., `pip install teachbooks`)
2. Start a server from the command line with: `teachbooks serve`
3. The command line output will return the URL where you can access your book
4. 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`.
5. All interactive features like the JupyterLite consoles, Grasple/H5p iframe exercises, Sphinx-thebe python interactivity and HTML/Javascript elements should now work as well.
6. When you no longer need the server, simply run `teachbooks serve stop`
### How to create a local server without the TeachBooks package
Here is how to set up a local server with only standard Python libraries:
1. Start a server from the command line with: `python -m http.server -b 127.0.0.1` (add ` &` if you want to keep using the terminal for other tasks).
2. Port 8000 is usually used by default, but depending on your OS it will tell you in the output.
3. To visit your site, just enter the address in your web browser, followed by a colon, and then the port number. By default, that would be: `127.0.0.1:8000`.
4. You will get a website that looks like a file browser, to visit your site just navigate to `book/_build/html/` (if you've started this command from this folder you see the book immediately)

27
book/workflows/edit_book.md
View file

@ -366,21 +366,30 @@ Demonstration, video available [here](https://youtu.be/2ttjBevkEP8)
2. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy!
Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
You will firstly need to actiavte the right environment. Type the following command:
`conda activate jupyter-book-env`
(or the environment in which you have installed the TeachBooks package)
Then we can build the book locally. Make sure you are in the right repository in VS code and type the folloing command:
Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command:
`jupyter-book build book`
```
teachbooks build <path-to-book>
```
Alternatively:
```
jupyter-book build <path-to-book> --all
```
Where book is the name of the folder containing all the files that make up your book. After `jupyter-book` is done running you will get the following:
Note: use `--all` for the jupyter-book whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book.
Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following:
```{figure} ../figures/buildbook.PNG
Output.
Output
```
Paste the last line into your browser to see the updated changes.
@ -391,6 +400,9 @@ Sometimes there are problems building the book. It could be that the building re
`pip install -r requirements.txt --upgrade`
```
If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server]
3. If you are satisfied with your changes, you can select the files ready to be added to Git-timeline (staging)
For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu:
@ -419,13 +431,6 @@ In the bottom left corner, next to the branch name, click the "Synchronize Chang
```{figure} ../images/git-push.png
After committing, click the 🔄 button to push our changes to the remote repository.
```{Note}
Missing from this chapter: startup python server.
You can read more about it [here](/book/installation-and-setup/jupyter-book-setup.md)
```
````
````{tab-item} ... GitHub Desktop