mirror of
https://github.com/TeachBooks/manual.git
synced 2026-11-12 22:35:51 +00:00
Jupyterbook v1 and teachbooks
This commit is contained in:
Tom van Woudenberg
parent
4311f11d16
commit
fdf2d7c5ef
57 changed files with 88 additions and 89 deletions
2
.github/workflows/call-deploy-book.yml
vendored
2
.github/workflows/call-deploy-book.yml
vendored
|
|
@ -5,7 +5,7 @@ on:
|
|||
branches:
|
||||
- '**'
|
||||
# - '!dependabot**'
|
||||
# If your git repository has the Jupyter Book within some-subfolder next to
|
||||
# If your git repository has the TeachBooks / Jupyter Book v1 within some-subfolder next to
|
||||
# unrelated files, you can make this run only if a file within that specific
|
||||
# folder (or the workflow file itself) has been modified.
|
||||
#
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ preferred-citation:
|
|||
value: 'https://github.com/TeachBooks/manual'
|
||||
description: 'GitHub repository'
|
||||
abstract: >-
|
||||
his manual assists you in creating and collaborating on JupyterBooks
|
||||
his manual assists you in creating and collaborating on TeachBooks
|
||||
for educational purposes. Some parts are specifically aimed for
|
||||
teachers at Delft University of Technology, although all material and
|
||||
tools are openly available. This manual aims at providing an easy start
|
||||
|
|
|
|||
|
|
@ -3,14 +3,14 @@
|
|||
[](https://doi.org/10.5281/zenodo.15100848)
|
||||
[](https://github.com/TeachBooks/manual/actions/workflows/call-deploy-book.yml)
|
||||
|
||||
This manual assists you in creating and collaborating on [JupyterBooks](https://jupyterbook.org/v1/) for educational purposes. Some parts are specifically aimed for teachers at Delft University of Technology, although all material and tools are openly available. This manual aims at providing an easy start and advanced usages for new and existing users with or without skills on this topic. it is part of TeachBooks, for more information visit [https://teachbooks.io/](https://teachbooks.io/).
|
||||
This manual assists you in creating and collaborating on TeachBooks: [JupyterBooks v1](https://jupyterbook.org/v1/) for educational purposes. Some parts are specifically aimed for teachers at Delft University of Technology, although all material and tools are openly available. This manual aims at providing an easy start and advanced usages for new and existing users with or without skills on this topic. it is part of TeachBooks, for more information visit [https://teachbooks.io/](https://teachbooks.io/).
|
||||
|
||||
## Contact
|
||||
If you encounter any issues and you have a TU Delft account, report it by clicking the github icon and lightbulb on the top right corner of this page. Or contribute directly by creating a merge request in the [repository](https://github.com/Teachbooks/manual).
|
||||
|
||||
If you have questions, contact the TeachBooks Development Team at info@teackbooks.io, also for non-TU Delft account holders. You can also contact us in our [GitHub discussions](https://github.com/orgs/TeachBooks/discussions)
|
||||
|
||||
We really value your feedback on this manual. This helps us improving it. Please keep using the manual as you build your own Jupyter Book and come back to fill out this short [survey](https://forms.gle/hXbFUQgN95H8ftxt9).
|
||||
We really value your feedback on this manual. This helps us improving it. Please keep using the manual as you build your own TeachBooks and come back to fill out this short [survey](https://forms.gle/hXbFUQgN95H8ftxt9).
|
||||
|
||||
## Contribute
|
||||
This book will continue to develop, so feel free to contribute https://github.com/TeachBooks/manual! You can do so directly by forking this repository and creating a merge request.
|
||||
|
|
|
|||
|
|
@ -101,7 +101,7 @@ parts:
|
|||
sections:
|
||||
- file: external/annotater/README.md
|
||||
- file: basic-features/hypothesis.md
|
||||
- caption: Original Jupyter Book and Sphinx Features
|
||||
- caption: Original Jupyter Book v1 and Sphinx Features
|
||||
chapters:
|
||||
- file: basic-features/overview.md
|
||||
sections:
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Badges, Buttons & Icons
|
||||
|
||||
<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> provides a range of features which are visually appealing and functional. These elements can enhance the interactivity and visual design of your book, offering additional information or links in a compact and visually engaging way. The badges, buttons and icons are made available through Sphinx and they themselves wrote a [documentation](https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html) about it.
|
||||
<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> provides a range of features which are visually appealing and functional. These elements can enhance the interactivity and visual design of your book, offering additional information or links in a compact and visually engaging way. The badges, buttons and icons are made available through Sphinx and they themselves wrote a [documentation](https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html) about it.
|
||||
|
||||
(my_ref)=
|
||||
## Badges
|
||||
|
|
@ -36,7 +36,7 @@ Here's an overview of all the available colours:
|
|||
|
||||
## Buttons
|
||||
|
||||
Buttons provide a way to create clickable elements that are more attractive than links, for example, to link to key sections of your book such as downloads or external resources. Jupyter-Book supports buttons using Markdown making them highly customizable. It is possible to link to external websites as well as chapters within your book. To link to an external page, use `{button-link}`. `{button-ref}` must be used when linking to a part within your book.
|
||||
Buttons provide a way to create clickable elements that are more attractive than links, for example, to link to key sections of your book such as downloads or external resources. Jupyter-Book v1 supports buttons using Markdown making them highly customizable. It is possible to link to external websites as well as chapters within your book. To link to an external page, use `{button-link}`. `{button-ref}` must be used when linking to a part within your book.
|
||||
|
||||
The basic code syntax for creating a button is as follows:
|
||||
|
||||
|
|
@ -119,12 +119,12 @@ To add an icon, use the following syntax:
|
|||
|
||||
**1. Image Icons**
|
||||
|
||||
Let's have a look at the first sentence of this chapter again: <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> provides a range of features which are visually appealing and functional.
|
||||
Let's have a look at the first sentence of this chapter again: <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> provides a range of features which are visually appealing and functional.
|
||||
|
||||
Here the Jupyter-book logo was inserted for a more professional look. It's including a link `href` and and image saved as `../images/logo-wide.svg`
|
||||
|
||||
```
|
||||
<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> provides a range of features which are visually appealing and functional.
|
||||
<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> provides a range of features which are visually appealing and functional.
|
||||
```
|
||||
|
||||
**2. SVG Icons**
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Banners and Announcements
|
||||
|
||||
A banner can be added to the top of a Jupyter Book:
|
||||
A banner can be added to the top of a TeachBook:
|
||||
|
||||
```{figure} banner_mude.png
|
||||
---
|
||||
|
|
@ -10,7 +10,7 @@ name: banner_mude
|
|||
Example of a banner in the MUDE book.
|
||||
```
|
||||
|
||||
This is a commonly used feature, described in the [Jupyter Book manual here](https://jupyterbook.org/v1/web/announcements.html). However, note that if you are using the Sphinx-Thebe interactive Python feature, or other features that customize the top part of a Jupyter Book website (for example, the download page buttons), the banner does not always work. In this case, the banner should be specified using the `announcement` option in the `html_theme_options` setting in the `_config.yml` file:
|
||||
This is a commonly used feature, described in the [Jupyter Book v1 manual here](https://jupyterbook.org/v1/web/announcements.html). However, note that if you are using the Sphinx-Thebe interactive Python feature, or other features that customize the top part of a TeachBook (for example, the download page buttons), the banner does not always work. In this case, the banner should be specified using the `announcement` option in the `html_theme_options` setting in the `_config.yml` file:
|
||||
|
||||
```
|
||||
sphinx:
|
||||
|
|
|
|||
|
|
@ -2,9 +2,9 @@
|
|||
|
||||
There are two main ways to include code: directly within a Markdown file or within a Jupyter notebook. More methods are available, but we don't include them here. The first option is great for including simple calculations, or generating simple figures when an image file is not practical. *More will be added later.*
|
||||
|
||||
Note that if you are using a `*.ipynb` file or including a code snippet in a `*.md` file, including a blank line between the text and the closing three tick marks will generate an empty code box of one line in the Jupyter Book.
|
||||
Note that if you are using a `*.ipynb` file or including a code snippet in a `*.md` file, including a blank line between the text and the closing three tick marks will generate an empty code box of one line in the TeachBook.
|
||||
|
||||
When making notebooks for the Book, you might want to hide certain cells from the reader. For example, when including a simple figure generated from code or making a JupyterQuiz, we have to execute a code cell that generates the quiz. This code cell is ugly and distracting, so we do not want to render this in the final book.
|
||||
When making notebooks for the TeachBook, you might want to hide certain cells from the reader. For example, when including a simple figure generated from code or making a JupyterQuiz, we have to execute a code cell that generates the quiz. This code cell is ugly and distracting, so we do not want to render this in the final book.
|
||||
|
||||
We can change how the compiler treats notebook cells by using cell tags. You can find a detailed explanation on cell tags [here](https://jupyterbook.org/v1/interactive/hiding.html?highlight=cell%20tag). Specifically, have a look at the sections on *hiding* cell inputs and *removing* cell inputs.
|
||||
|
||||
|
|
|
|||
|
|
@ -45,5 +45,5 @@ Equation {eq}`show_newtons_second_law` can now be referred to.
|
|||
|
||||
> **Note**
|
||||
>
|
||||
> The Jupyter Book uses MathJax to display equations, which provides some LaTeX-like functionality, but not all! For example, the Euro symbol is missing, and packages like `siunitx` are not available (hint, use `\textrm{}` and `\textrm{}`). When something is not working, it's useful to search for MathJax-specific solutions (hint, include "mathjax" in your Google search).
|
||||
> The TeachBook uses MathJax to display equations, which provides some LaTeX-like functionality, but not all! For example, the Euro symbol is missing, and packages like `siunitx` are not available (hint, use `\textrm{}` and `\textrm{}`). When something is not working, it's useful to search for MathJax-specific solutions (hint, include "mathjax" in your Google search).
|
||||
>
|
||||
|
|
@ -1,18 +1,17 @@
|
|||
# Anatomy of a Jupyter Book
|
||||
# Anatomy of a TeachBook
|
||||
|
||||
To build a Jupyter Book, you need three things:
|
||||
To build a TeachBook, you need three things:
|
||||
|
||||
1. A configuration file
|
||||
2. A table of contents
|
||||
3. Content
|
||||
|
||||
## The configuration file
|
||||
The configuration file of Jupyter Books is named `_config.yml`. It mainly contains settings that apply when building the book. Here is a basic example of a configuration file, taken from this book:
|
||||
The configuration file of TeachBooks is named `_config.yml`. It mainly contains settings that apply when building the book. Here is a basic example of a configuration file, taken from this book:
|
||||
|
||||
```yaml
|
||||
title: Jupyter Book Manual
|
||||
author: Interactive Textbooks CiTG
|
||||
logo: images/TUDelft_logo_rgb.png
|
||||
title: TeachBook Manual
|
||||
author: TeachBooks development team
|
||||
copyright: CC BY-NC
|
||||
|
||||
execute:
|
||||
|
|
@ -23,7 +22,7 @@ sphinx:
|
|||
- sphinx_inline_tabs
|
||||
```
|
||||
|
||||
Technically speaking, a `_config.yml` file is not required to build a Jupyter Book. If you don't make one, `jupyter book` will just use all default values. However, you should make a configuration file which includes at least the following settings:
|
||||
Technically speaking, a `_config.yml` file is not required to build a TeachBook. If you don't make one, your TeachBook will just use all default values. However, you should make a configuration file which includes at least the following settings:
|
||||
|
||||
- `title`: the title of your book, which appears on the top-left of every page, under the logo.
|
||||
- `author`: authors of the book, which appears in the bottom margin of every page.
|
||||
|
|
@ -32,7 +31,7 @@ Technically speaking, a `_config.yml` file is not required to build a Jupyter Bo
|
|||
|
||||
In addition, the following option can also be useful:
|
||||
|
||||
- `execute_notebooks`: *turn on/off* the execution of Jupyter Notebooks during the build process. *On* by default. If you perform heavy computations in your notebook (machine learning, FEM models, et cetera), you might be better off running the notebooks on a more powerful machine as opposed to the CI/CD server. To turn it off, specify the value `'off'`. You can also exclude specific notebooks by creating exclude patterns in the filenames. For more info, see the [Jupyter Book documentation](https://jupyterbook.org/v1/content/execute.html#exclude-files-from-execution).
|
||||
- `execute_notebooks`: *turn on/off* the execution of Jupyter Notebooks during the build process. *On* by default. If you perform heavy computations in your notebook (machine learning, FEM models, et cetera), you might be better off running the notebooks on a more powerful machine as opposed to the CI/CD server. To turn it off, specify the value `'off'`. You can also exclude specific notebooks by creating exclude patterns in the filenames. For more info, see the [Jupyter Book v1 documentation](https://jupyterbook.org/v1/content/execute.html#exclude-files-from-execution).
|
||||
|
||||
|
||||
```{warning}
|
||||
|
|
|
|||
|
|
@ -7,4 +7,4 @@ This section is useful for [user type 3-5](../installation-and-setup/user_types.
|
|||
|
||||
# Overview
|
||||
|
||||
These pages itemize some of the more common, basic book features which are all available in the original <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, without requiring any additional software. They are, of course, selected with teachers and teaching applications in mind. On each page best-practices are illustrated.
|
||||
These pages itemize some of the more common, basic book features which are all available in the original <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, without requiring any additional software. They are, of course, selected with teachers and teaching applications in mind. On each page best-practices are illustrated.
|
||||
|
|
|
|||
|
|
@ -13,9 +13,9 @@ kernelspec:
|
|||
|
||||
# Videos
|
||||
|
||||
Videos uploaded to YouTube can be embedded in the Jupyter Book. There are several ways to do so:
|
||||
Videos uploaded to YouTube can be embedded in the TeachBook. There are several ways to do so:
|
||||
|
||||
**1.** To embed them in the Jupyter Book, first obtain the embedding link of the video. In order to do so, go to the *YouTube* page of the video (so not the Brightspace page), then click *share* in the description box. There should be a button *embed*, click that. Copy the HTML code that appears in the panel. Then, to embed the video, use the following
|
||||
**1.** To embed them in the TeachBook, first obtain the embedding link of the video. In order to do so, go to the *YouTube* page of the video (so not the Brightspace page), then click *share* in the description box. There should be a button *embed*, click that. Copy the HTML code that appears in the panel. Then, to embed the video, use the following
|
||||
|
||||
```
|
||||
<iframe
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# Well-Structured Book
|
||||
|
||||
One thing that students love is having all practical information about a course collected and updated on one page.
|
||||
No more scrolling through the introduction lecture on Brightspace while veryfing assessment methods on the online studyguide or finding out about the schedule on MyTimetable. As will be shown in the following section, a Jupyter Book can be used to clarify the logistics of a course on top of providing the course material to the students.
|
||||
No more scrolling through the introduction lecture on Brightspace while veryfing assessment methods on the online studyguide or finding out about the schedule on MyTimetable. As will be shown in the following section, a TeachBook can be used to clarify the logistics of a course on top of providing the course material to the students.
|
||||
|
||||
The crossover module Data Science and Artifical Intelligence for Engineers, or in short DSAIE, aims to teach powerful data science tools to 2nd master students from the Civil Engineering and Geosciences faculty. In order to do that they use a combination of practical projects and theory provided to the students through their online interactive [book](https://interactivetextbooks.citg.tudelft.nl/dsaie/intro.html).
|
||||
|
||||
|
|
@ -16,7 +16,7 @@ DSAIE Overview Page
|
|||
```
|
||||
While the left menu shows the first two chapters in the table of contents (Home & Logistics), the right hand side menu shows the sections of the current chapter where an introduction is given on the different units of the course, the responsible lecturers as well as the schedule of lectures and practicals. Additionally, the book layout is explained to the students which can help clarify how to use the interactive sections!
|
||||
|
||||
The anatomy of a jupyter book is explained more in detail on [this page](../basic-features/jupyterbook.md). In short, you can create structure in your book by having chapters and subschapters defined in the `.toc` file. In each chapter you can organize the content in sections using the `#` syntax which is visible in the menu on the right.
|
||||
The anatomy of a TeachBook is explained more in detail on [this page](../basic-features/jupyterbook.md). In short, you can create structure in your book by having chapters and subschapters defined in the `.toc` file. In each chapter you can organize the content in sections using the `#` syntax which is visible in the menu on the right.
|
||||
|
||||
## Tagged content
|
||||
|
||||
|
|
|
|||
|
|
@ -8,10 +8,10 @@
|
|||
"source": [
|
||||
"# Programming assignment with checks\n",
|
||||
"\n",
|
||||
"This page shows how you can recreate the classical Jupyter Notebook assignments that are given in many courses to a Jupyter Book format with live coding. A widget has been implemented to check the answers, of which the data is included in a separate python file. The page automatically loads and a custom download page has been added\n",
|
||||
"This page shows how you can recreate the classical Jupyter Notebook assignments that are given in many courses to a TeachBook format with live coding. A widget has been implemented to check the answers, of which the data is included in a separate python file. The page automatically loads and a custom download page has been added\n",
|
||||
"\n",
|
||||
"```{Note}\n",
|
||||
"Keep in mind that Jupyter Book sections might not be the best environment for programming assignments you have in mind for your course due to the limitation posed by jupyter book. In fact, in jupyter book, python runs in the browser of the students' laptop. Nothing needs to be installed which can be an advantage but also a disadvantage depending on the learning goals of your course. TeachBooks suggests using it's live coding feature to support the theory in textbooks and not as a replacement for Jupyter Notebook.\n",
|
||||
"Keep in mind that TeachBook sections might not be the best environment for programming assignments you have in mind for your course due to the limitation posed by TeachBook. In fact, in a TeachBook, python runs in the browser of the students' laptop. Nothing needs to be installed which can be an advantage but also a disadvantage depending on the learning goals of your course. TeachBooks suggests using it's live coding feature to support the theory in textbooks and not as a replacement for Jupyter Notebook.\n",
|
||||
"```\n",
|
||||
"\n",
|
||||
"```{custom_download_link} ./example_gumbel_stripped.ipynb\n",
|
||||
|
|
|
|||
|
|
@ -4,10 +4,10 @@ Lastly some example pages are shown which combine theory and interactive questio
|
|||
|
||||
1. [Programming Assignments](example_gumbel.ipynb)
|
||||
|
||||
This page shows how you can recreate the classical Jupyter Notebook assignments that are given in many courses to a Jupyter Book format with live coding.
|
||||
This page shows how you can recreate the classical Jupyter Notebook assignments that are given in many courses to a TeachBook format with live coding.
|
||||
|
||||
```{Note}
|
||||
Keep in mind that Jupyter Book sections might not be the best environment for programming assignments you have in mind for your course due to the limitation posed by jupyter book. In fact, in jupyter book, python runs in the browser of the students' laptop. Nothing needs to be installed which can be an advantage but also a disadvantage depending on the learning goals of your course. TeachBooks suggests using it's live coding feature to support the theory in textbooks and not as a replacement for Jupyter Notebook.
|
||||
Keep in mind that TeachBook sections might not be the best environment for programming assignments you have in mind for your course due to the limitation posed by TeachBook. In fact, in a TeachBook, python runs in the browser of the students' laptop. Nothing needs to be installed which can be an advantage but also a disadvantage depending on the learning goals of your course. TeachBooks suggests using it's live coding feature to support the theory in textbooks and not as a replacement for Jupyter Notebook.
|
||||
```
|
||||
|
||||
2. [Combining theory with interactive questions and extensive coding assignments](example_quiz_interactive.ipynb)
|
||||
|
|
|
|||
|
|
@ -1,3 +1,3 @@
|
|||
# Overview
|
||||
|
||||
This chapter will showcase some TeachBooks making great use of Jupyter Book and TeachBooks features. They can serve as an inspiring starting point for structuring your own TeachBook or just to get an idea of how other teachers and students are using it. Lastly some example pages are shown which combine theory and interactive questions and coding to different degrees.
|
||||
This chapter will showcase some TeachBooks making great use of Jupyter Book v1 and TeachBooks features. They can serve as an inspiring starting point for structuring your own TeachBook or just to get an idea of how other teachers and students are using it. Lastly some example pages are shown which combine theory and interactive questions and coding to different degrees.
|
||||
|
|
|
|||
2
book/external/Download-Link-Replacer
vendored
2
book/external/Download-Link-Replacer
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 89235af168099dfc6af2be6cab19ca9a5565e1c8
|
||||
Subproject commit be4b09352b1eebeb6cfa614060daf187c6a8f7e7
|
||||
2
book/external/JupyterBook-Patches
vendored
2
book/external/JupyterBook-Patches
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit fe2dd75143631d9b3d6501eb0294b94ba3348e3c
|
||||
Subproject commit 13aa6988c62049030aec8bd2789452c494a31c96
|
||||
2
book/external/Nested-Books
vendored
2
book/external/Nested-Books
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 97780fc7ad1ac36ba7079421a1326343c2488cfb
|
||||
Subproject commit c365e770730fb5abb3426b06062e69a3a325b336
|
||||
2
book/external/Sphinx-Grasple-public
vendored
2
book/external/Sphinx-Grasple-public
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 95a060e2dab5490a362c7f25a8b8954c6cd2aaa7
|
||||
Subproject commit 0dc28b45ef6184e67b8219bd4494c6f54ad8ccd0
|
||||
2
book/external/Sphinx-Image-Inverter
vendored
2
book/external/Sphinx-Image-Inverter
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 215a5b9a8e205dba9ddf27052dba9e56d27c341e
|
||||
Subproject commit ca1280ccadfc17f611b6f411dddb77329710dd85
|
||||
2
book/external/Sphinx-TUDelft-theme
vendored
2
book/external/Sphinx-TUDelft-theme
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 86f5772bedd64ccbb2ab9ab16577215803ef238c
|
||||
Subproject commit 3815645c5cfef3ebbdc8070e649e4c7331b680e3
|
||||
2
book/external/Sphinx-launch-buttons
vendored
2
book/external/Sphinx-launch-buttons
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 63d539763e9b9ce13f4dab2ef4c4a17c46e953ef
|
||||
Subproject commit 9e70fbca8fb7bacb3e6d9c58349f04d6245082dc
|
||||
2
book/external/deploy-book-workflow
vendored
2
book/external/deploy-book-workflow
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 2cb7fc38e67d0aa486829027baee61d46c213e75
|
||||
Subproject commit da54eb463cd0bac2a3e78dcce7067b2a81a8c3d1
|
||||
2
book/external/template
vendored
2
book/external/template
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 1064963a9393a4a910d05435759887610d05bca5
|
||||
Subproject commit 1ab90c5092b69aa8e1421e598ff43433bd97a9d8
|
||||
|
|
@ -16,7 +16,7 @@ This page is useful for user type 4 and 5.
|
|||
```{note}
|
||||
This feature is stable but because it relies on a local extension that is part of your book files and _not_ managed as part of a computing environment (e.g., `pip` or `conda`), unknown issues may arise. We would like to convert this feature into an independent Sphinx extension and/or Pybtext plugin. Visit the README in the [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17?pane=info) to learn more.
|
||||
|
||||
The instructions provided here will work under conventional usage with Jupyter Book (e.g., `jupyter book build book`).
|
||||
The instructions provided here will work under conventional usage with TeachBooks and Jupyter Book v1 (e.g., `jupyter book build book`).
|
||||
|
||||
A temporary fix has also been implemented in the TeachBooks package for use with the Deploy Book Workflow (release mode) (see [release notes from v0.1.0](https://github.com/TeachBooks/TeachBooks/releases/tag/v0.1.0)).
|
||||
|
||||
|
|
@ -25,7 +25,7 @@ _Update, October 21, 2025:_ a new fix was necessitated due to dependency issues
|
|||
|
||||
## Introduction
|
||||
|
||||
Do you include references in your book, but you're tired of the default options available in Jupyter Book? For example, the square-bracket style of citation and reference, where the first three letters of the name year are combined in a way that seems designed to minimize transparency?
|
||||
Do you include references in your book, but you're tired of the default options available in a TeachBook / Jupyter Book v1? For example, the square-bracket style of citation and reference, where the first three letters of the name year are combined in a way that seems designed to minimize transparency?
|
||||
|
||||
There is a solution! This extension allows you to have APA formatting in your book.
|
||||
|
||||
|
|
@ -97,7 +97,7 @@ Two issues are known:
|
|||
|
||||
The extension is based on [`pybtex`](https://pybtex.org/), which is a BibTeX-compatible bibliography processor in Python that is extendible with plugins.
|
||||
|
||||
Although some customization is possible with the standard Jupyter Book features, [as described here](https://jupyterbook.org/v1/content/citations.html#change-the-in-line-citation-style), this extension implements the complete APA style, as well as enforcing round brackets (like this).
|
||||
Although some customization is possible with the standard Jupyter Book v1 features, [as described here](https://jupyterbook.org/v1/content/citations.html#change-the-in-line-citation-style), this extension implements the complete APA style, as well as enforcing round brackets (like this).
|
||||
|
||||
The need to include a CSS file is an easy solution to the issue where empty brackets `[]` are left on the references page (to try it, simply delete `apastyle.css`).
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ Now that we have talked about how you can collaborate using git, it's time to ex
|
|||
|
||||
## Pipeline
|
||||
|
||||
Both GitLab and GitHub make use of CI/CD to publish the jupyter books. CI/CD stands for Continuous Integration/Continuous Deployment. Within the scope of jupyter books focuses on automating the process of building and deploying the books. It makes sure that the book is always up-to-date and available.
|
||||
Both GitLab and GitHub make use of CI/CD to publish the TeachBooks. CI/CD stands for Continuous Integration/Continuous Deployment. Within the scope of TeachBooks, it focuses on automating the process of building and deploying the books. It makes sure that the book is always up-to-date and available.
|
||||
|
||||
Concretely, Continuous Integration means that whenever changes are pushed to the repository (where does the publish branch come in?) the pipeline is triggered. Moreover, the pipeline also builds the book which is composed out of multiple .md or .ipynb files and converts those files into HTML.
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ This page is useful for user type 4 and 5.
|
|||
````
|
||||
|
||||
# Multilingual book
|
||||
The custom launch button extension allows you to create a customizable button in the top right of your jupyter book.
|
||||
The custom launch button extension allows you to create a customizable button in the top right of your TeachBook.
|
||||
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">
|
||||
|
|
|
|||
|
|
@ -90,6 +90,6 @@ pip install --upgrade teachbooks
|
|||
|
||||
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.
|
||||
|
||||
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 package is a CLI tool that primarily provides a wrapper around the Jupyter Book v1 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.
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ This section is useful for user type 3-5.
|
|||
# H5p interactive elements
|
||||
|
||||
## Instruction
|
||||
H5p elements are interactive HTML-blocks which can be embedded in a Jupyter Book using an iframe. H5p requires a server to host those elements. For TU Delft employees, this is arranged for on a [TU Delft portal on the H5p website](https://tudelft.h5p.com/content) (sign in via Brightspace to H5p required first as described [here](https://www.tudelft.nl/teaching-support/educational-tools/h5p)).
|
||||
H5p elements are interactive HTML-blocks which can be embedded in a TeachBook using an iframe. H5p requires a server to host those elements. For TU Delft employees, this is arranged for on a [TU Delft portal on the H5p website](https://tudelft.h5p.com/content) (sign in via Brightspace to H5p required first as described [here](https://www.tudelft.nl/teaching-support/educational-tools/h5p)).
|
||||
|
||||
After creating an H5p element, the iframe code can be copied at Edit - Publish - Public - Embed code. This html link of that embed can be directly added to your markdown file using [](../external/sphinx-iframes/README.md):
|
||||
|
||||
|
|
|
|||
|
|
@ -23,9 +23,9 @@ When you have installed `jupyterlite-xeus-python`, the kernel will automatically
|
|||
}
|
||||
}
|
||||
|
||||
## Updating the Jupyter Book `_config.yml`
|
||||
## Updating the TeachBook's `_config.yml`
|
||||
|
||||
Since `jupyterlite-sphinx` is a Sphinx extension, we need to tell Jupyter Book to include it in the build process and specify the name of the `jupyterlite` configuration file. To do so, create a new entry in `_config.yml` like this:
|
||||
Since `jupyterlite-sphinx` is a Sphinx extension, we need to tell TeachBooks to include it in the build process and specify the name of the `jupyterlite` configuration file. To do so, create a new entry in `_config.yml` like this:
|
||||
|
||||
sphinx:
|
||||
extra_extensions:
|
||||
|
|
@ -37,4 +37,4 @@ Of course, change `jupyterlite-config.json` to the name of your configuration fi
|
|||
|
||||
## Building
|
||||
|
||||
When everything is configured correctly, a `Xeus-Python` kernel will be built when you build your book via `jupyter book build`. You can check this by keeping an eye on the output in the terminal: you should see a lot of extra lines mentioning `JupyterLite`.
|
||||
When everything is configured correctly, a `Xeus-Python` kernel will be built when you build your book via `teachbooks build`. You can check this by keeping an eye on the output in the terminal: you should see a lot of extra lines mentioning `JupyterLite`.
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# JupyterLite-Sphinx
|
||||
|
||||
By popular demand: how to include interactive pieces of code in your Jupyter Book. We can do this by using the [JupyterLite](https://github.com/jupyterlite) app, which allows you to run a Jupyter Lab session and execute Python code entirely in-browser. Jupyterlite can be embedded in a Jupyter Book with the [`JupyterLite-Sphinx`](https://github.com/jupyterlite/jupyterlite-sphinx) extension.
|
||||
By popular demand: how to include interactive pieces of code in your TeachBook. We can do this by using the [JupyterLite](https://github.com/jupyterlite) app, which allows you to run a Jupyter Lab session and execute Python code entirely in-browser. Jupyterlite can be embedded in a TeachBook with the [`JupyterLite-Sphinx`](https://github.com/jupyterlite/jupyterlite-sphinx) extension.
|
||||
|
||||
## An example
|
||||
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@
|
|||
"\n",
|
||||
"# Interactive content: Run Python inside your book\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",
|
||||
"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 TeachBook 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",
|
||||
"\n",
|
||||
|
|
@ -95,7 +95,7 @@
|
|||
"\n",
|
||||
"By `launch_buttons` you initiate the {fa}`rocket` --> {guilabel}`Live Code` on the top right corner of every page generated from a `.ipynb` file. \n",
|
||||
"\n",
|
||||
"Note, if you're messing around with `html_theme_options` (for example when adding more buttons), all button behaviour is affected. In that case, as opposed to the jupyter book documentation, all buttons have to be specified from within `sphinx: html_theme_options` where you might also specify other buttons as well (ie. the [code repository button](https://jupyterbook.org/v1/basics/repository.html)).\n",
|
||||
"Note, if you're messing around with `html_theme_options` (for example when adding more buttons), all button behaviour is affected. In that case, as opposed to the jupyter book v1 documentation, all buttons have to be specified from within `sphinx: html_theme_options` where you might also specify other buttons as well (ie. the [code repository button](https://jupyterbook.org/v1/basics/repository.html)).\n",
|
||||
"\n",
|
||||
"```yaml\n",
|
||||
"sphinx:\n",
|
||||
|
|
@ -119,7 +119,7 @@
|
|||
"If you push to main, you can test the interactivity on the book-draft website as well.\n",
|
||||
"\n",
|
||||
"## Custom cell tags\n",
|
||||
"With the extended functionality of live code, additional cell tags have been developed to be added to python cells (not markdown cells) in any .ipynb file, next to the [existing tags] of the jupyter book (https://jupyterbook.org/en/stable/content/metadata.html):\n",
|
||||
"With the extended functionality of live code, additional cell tags have been developed to be added to python cells (not markdown cells) in any .ipynb file, next to the [existing tags] of the jupyter book v1 (https://jupyterbook.org/en/stable/content/metadata.html):\n",
|
||||
"- `disable-execution-cell` disables the ability to execute the cell when thebe is activated. This might be useful if you notebook file includes interactivity for only a part of the coding cells\n",
|
||||
"- `disable-execution-page` disables the ability to execute the entire page. This might be useful if you use python code for creating a page, but the code is not part of the actual content of the book.\n",
|
||||
"- `auto-execute-page` automatically starts the thebe live coding functionality whenever the page is opened. This is particularly useful if you're using widgets on a page.\n",
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ Technically what is needed to facilitate this during the editing and checking of
|
|||
```{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.
|
||||
A TeachBook 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>`.
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
As TeachBooks, we collect a suite of existing open-source software 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. 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!
|
||||
|
||||
Since the list of TeachBook features is getting quite long, we have grouped them in categories:
|
||||
- [Original Jupyter Book and Sphinx features](../basic-features/overview.md)
|
||||
- [Original Jupyter Book v1 and Sphinx features](../basic-features/overview.md)
|
||||
- [Easy editing process](./easy-editing.md)
|
||||
- [Additional functionality](./sphinx_extensions.md)
|
||||
- [Book styling](./visuals.md)
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ Pull Requests are a key tool for allowing anyone with a GitHub account to make a
|
|||
|
||||
Read the Docs is not recommended for final versions of your book because of the advertisement in the free version. If you'd like to pay for it, it can replace the functionality of the [deploy-book-workflow](../external/deploy-book-workflow/README.md).
|
||||
|
||||
This tool works using Sphinx, which is the core engine for Jupyter Book; it is carried out using a Jupyter Book command to generate a Sphinx configuration file, for example:
|
||||
This tool works using Sphinx, which is the core engine for Jupyter Book v1; it is carried out using a Jupyter Book command to generate a Sphinx configuration file, for example:
|
||||
|
||||
```
|
||||
jupyter-book config sphinx book/
|
||||
|
|
|
|||
|
|
@ -118,7 +118,7 @@ One possible modification to this setup would be if you are progressively releas
|
|||
- Set `PRIMARY_BRANCH` to `2024`
|
||||
- Set `BEHAVIOR_PRIMARY` to `copy`
|
||||
|
||||
As your current students may then accidentally go to the older version of the book, we recommend you use a banner to indicate to readers that there is a (partial) new version available, and advise them where to find it. You can add a banner using this workflow (`BRANCHES_ARCHIVED`) or the [standard Jupyter Book banner feature](https://jupyterbook.org/v1/web/announcements.html).
|
||||
As your current students may then accidentally go to the older version of the book, we recommend you use a banner to indicate to readers that there is a (partial) new version available, and advise them where to find it. You can add a banner using this workflow (`BRANCHES_ARCHIVED`) or the [standard Jupyter Book v1 banner feature](https://jupyterbook.org/v1/web/announcements.html).
|
||||
|
||||
### Books with active editors working in parallel
|
||||
|
||||
|
|
|
|||
|
|
@ -7,4 +7,4 @@ This section is useful for user type 4-5.
|
|||
|
||||
# Additional functionality
|
||||
|
||||
This sections includes the features developed by TeachBooks which add functionality to the book. Most of them are implemented as sphinx extensions {bdg-primary}`Sphinx Extension`, 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` and `requirements.txt` files.
|
||||
This sections includes the features developed by TeachBooks which add functionality to the book. Most of them are implemented as sphinx extensions {bdg-primary}`Sphinx Extension`, which are plugins developed for the Sphinx documentation ecosystem (which Jupyter Book v1 and TeachBooks is built upon). They extend or modify Sphinx’s capabilities. Since Sphinx extensions are not an integral part of Jupyter Book and TeachBooks, as opposed to original jupyter-book v1 features, they must be installed and configured explicitly, for example in the `_config.yml` and `requirements.txt` files.
|
||||
|
|
@ -27,10 +27,10 @@ This section is useful for user type 4-5.
|
|||
(teachbooks_package)=
|
||||
# TeachBooks Python Package
|
||||
|
||||
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](../external/deploy-book-workflow/README.md) and, therefore, any book created from the [TeachBooks Template](../external/template/README.md). This raises two important points:
|
||||
The TeachBooks Python package is a collection of tools that are used to enhance the Jupyter Book v1 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](../external/deploy-book-workflow/README.md) and, therefore, any book created from the [TeachBooks Template](../external/template/README.md). This raises two important points:
|
||||
|
||||
1. If you are a book user using the [TeachBooks Template](../external/template/README.md) and/or the [Deploy Book Workflow](../external/deploy-book-workflow/README.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/v1/publish/web.html), for example, [this GitHub workflow](https://jupyterbook.org/v1/publish/gh-pages.html).
|
||||
2. If you are using the `jupyter-book` v1 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 v1 Manual](https://jupyterbook.org/v1/publish/web.html), for example, [this GitHub workflow](https://jupyterbook.org/v1/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`. As `teachbooks` is a wrapper, the package is meant to replace the usage of `jupyter-book` commands (although it does indeed add a few new commands to the CLI, e.g., `serve`). It is conventionally used in an identical way, as follows:
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ This page is useful for user type 4-5.
|
|||
|
||||
# Auto-updating packages
|
||||
|
||||
When building your book, you are making use of various Python packages: the `teachbooks` and `jupyter-book` packages themselves, but also packages for extensions. These are regularly updated, however, those updates are not necessarily incorporated into your book automatically. The list of packages and their versions are defined in the `requirements.txt` file, which is provided as part of the [template](../external/template/README.md). Consider the following three options for how packages can be specified:
|
||||
When building your book, you are making use of various Python packages: the `teachbooks` and `jupyter-book` v1 packages themselves, but also packages for extensions. These are regularly updated, however, those updates are not necessarily incorporated into your book automatically. The list of packages and their versions are defined in the `requirements.txt` file, which is provided as part of the [template](../external/template/README.md). Consider the following three options for how packages can be specified:
|
||||
1. `requirements.txt` only contains names of packages like: `download_link_replacer`. In that case, your [deploy-book-workflow](../external/deploy-book-workflow/README.md) will take the most up-to-date version when making your book website once a week (as the chache will be cleared once a week). This might lead to unexpected changes when a new version has been released (although new versions will generally be backwards compatible).
|
||||
1. `requirements.txt` contains names of packages with a specified version like: `download_link_replacer==1.0.4`. In that case, your [deploy-book-workflow](../external/deploy-book-workflow/README.md) always uses that specific version. In doing so, you'll never get a new update unless you explicitly adapt the version in `requirements.txt`. If you'd like to get notified for updates, you might consider using GitHub's Dependabot.
|
||||
1. A combination of 1. and 2.: In that case (once a week at most) you will receive new versions for only the unfixed packages, no updates for the fixed versions.
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
"source": [
|
||||
"# Ipywidgets\n",
|
||||
"\n",
|
||||
"If you publish widgets in a jupyter book they might (depending on your implementation) require an active python kernel for the output to be interactive. Using the [thebe-integration](../examples/live_code.md), this is possible. Note: You can circumvent the use of a kernel by using packages which don't need such a kernel, for example the [non-kernel-based widgets using Plotly](./plotly.ipynb).\n",
|
||||
"If you publish widgets in a TeachBook they might (depending on your implementation) require an active python kernel for the output to be interactive. Using the [thebe-integration](../examples/live_code.md), this is possible. Note: You can circumvent the use of a kernel by using packages which don't need such a kernel, for example the [non-kernel-based widgets using Plotly](./plotly.ipynb).\n",
|
||||
"\n",
|
||||
"## `matplotlib` widgets\n",
|
||||
"When you'd like to use `ipywidgets` in combinations with a `matplotlib` figure, import the following packages:\n",
|
||||
|
|
@ -221,7 +221,7 @@
|
|||
"metadata": {
|
||||
"celltoolbar": "Tags",
|
||||
"kernelspec": {
|
||||
"display_name": "Python 3 (ipykernel)",
|
||||
"display_name": "base",
|
||||
"language": "python",
|
||||
"name": "python3"
|
||||
},
|
||||
|
|
@ -235,7 +235,7 @@
|
|||
"name": "python",
|
||||
"nbconvert_exporter": "python",
|
||||
"pygments_lexer": "ipython3",
|
||||
"version": "3.11.5"
|
||||
"version": "3.12.11"
|
||||
}
|
||||
},
|
||||
"nbformat": 4,
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
(tex_md_converter)=
|
||||
# Convert LaTeX to Markdown
|
||||
|
||||
A script is to convert LaTeX files to Markdown for use in Jupyter Books {cite:p}`timon_latex`.
|
||||
A script is to convert LaTeX files to Markdown for use in TeachBooks and Jupyter Books v1 {cite:p}`timon_latex`.
|
||||
|
||||
This script has been used successfully on at least one book in the TU Delft OPEN library: [Introduction to particle and continuum mechanics, by Timon Idema](https://textbooks.open.tudelft.nl/textbooks/catalog/book/81). The author is able to convert nearly everything in this book automatically, with only a few manual adjustments needed (e.g., a special character and a figure caption).
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
This chapter contains a few scripts which can be useful in the book-editing process, all of which are scripts and/or files stored in other repositories (they are _not_ Sphinx extensions).
|
||||
|
||||
- [LaTeX to markdown conversion](tex_md_converter) to convert a LaTeX file into jupyter-book compatible markdown.
|
||||
- [LaTeX to markdown conversion](tex_md_converter) to convert a LaTeX file into TeachBook compatible markdown.
|
||||
- [Snippitall](Snippitall) to insert the same code snippet at a certain point in each md file in a specific folder and all subfolder.
|
||||
- [Snippitonce](Snippitonce) to insert the same code snippet at a certain point in each md file only in a specific folder.
|
||||
- [Extensionchecker](Extensionchecker) to identify the kind of files present in subfolder
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# TeachBooks Manual
|
||||
|
||||
This manual is primarily designed for and by teachers for use in education, but should be a useful resource for anyone interested in creating and collaborating on <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>. Our aim is to provide a simple way to start book-making for new users (it only takes 10 clicks!) through advanced usage for experienced users with many additional features developed for education-purposes. We hope you find this resource useful and refer back to it often.
|
||||
This manual is primarily designed for and by teachers for use in education, but should be a useful resource for anyone interested in creating and collaborating on <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>. Our aim is to provide a simple way to start book-making for new users (it only takes 10 clicks!) through advanced usage for experienced users with many additional features developed for education-purposes. We hope you find this resource useful and refer back to it often.
|
||||
|
||||
TeachBooks originated at Delft University of Technology in the Netherlands, and some of the material in this Manual reflects tools and resources specific to TU Delft. With the exception of a few tools for which we have educational licenses at Delft, everything in this Manual is open source. Despite this, we are happy to grow our open source community beyond Delft and welcome contributions from all users.
|
||||
|
||||
|
|
@ -11,7 +11,7 @@ Happy book building!
|
|||
## How to Use this Manual
|
||||
|
||||
There are several "parts" to the manual:
|
||||
- **Your First TeachBook!** introduces the essential platforms and workflows, and contains a _workshop_ that can be completed independently or as part of a TeachBooks training. We recommend even experienced Jupyter Book users go through this material to better understand the TeachBooks vision on how to make books collaboratively, as this drives much of our tool development. The workshop is designed to be completed in 1-2 hours and does not require any prior knowledge or installation (just a GitHub account).
|
||||
- **Your First TeachBook!** introduces the essential platforms and workflows, and contains a _workshop_ that can be completed independently or as part of a TeachBooks training. We recommend even experienced Jupyter Book v1 users go through this material to better understand the TeachBooks vision on how to make books collaboratively, as this drives much of our tool development. The workshop is designed to be completed in 1-2 hours and does not require any prior knowledge or installation (just a GitHub account).
|
||||
- **Getting Going!** begins with an overview of _User Types_, which are used to help understand which parts of the Manual are most relevant to you. Detailed software installation instructions, book and team setup and workflows are also provided in this part.
|
||||
- The **Features** part describes a suite of tools that are useful for teachers, many of which are developed by TeachBooks contributors specifically for use in education. Many of these tools are illustrated in the **Examples**.
|
||||
- A few special tools are included in the **Editing Tools** that are useful when writing content.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# You Know the Basics: What Next?
|
||||
|
||||
You've seen what a JupyterBook is, how TeachBooks tries to help you with making those, and what the potential is in teaching. So what's next?
|
||||
You've seen what a TeachBooks is, how git is useful in combination with it, and what the potential is in teaching. So what's next?
|
||||
|
||||
In this manual we explain how to get going depending on the way you want to use it. If you successfully followed the steps until here, you'll be able to make book as a 'user type 3'!
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ width: 150px
|
|||
align: right
|
||||
```
|
||||
|
||||
Now that you've been introduced to the basics of a Jupyter Book, let's make one! The TeachBooks Team has put together a set of tools to make the book-creation process as smooth and automatic as possible. This page guides you through the process of creating a book, followed by a series of exercises that are designed to help you get used to the syntax and structure of a Jupyter Book, as well as the tools and essential workflows associated with the editing, checking and review processes.
|
||||
Now that you've been introduced to the basics of a TeachBook, let's make one! The TeachBooks Team has put together a set of tools to make the book-creation process as smooth and automatic as possible. This page guides you through the process of creating a book, followed by a series of exercises that are designed to help you get used to the syntax and structure of a TeachBook, as well as the tools and essential workflows associated with the editing, checking and review processes.
|
||||
|
||||
## 1. Create a GitHub account
|
||||
TeachBooks relies of freely available services from GitHub to store files online, carry out the book-building process and host your book as a website. All you need to get started is a GitHub account (not counted in the 10 clicks 🤭).
|
||||
|
|
@ -26,7 +26,7 @@ Go to the [TeachBooks Template repository on GitHub](https://github.com/TeachBoo
|
|||
```
|
||||
|
||||
## 3. Let's practice!
|
||||
Getting used to the syntax of writing in a Jupyter Book can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises covering the TeachBooks workflow have been prepared for you. The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages.
|
||||
Getting used to the syntax of writing in a TeachBook can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises covering the TeachBooks workflow have been prepared for you. The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages.
|
||||
|
||||
The exercises on the TeachBooks Workflow can be found in your book at `https://<username or organiszation_name>.github.io/<repository_name>/exercises/exercises` (case sensitive) or at https://teachbooks.io/template/exercises.html.
|
||||
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ This page is useful for user type 3, 4 and 5.
|
|||
|
||||
# Collaborative book-editing
|
||||
|
||||
A jupyter book is composed out of many files which contain the educational content produced by you. Through the use of branches it is possible to work on the book at the same time as your team-members. Working on content for the book is mainly individual work, the beauty of Git comes in when everybody's changes are merged into the main branch.
|
||||
A TeachBook is composed out of many files which contain the educational content produced by you. Through the use of branches it is possible to work on the book at the same time as your team-members. Working on content for the book is mainly individual work, the beauty of Git comes in when everybody's changes are merged into the main branch.
|
||||
|
||||
We have previously introduced the notions of using Git in the online environment (remote) or locally. All the (text, figures, etc.) files that make up the book are contained on the remote repository on GitLab or GitHub. This could be on an open repository on `gitlab.com` or `github.com`. In the context of creating educational books for students at TU Delft, the repository will most likely be located on `github.com` or `gitlab.tudelft.nl`. If this is the first time you interact with books, you're advise to use `github.com`.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Edit (merge conflicts, staging, committing, pushing)
|
||||
|
||||
Suppose we are writing a new chapter, or are updating an existing chapter for our Jupyter Book. We've created a new branch on which we are going to make the changes.
|
||||
Suppose we are writing a new chapter, or are updating an existing chapter for our TeachBook. We've created a new branch on which we are going to make the changes.
|
||||
|
||||
**Edit files as ...**
|
||||
`````````{tab-set}
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ Then we can build the book locally. Make sure you are in the right repository in
|
|||
teachbooks build <path-to-book>
|
||||
```
|
||||
|
||||
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.
|
||||
Note: use `--all` for the TeachBook 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:
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue