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

Merge pull request #20 from TeachBooks/languages

Browse source 
Languages
This commit is contained in:
Tom van Woudenberg 2024-11-29 11:36:46 +01:00 • committed by GitHub
commit aacdf99146
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
27 changed files with 193 additions and 27 deletions
Download patch file Download diff file Expand all files Collapse all files

20
book/_toc.yml
View file

@ -26,7 +26,8 @@ parts:
- file: installation-and-setup/creating_content.md
- caption: Features
chapters:
- file: basic-features/overview
- file: features/overview.md
- file: basic-features/overview.md
sections:
- file: basic-features/jupyterbook.md
- file: basic-features/figures.md
@ -37,18 +38,19 @@ parts:
- file: basic-features/Code_block_figures
- file: basic-features/banner
title: Banner or Announcement
- file: basic-features/external-features.md
sections:
- file: basic-features/hypothesis.md
- file: basic-features/utterances.md
- file: features/overview.md
- file: features/easy-editing.md
sections:
- file: external/TeachBooks/README.md
- file: external/deploy-book-workflow/README.md
- file: external/Nested-Books/README.md
- file: features/sphinx_extensions.md
sections:
- file: external/Download-Link-Replacer/README.md
- file: external/Sphinx-Image-Inverter/README.md
- file: external/JupyterBook-Patches/README.md
- file: external/Sphinx-TUDelft-theme/README.md
- file: external/teachbooks-sphinx-tippy/README.md
- file: features/custom-launch-button.md
- file: features/interactive_element.ipynb
sections:
- file: external/Sphinx-Grasple-public/README.md
@ -61,6 +63,12 @@ parts:
sections:
- file: features/widgets.ipynb
- file: features/exercise_checking.ipynb
- file: features/visuals.md
sections:
- file: external/Sphinx-Image-Inverter/README.md
- file: external/JupyterBook-Patches/README.md
- file: external/Sphinx-TUDelft-theme/README.md
- file: external/teachbooks-sphinx-tippy/README.md
- file: features/students
sections:
- file: external/annotater/README.md

8
book/basic-features/external-features.md Normal file
View file

@ -0,0 +1,8 @@
# Externally Developed Features
```{admonition} User types
:class: tip
This section is useful for user type 1-5.
```
This chapter includes features useful for books in the educational context, developed by various parties.

2
book/basic-features/hypothesis.md
View file

