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

Jupyterbook v1 and teachbooks

Browse source
This commit is contained in:
Tom van Woudenberg 2025-11-03 17:48:38 +01:00
parent 4311f11d16
commit fdf2d7c5ef
57 changed files with 88 additions and 89 deletions
Download patch file Download diff file Expand all files Collapse all files

4
book/installation-and-setup/anaconda.md
View file

@ -36,7 +36,7 @@ A python virtual environment is, like the name might suggest, a reserved space w
### Set-up environments
Now we will set up your first environment. The following steps will create an Anaconda environment and install Python 3.11. Even if you already have Python 3.11, it is still good practice to create a dedicated Anaconda environment for each of your major projects such as creating a jupyter book.
Now we will set up your first environment. The following steps will create an Anaconda environment and install Python 3.11. Even if you already have Python 3.11, it is still good practice to create a dedicated Anaconda environment for each of your major projects such as creating a TeachBook.
For simplicity we will call this environment `my_new_book_env`, but you can give it any name you like.
@ -47,7 +47,7 @@ For simplicity we will call this environment `my_new_book_env`, but you can give
4. Additional 4th step: `pip install -r requirements.txt` (explanation in the following section)
Now everytime you want to work on your jupyter-book, you need to activate the environment! (step 3) If you don't activate your environment, you will work in a 'wrong' working environment that might not contain all the packages you need.
Now everytime you want to work on your TeachBook, you need to activate the environment! (step 3) If you don't activate your environment, you will work in a 'wrong' working environment that might not contain all the packages you need.
As mentioned before, python packages can be downloaded in the environments you create. Both NumPy and pandas are popular Python packages used for data manipulation and analysis. For the creation of Jupyter Books, we will use the package `teachbooks` which is a wrapper around JupyterBooks. More information about this package [here](jupyter-book-setup.md).

2
book/installation-and-setup/copyright/licenses.md
View file

@ -16,7 +16,7 @@ Here we present an overview of various license types, with a particular focus on
Since we (TeachBooks) authors have been working on making online books, we see the value in making content available for reuse. When preparing a new page or assignment, nothing makes us happier than seeing a CC BY license on something that we would like to (re)use ourselves. Why? Because we know that all we have to do is properly attribute the work and we can get on with our true passion: **teaching!**
```
This page is written expressly for content authors of online interactive textbooks (e.g., those including, but not restricted to, Jupyter Books), which are composed of two parts:
This page is written expressly for content authors of online interactive textbooks (e.g., those including, but not restricted to, TeachBooks), which are composed of two parts:
1. An online document in the form of a website, accessible at a specific URL, and
2. The _source code,_ which defines the _content_ and is required to create the website.

2
book/installation-and-setup/copyright/recommendations.md
View file

@ -22,7 +22,7 @@ The recommendations on this page are designed for content that is available in t
## Key Locations in the Book
Note that there are several types of pages and files that can be incorporated into your TeachBook which, together, accomplish our goals of proper attribution and referencing. These are summarized in the table and explained in more detail in the following sections, along with examples for implementation in a Jupyter Book.
Note that there are several types of pages and files that can be incorporated into your TeachBook which, together, accomplish our goals of proper attribution and referencing. These are summarized in the table and explained in more detail in the following sections, along with examples for implementation in a TeachBook..
```{list-table} Key Locations in the Book for Attribution and Referencing Best Practices
:header-rows: 1

2
book/installation-and-setup/git-setup_local.md
View file