@ -1,5 +1,7 @@
# Making comments on the website: Hypothesis
{bdg-warning}`Javascript overlay` {bdg-success}`Chrome Extension`
Hypothesis is a third-party application that allows anyone to make publicly visible comments on a website (once you create a free account). This section explains how to use and install the extension. As this tool requires an account with a third-party, we advise to use our [local-annotator](../external/annotater/README.md) with similar capabilities but which store annotations locally. By default Hypothesis stores annotations publicly, which might confuse other students.
```{admonition} Be careful of changing website URL's!

4
book/basic-features/overview.md
View file

@ -1,8 +1,8 @@
# Original Jupyter Book Features
# Original Jupyter Book and Sphinx Features
```{admonition} User types
:class: tip
This section is useful for [user type 3-5](../installation-and-setup/user_types.md).
```
These pages will provide a list of some common, basic book features which are all available in the original <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> package. However, this page includes also best-practices.
These pages will provide a list of some common, basic book features which are all available in the original <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> package. Additionally, this page includes also best-practices.

2
book/basic-features/utterances.md
View file

@ -1,5 +1,7 @@
# Discussions in your book: Utterances
{bdg-white}`GitHub app and Javascript script`
[Utterances 🔮](https://utteranc.es/) is a lightweight open-source widget which allows you, your colleages and your students to discuss stuff in a blog post in your book. It is build on GitHub issues, so requires a GitHub repository, although the book can be hosted anywhere (so also on GitLab).
The [utterances website](https://utteranc.es/) clearly explains the required steps. One thing to take care of is how you want to do the issue-mapping with respect to multiple deployed versions (draft version, student version, archived versions):

2
book/external/Download-Link-Replacer vendored

@ -1 +1 @@
Subproject commit e2205387f4446e736a89d6f5e70e0bddfa955a98
Subproject commit 66952b5f23af2f0106eb24e56f186d729b5a1ca8

2
book/external/JupyterBook-Patches vendored

@ -1 +1 @@
Subproject commit 8d97cb21d7d5f67cc19d35768c5e257d36cc0e69
Subproject commit 5c129f2447bb4b30100c136d94b5bee9e51e2921

2
book/external/Nested-Books vendored

@ -1 +1 @@
Subproject commit c0aab87a87c97e2c643c4e905a0065a49d925616
Subproject commit ced5cdefa1b1b6c4fdba3fc42a94e812db4892f0

2
book/external/Sphinx-Grasple-public vendored

@ -1 +1 @@
Subproject commit 4158a9c5cc5b299496066fa3fe36b569814c5f2b
Subproject commit c29b4a03351c88fa5cdd09475f99a1b486a0e247

2
book/external/Sphinx-Image-Inverter vendored

@ -1 +1 @@
Subproject commit 95fccf09f2c9d42ae473b3ed6033ebcb948792b1
Subproject commit c9c9d2f6953b5a57ff4763976840ec3bb281dbcf

2
book/external/Sphinx-TUDelft-theme vendored

@ -1 +1 @@
Subproject commit 9356dac16e04935cfa92924856f652d5653e8793
Subproject commit 0f4758586bebb1db4da0738b66d02d883ff7b54d

2
book/external/TeachBooks vendored

@ -1 +1 @@
Subproject commit ba8752053a5a4c70d8dacc77e65433f5bfb5a318
Subproject commit eb5f90c86e6f9dd368c513b2d958f77fb941cae0

2
book/external/annotater vendored

@ -1 +1 @@
Subproject commit 22d2efac5bf175f8173b9accae21e7270c977b03
Subproject commit 7cd38dbba9ab50eebc5dbba6c61b9cb4f46d3cf0

2
book/external/deploy-book-workflow vendored

@ -1 +1 @@
Subproject commit 29f9f4a690d0f0af49d04d062bf468de7fecc790
Subproject commit 71dd5f2f56c8540fa45ce713adf44cab9d85c36e

2
book/external/teachbooks-sphinx-tippy vendored

@ -1 +1 @@
Subproject commit 304a1dcd6bdf6ce3501eb46d55fcc9216db0d334
Subproject commit 546f58fe01a556130f06cdc95524efd922362f83

2
book/features/HTML_javascript.md
View file

@ -5,6 +5,8 @@
This section is useful for user type 5.
```
{bdg-danger}`iframe`
In this section, we will discuss how to [create](creating_basic_HTML_elements.md) and [embed](adding_HTML_elements.md) interactive HTML/Javascript elements created in HTML/JavaScript in a TeachBook. These HTML/Javascript element work very fluently and don't require a python kernel running in the background.
This could be for example interactive 3d figures:

2
book/features/adding_HTML_elements.md
View file

@ -1,5 +1,7 @@
# Adding interactive HTML/JavaScript elements
{bdg-danger}`iframe`
In this section, we will discuss how to embed interactive elements created in HTML/JavaScript in a TeachBook. If you are interested in learning how to create these elements yourself, we will discuss an example in the [next article](creating_basic_HTML_elements.md). As an example, let us discuss how to embed an interactive 3D model of a subsurface environment I created:
<iframe src="../_static/element_render_box.html" width="600" height="400" frameborder="0"></iframe>

102
book/features/custom-launch-button.md Normal file
View file

@ -0,0 +1,102 @@
# Multilingual book
```{admonition} User types
:class: tip
This page is useful for user type 4 and 5.
```
{bdg-primary}`Sphinx Extension`
The custom launch button extension allows you to create a customizable button in the top right of your jupyter book.
This may have many applications, one of them being that you can create different language versions of the book available for the user.
This section will explain how to create a "Languages" or " <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-globe" viewBox="0 0 16 16">
<path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8m7.5-6.923c-.67.204-1.335.82-1.887 1.855A8 8 0 0 0 5.145 4H7.5zM4.09 4a9.3 9.3 0 0 1 .64-1.539 7 7 0 0 1 .597-.933A7.03 7.03 0 0 0 2.255 4zm-.582 3.5c.03-.877.138-1.718.312-2.5H1.674a7 7 0 0 0-.656 2.5zM4.847 5a12.5 12.5 0 0 0-.338 2.5H7.5V5zM8.5 5v2.5h2.99a12.5 12.5 0 0 0-.337-2.5zM4.51 8.5a12.5 12.5 0 0 0 .337 2.5H7.5V8.5zm3.99 0V11h2.653c.187-.765.306-1.608.338-2.5zM5.145 12q.208.58.468 1.068c.552 1.035 1.218 1.65 1.887 1.855V12zm.182 2.472a7 7 0 0 1-.597-.933A9.3 9.3 0 0 1 4.09 12H2.255a7 7 0 0 0 3.072 2.472M3.82 11a13.7 13.7 0 0 1-.312-2.5h-2.49c.062.89.291 1.733.656 2.5zm6.853 3.472A7 7 0 0 0 13.745 12H11.91a9.3 9.3 0 0 1-.64 1.539 7 7 0 0 1-.597.933M8.5 12v2.923c.67-.204 1.335-.82 1.887-1.855q.26-.487.468-1.068zm3.68-1h2.146c.365-.767.594-1.61.656-2.5h-2.49a13.7 13.7 0 0 1-.312 2.5m2.802-3.5a7 7 0 0 0-.656-2.5H12.18c.174.782.282 1.623.312 2.5zM11.27 2.461c.247.464.462.98.64 1.539h1.835a7 7 0 0 0-3.072-2.472c.218.284.418.598.597.933M10.855 4a8 8 0 0 0-.468-1.068C9.835 1.897 9.17 1.282 8.5 1.077V4z"/>
</svg> " button, like you might be used to seeing on just about any website. The use of the button, however, is completey customizable and may be used in many different ways.
## Installation
1. Install the Sphinx Launch Buttons extension from the GitHub repository. Paste the following line, in your terminal. Make sure you activated your book building environment.
```
pip install git+https://github.com/TeachBooks/Sphinx-launch-buttons.git
```
2. To use the extension in your book, you need to include it in your `_config.yml` file.
```
sphinx:
extra_extensions:
- custom-launch-buttons
```
3. Then you need to include a `_launch_buttons.yml` file in the same location as your `_config.yml` file. The following code cell shows the main structure of that file.
```
buttons:
- type : dropdown
- type : button
```
Here, `buttons` is an array of launch buttons, each can be identified using 2 types: 'dropdown' or 'button'. The cell above shows 2 buttons, one of type `dropdown` and one of type `button`.
The button/dropdown can be visualised using either an [svg icon](https://icons.getbootstrap.com/#icons) or text.
```
buttons:
- type : dropdown
label: Language
- type : button
icon : <svg> ...
</svg>
```
4. Lastly you need to specifiy the items of your button. So assuming you want to have different language versions, each item will be one of the languages.
```
buttons:
- type : dropdown
label: Language
- type : button
icon : <svg> ...
</svg>
items:
- label: English
url: url of branch
- label: Nederlands
url: url of branch
```
As you can see in the `items:` line, each dropdown option links to the branch of the repository in the respective language.
## Setting up your repository
For the implementation to your book, it is handy to create a branch for each language version you want to offer. Make a new branch using for example main as a source. Assuming we want to create a dutch version of you can call this branch `Dutch` or `Nederlands`.
You will then need to translate the content in the dutch branch to dutch which can take some time. From experience, [DeepL](https://www.deepl.com/en/translator) is a good tool for this but any AI chatbot might be helpful as well. Make sure to proofread the translation.
You'll need to add (merge) the updated `_config.yml` and the new `_launch_buttons.yml` to all of your branches.
## Example
```
buttons:
- type: dropdown
icon: <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-globe" viewBox="0 0 16 16">
<path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8m7.5-6.923c-.67.204-1.335.82-1.887 1.855A8 8 0 0 0 5.145 4H7.5zM4.09 4a9.3 9.3 0 0 1 .64-1.539 7 7 0 0 1 .597-.933A7.03 7.03 0 0 0 2.255 4zm-.582 3.5c.03-.877.138-1.718.312-2.5H1.674a7 7 0 0 0-.656 2.5zM4.847 5a12.5 12.5 0 0 0-.338 2.5H7.5V5zM8.5 5v2.5h2.99a12.5 12.5 0 0 0-.337-2.5zM4.51 8.5a12.5 12.5 0 0 0 .337 2.5H7.5V8.5zm3.99 0V11h2.653c.187-.765.306-1.608.338-2.5zM5.145 12q.208.58.468 1.068c.552 1.035 1.218 1.65 1.887 1.855V12zm.182 2.472a7 7 0 0 1-.597-.933A9.3 9.3 0 0 1 4.09 12H2.255a7 7 0 0 0 3.072 2.472M3.82 11a13.7 13.7 0 0 1-.312-2.5h-2.49c.062.89.291 1.733.656 2.5zm6.853 3.472A7 7 0 0 0 13.745 12H11.91a9.3 9.3 0 0 1-.64 1.539 7 7 0 0 1-.597.933M8.5 12v2.923c.67-.204 1.335-.82 1.887-1.855q.26-.487.468-1.068zm3.68-1h2.146c.365-.767.594-1.61.656-2.5h-2.49a13.7 13.7 0 0 1-.312 2.5m2.802-3.5a7 7 0 0 0-.656-2.5H12.18c.174.782.282 1.623.312 2.5zM11.27 2.461c.247.464.462.98.64 1.539h1.835a7 7 0 0 0-3.072-2.472c.218.284.418.598.597.933M10.855 4a8 8 0 0 0-.468-1.068C9.835 1.897 9.17 1.282 8.5 1.077V4z"/>
</svg>
items:
- label: English
url: https://teachbooks.github.io/files-and-folders/EN
- label: Nederlands
url: https://teachbooks.github.io/files-and-folders/NL
```
The code in the above cell is the `_launch_buttons.yml` file of a repository called "files-and-folders". The buttons created look like this:
```{figure} figures/language_button.PNG
---
width: 50%
name:language_button
---
Custom Button
```

8
book/features/easy-editing.md Normal file
View file

@ -0,0 +1,8 @@
# Easy Editing Process
```{admonition} User types
:class: tip
This section is useful for user type 3-5.
```
The following tools are created by TeachBooks to ease the process of making books. We acknowledge that making books is a difficult process; it requires advanced knowledge on CLI, python packages, html-files, data-storage and website hosting. The tools in this chapter are intended for those users who lack knowledge on these topics (which includes most of the TeachBooks' community members itself).

BIN
book/features/figures/language_button.PNG Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 7.1 KiB

2
book/features/h5p.md
View file

@ -5,6 +5,8 @@
This section is useful for user type 3-5.
```
{bdg-danger}`iframe`
## Instruction
H5p elements are interactive HTML-blocks which can be embedded in a Jupyter Book using an iframe. An H5p element can be created in the [TU Delft portal on the H5p website](https://tudelft.h5p.com/content) (sign in via Brightspace to H5p required first). The iframe code can be copied at Edit - Publish - Public - Embed code. This html code can be directly added to your markdown file:

2
book/features/interactive_element.ipynb
View file

@ -9,7 +9,7 @@
"source": [
"# Interactive content: Elements not including Python\n",
"\n",
"To add interactivity to the book, you can make use of interactive elements which are embedded in the book. You've four options:\n",
"To add interactivity to the book, you can make use of interactive elements which are embedded in the book. You've a few options:\n",
"\n",
" - Admonition: question provided in normal markdown language with answers in a drowdown menu. There's no feedback delivered to the student, only the correct answer no matter what the student's thinking/work.\n",
" - JupyterQuiz: code-based implementation of multiple-choiche questions and numerical answer questions. This is a basic open course tool which requires you to write your quiz questions in Python language as a `dict` or to a `.json` file.\n",

2
book/features/live_code.ipynb
View file

@ -11,6 +11,8 @@
"This section is useful for user type 5.\n",
"```\n",
"\n",
"{bdg-primary}`Sphinx Extension`\n",
"\n",
"Our book has been enable to run Python code live in the browser (thanks Max!). This extension makes code cells in your `.ipynb` book pages editable and executable by the reader! Opposed to the original sphinx-thebe extensions, our extension runs python in the reader's browser and doesn't rely on an external webserver for the python kernel. We highly recommend this extension as it allows you to use the strength of combining text/figures and code of a jupyter book with interactivity!\n",
"\n",
"This page contains some installation instructions and the other sections show how to use this functionality to create interactive figures and feedback on code\n",

21
book/features/overview.md
View file

@ -1,12 +1,19 @@
# TeachBooks Authoring Features
# Overview
As TeachBooks, we collect a suite of existing open-source software and keep our books up-to-date so you don't have to! Some of the software is developed with our TA's to improve the learning experience of our students and ease the book-development process for our teachers. By deploying these tools from a central location we can prevent common problems before they arise, and fix them quickly when they do occur. As the open-source software landscape changes rapidly, it is essential to keep in contact and share resources amongst ourselves to minimize maintenance and downtime for our book websites and focus on what really matters: teaching!
This chapter provides a list of commonly used book features together with sub-pages that provide additional information on:
- the purpose
- how to install them
- how to use them
- where to find the source code
Since the list of TeachBook features is getting quite long, we have grouped them in categories:
To see examples for these features, go to the [Examples chapter](../examples/overview.md).
Additionally, not all features are built using the same type of sourcecode. For transparency, tags will help differentiate between the different backgrounds of the features:
- {bdg-warning}`Javascript overlay`
- {bdg-success}`Chrome Extension`
- {bdg-white}`GitHub App and Javascript script`
- {bdg-secondary}`Python Package`
- {bdg-light}`GitHub Reusable Action`
- {bdg-dark}`Git Workflow`
- {bdg-primary}`Sphinx Extension`
- {bdg-danger}`iframe`
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).

8
book/features/sphinx_extensions.md Normal file
View file

@ -0,0 +1,8 @@
# Additional functionality
```{admonition} User types
:class: tip
This section is useful for user type 4-5.
```
This sections includes the features developed by TeachBooks which add functionality to the book. Most of them are implemented as sphinx extensions, which are plugins developed for the Sphinx documentation ecosystem (which Jupyter Book is built upon). They extend or modify Sphinx’s capabilities. Since Sphinx extensions are not an integral part of jupyter-book, as opposed to original jupyter-book features, they must be installed and configured explicitly, for example in the `_config.yml` file.

7
book/features/students.md
View file

@ -1,3 +1,8 @@
# TeachBooks Student-view Features
This chapter includes some TeachBooks features which aim to improve the way students can use TeachBooks. These tools are fully student-side, they don't influence the book website and the author doesn't have to setup anything. Nevertheless, the author could point the students to the availability of these tools and use it as part of the didactical approach.
```{admonition} User types
:class: tip
This section is useful for user type 1-5.
```
This chapter includes some TeachBooks features which aim to improve the way students can use TeachBooks. These tools are fully student-side, they don't influence the book website and the author doesn't have to setup anything. Nevertheless, the author could point the students to the availability of these tools and use it as part of the didactical approach. These tools could also be useful for other users.

8
book/features/visuals.md Normal file
View file

@ -0,0 +1,8 @@
# Book styling
```{admonition} User types
:class: tip
This section is useful for user type 1-5.
```
TeachBooks developed a few improvements of the book which improve the visual book styling.