@ -113,7 +113,7 @@ And type the following command to set the email address:
## GitHub Desktop
GitHub is a competitor company to GitLab. It provides very similar services, but they are often called different names, or have slightly different features. GitHub provides a free software that is very useful: [GitHub Desktop](https://desktop.github.com/)! While GitLab is a cloud-based version control system built around Git, GitHub Desktop makes it possible to manage our Git repositories locally on our computers, even though they are stored on GitLab. This is very useful for working with the jupyter-book more extensively and work on interactive features. GitHub Desktop provides an alternative to Git in VS Code, and will be described on a later stage.
GitHub is a competitor company to GitLab. It provides very similar services, but they are often called different names, or have slightly different features. GitHub provides a free software that is very useful: [GitHub Desktop](https://desktop.github.com/)! While GitLab is a cloud-based version control system built around Git, GitHub Desktop makes it possible to manage our Git repositories locally on our computers, even though they are stored on GitLab. This is very useful for working with the TeachBook more extensively and work on interactive features. GitHub Desktop provides an alternative to Git in VS Code, and will be described on a later stage.
## Terminology
This is a (non-exhaustive) list of terminology that will be used in Git for local use.

2
book/installation-and-setup/git_bash_conda_vs-code.md
View file

@ -8,7 +8,7 @@ This page is useful for user type 5.
# Combining Git Bash, VS Code and Conda
## Conda in Git Bash
Git Bash is a shell (also referred to as "the terminal") that is automatically installed with git. It provides Unix-like commands on a Windows OS, and is recommended for working with open source projects like Jupyter (for example `pip install`, building Jupyter books, using Git Bash in VS Code, etc). To do this, `conda` needs to be setup properly; this is described here:
Git Bash is a shell (also referred to as "the terminal") that is automatically installed with git. It provides Unix-like commands on a Windows OS, and is recommended for working with open source projects like Jupyter (for example `pip install`, building TeachBooks, using Git Bash in VS Code, etc). To do this, `conda` needs to be setup properly; this is described here:
(vscode-setup-bash)=
````{tab} Windows - Git Bash (preferred)

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

@ -7,9 +7,9 @@ This page is useful for user type 5.
# Build your book: JupyterBook
<a href="https://jupyterbook.org/v1/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book"></a> is a regular Python package which converts our content into a website. It's part of all of the `requirements.txt` files for a book repository. At TeachBooks we developed a Python package called `teachbooks` which takes over the these features and adds [additional features](../features/overview.md). One of those additional features, for example, is the workflow to GitHub Pages.
<a href="https://jupyterbook.org/v1/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book v1"></a> is a regular Python package which converts our content into a website. It's part of all of the `requirements.txt` files for a book repository. At TeachBooks we developed a Python package called `teachbooks` which takes over the these features and adds [additional features](../features/overview.md). One of those additional features, for example, is the workflow to GitHub Pages.
Concretely, this means that the teachbooks package can be used to replace the <a href="https://jupyterbook.org/v1/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book"></a> package when calling these features. You could think of it as `jupyter-book` being a dependency of `teachbooks`.
Concretely, this means that the teachbooks package can be used to replace the <a href="https://jupyterbook.org/v1/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book v1"></a> package when calling these features. You could think of it as `jupyter-book` being a dependency of `teachbooks`.
```{admonition} Note
:class: tip
@ -18,7 +18,7 @@ Don't forget to add the package `teachbooks` in the `requirements.txt` files in
## Build a book
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/v1/"><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`.
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/v1/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book v1"></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>

2
book/installation-and-setup/overview.md
View file

@ -16,4 +16,4 @@ The following table will link the relevant installation and setup steps for you.
| Type 1<br>Type 2 | Review book | No software needed! Just open your interactive book online and give a review in the way you're asked to |
| Type 3 | Edit single files online | No software needed! But you'll interact with Git, which might be a new thing for you |
| Type 4 | Editing text<br>Git| VS Code<br>GitHub Desktop / Git in VS Code |
| Type 5 | Editing text<br>Git<br>Managing code-related software<br>Build your book | VS Code<br>GitHub Desktop / Git in VS Code<br>Anaconda<br>Jupyter Book |
| Type 5 | Editing text<br>Git<br>Managing code-related software<br>Build your book | VS Code<br>GitHub Desktop / Git in VS Code<br>Anaconda<br>Jupyter Book/Sphinx |

4
book/installation-and-setup/user_types.md
View file

@ -1,6 +1,6 @@
# User types
Different types of users will interact with the website or the Jupyter Books differently and will therefore need to know more or less about the composition of the book. For now we will differentiate 5 types of users.
Different types of users will interact with the website or the TeachBooks differently and will therefore need to know more or less about the composition of the book. For now we will differentiate 5 types of users.
## User type 1: Students providing feedback via the book website
@ -32,7 +32,7 @@ class: dark-light
```
In a similar manner as students, colleagues and team members can leave content-related comments on the website through extensions or GitHub/GitLab features (e.g., Issues). In this way, multiple teachers can give input in the draft of the textbook and course material without requiring a complete understanding of Jupyter Books or GitLab/GitHub. The responsible teacher (or student assistants) can then make adaptations to the book as recommended by their colleagues.
In a similar manner as students, colleagues and team members can leave content-related comments on the website through extensions or GitHub/GitLab features (e.g., Issues). In this way, multiple teachers can give input in the draft of the textbook and course material without requiring a complete understanding of TeachBooks or GitLab/GitHub. The responsible teacher (or student assistants) can then make adaptations to the book as recommended by their colleagues.
## User type 3: Colleague making adjustments via the browser

2
book/installation-and-setup/vscode-setup.md
View file

@ -15,7 +15,7 @@ VS Code can be downloaded from [here](https://code.visualstudio.com). The instal
## Extensions
When working with Jupyter Book (or Notebooks in general), these extensions are highly recommended:
When working with TeachBooks (or Jupyter Notebooks in general), these extensions are highly recommended:
- User type 4-5:
- [MyST-Markdown](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) - adds support for MyST markdown, including previews.