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 branch 'main' of https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual

Browse source
This commit is contained in:
Freek Pols 2024-10-18 19:06:18 +02:00
commit 26f79a14a7
22 changed files with 99 additions and 164 deletions
Download patch file Download diff file Expand all files Collapse all files

12
.gitlab-ci.yml
View file

@ -2,18 +2,15 @@ stages:
- test
- build
- deploy
variables:
PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
REGISTRY_HOST: localhost:5000
TAG_LATEST: $REGISTRY_HOST/$CI_PROJECT_NAME/$CI_COMMIT_REF_NAME:latest
TAG_DRAFT: $REGISTRY_HOST/$CI_PROJECT_NAME-draft/$CI_COMMIT_REF_NAME:latest
GIT_SUBMODULE_STRATEGY: recursive # For submodules
cache:
paths:
- .cache/pip
# This job tests if the book compiles gracefully after a new addition
test-build:
stage: test
@ -24,13 +21,12 @@ test-build:
- pip install -r requirements.txt
- jupyter-book clean book/
- jupyter-book build book/
# This job builds the Docker container
build-book:
stage: build
image: docker
rules:
- if: $CI_COMMIT_BRANCH == "publish" && $CI_PIPELINE_SOURCE == "push"
- if: $CI_COMMIT_BRANCH == "release" && $CI_PIPELINE_SOURCE == "push"
variables:
TAG: $TAG_LATEST
- if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push"
@ -42,13 +38,12 @@ build-book:
- if [ "$TAG" = "$TAG_LATEST" ]; then sed --in-place=".bak" '/# START DRAFT/,/# END DRAFT/{//!d}' book/_config.yml; fi
- docker build -t $TAG .
- docker push $TAG
# This job takes down the existing container and starts the new one
deploy-book:
stage: deploy
image: docker
rules:
- if: $CI_COMMIT_BRANCH == "publish" && $CI_PIPELINE_SOURCE == "push"
- if: $CI_COMMIT_BRANCH == "release" && $CI_PIPELINE_SOURCE == "push"
before_script:
- docker info
- docker stop $CI_PROJECT_NAME || exit_code=$?
@ -58,7 +53,6 @@ deploy-book:
environment:
name: production
url: https://interactivetextbooks.citg.tudelft.nl/jupyter-book-manual
# Deploy the draft version of the book
deploy-draft:
stage: deploy
@ -73,4 +67,4 @@ deploy-draft:
- docker run -d --restart always -p 8018:8000 --name $CI_PROJECT_NAME-draft $TAG_DRAFT
environment:
name: draft
url: https://interactivetextbooks.citg.tudelft.nl/jupyter-book-manual-draft
url: https://interactivetextbooks.citg.tudelft.nl/jupyter-book-manual-draft

3
.gitmodules vendored
View file

@ -13,3 +13,6 @@
[submodule "book/external/Useful_python_code"]
path = book/external/Useful_python_code
url = https://github.com/TeachBooks/Useful_python_code.git
[submodule "book/external/TeachBooks"]
path = book/external/TeachBooks
url = https://github.com/TeachBooks/TeachBooks.git

20
book/_toc.yml
View file

@ -36,11 +36,11 @@ parts:
- file: basic-features/Code_block_figures
- file: basic-features/banner
title: Banner or Announcement
- file: basic-features/hypothesis
- file: basic-features/utterances
- file: basic-features/hypothesis.md
- file: basic-features/utterances.md
- file: features/overview
sections:
- file: features/teachbooks
- file: external/TeachBooks/README.md
title: TeachBooks Package
- file: external/deploy-book-workflow/README.md
- file: features/remove_from_publish
@ -55,20 +55,14 @@ parts:
sections:
- file: features/adding_HTML_elements.md
- file: features/creating_basic_HTML_elements.md
- file: features/python_interactivity.md
- file: features/live_code
sections:
- file: features/live_code
sections:
- file: features/widgets.ipynb
- file: features/exercise_checking.ipynb
- file: features/jupyterlite/jupyterlite
sections:
- file: features/jupyterlite/configuration
- file: features/jupyterlite/including-jupyterlite
- file: features/widgets.ipynb
- file: features/exercise_checking.ipynb
- caption: Examples
chapters:
- file: examples/overview
- file: examples/overview.md
- file: examples/book_structure.md
- file: examples/h5p_examples.md
- file: examples/live_code.md

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

@ -5,14 +5,4 @@
This section is useful for user type 3-5.
```
A short description on basic features is given here:
- Figures
- Videos
- Equations
- Code blocks to produce figures
- References
- Code
- Notebooks
This page will provide a list of some commonly used 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 best-practises on how to use them.
```
A short description on basic features is given here. These pages will provide a list of some commonly used 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 best-practices on how to use them.

2
book/external/Nested-Books vendored

@ -1 +1 @@
Subproject commit 7ce10eb625c878f1fbd008b67bd266d61461541b
Subproject commit 4f72481f6a9b65c9b3bd22d0351b58b562f4802c

1
book/external/TeachBooks vendored Submodule

@ -0,0 +1 @@
Subproject commit c802630d700f579eff2ac990496503bdda57ca3b

2
book/external/latex-to-markdown-conversion vendored

@ -1 +1 @@
Subproject commit 0b9b6512da9ff9011e56897eb6837cc3ed89ee45
Subproject commit f71092bfdb2e3d5d2f580bac5e31ff695806e7d3

2
book/external/template vendored

@ -1 +1 @@
Subproject commit 2d5513da0a53b606f870890237ef4417dc18b398
Subproject commit 1ea4faffd395342b79b0bc995526ba254c2c4b63

4
book/features/HTML_javascript.md
View file

@ -13,4 +13,6 @@ This could be for example interactive 3d figures:
Or other interactive graphs:
<iframe src="../_static/element_pdf_and_cdf.html" width="600" height="300" frameborder="0"></iframe>
<iframe src="../_static/element_pdf_and_cdf.html" width="600" height="300" frameborder="0"></iframe>
<iframe src="https://openla.ewi.tudelft.nl/applet/lines_and_planes/normal_equation_plane_origin?iframe=true" width="600" height="500" allow="fullscreen" loading="lazy" frameborder="0"></iframe>

4
book/features/custom_toc.md
View file

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

2
book/features/h5p.md
View file

@ -6,7 +6,7 @@ This section is useful for user type 3-5.
```
## Instruction
H5p elements are interactive HTML-blocks which can be imbeded in a Jupyter Book using an iframe. 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:
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:
```html
<iframe src="https://tudelft.h5p.com/content/.../embed" aria-label="..." width="1088" height="200" frameborder="0" allowfullscreen="allowfullscreen" allow="autoplay *; geolocation *; microphone *; camera *; midi *; encrypted-media *"></iframe><script src="https://tudelft.h5p.com/js/h5p-resizer.js" charset="UTF-8"></script>

31
book/features/live_code.ipynb
View file

@ -4,9 +4,16 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"# Sphinx-thebe\n",
"# Run Python inside your book with Sphinx-thebe\n",
"\n",
"Our book has been enable to run Python code live in the browser (thanks Max!). 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",
"```{admonition} User types\n",
":class: tip\n",
"This section is useful for user type 5.\n",
"```\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",
"\n",
"To see this happening, click {fa}`rocket` --> {guilabel}`Live Code` on the top right corner of this page"
]
@ -29,7 +36,7 @@
"metadata": {},
"source": [
"## Setting up Python live coding\n",
"To set up the Python live coding you need to add our [own sphinx-thebe extension](https://gitlab.tudelft.nl/interactivetextbooks-citg/extensions/sphinx-thebe) to your book. This extensions doesn't rely on a 3rd party like Binder and it supports local python execution and custom features. Therefore, you need to add some lines to `requirements.txt` and `_config.yml`\n",
"To set up the Python live coding you need to add our [own sphinx-thebe extension](https://github.com/TeachBooks/Sphinx-Thebe) to your book. This extensions doesn't rely on a 3rd party like Binder and it supports local python execution and custom features. Therefore, you need to add some lines to `requirements.txt` and `_config.yml`\n",
"\n",
"For `requirements.txt` add the following lines:\n",
"```\n",
@ -37,7 +44,7 @@
"sphinx-thebe ~= 0.9.9\n",
"```\n",
"\n",
"This will download the correct version of the sphinx extension when the book is build on the server (which loads the required packages from `requirements.txt`)\n",
"This will download the correct version of the sphinx extension when the book is built on the server (which loads the required packages from `requirements.txt`)\n",
"\n",
"If you want to build the book locally, you need to install this version of sphinx-thebe in your environment as well with:\n",
"```\n",
@ -123,11 +130,25 @@
"%pip install package_name\n",
"```\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Alternative with JupyterLite (less well integrated)\n",
"Another option to use python in your browser is to use JupyterLite. However, this doesn't give a similar seamless interface. You could create 'iframe-like' Ipython consoles / jupyterbook / jupyter lab environments in your book. As these 'iframes' are separate modules added to your page, the integration with the other content in your book is less flexible as with our sphinx-thebe extension. Furthermore, the best way to use a JupyterLite session would be a separate repo with the jupyter lab interface anyway, so you get the full browser experience. Alternatively, the ipython REPL better can be usefull, as shown here: https://teachbooks.github.io/learn-python/main/Python_Toolbox.html."
]
}
],
"metadata": {
"kernelspec": {
"display_name": "base",
"language": "python",
"name": "python3"
},
"language_info": {
"name": "python"
"name": "python",
"version": "3.9.18"
}
},
"nbformat": 4,

17
book/features/overview.md
View file

@ -1,6 +1,6 @@
# TeachBooks Features
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 esential 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!
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
@ -8,18 +8,5 @@ This chapter provides a list of commonly used book features together with sub-pa
- how to use them
- where to find the source code
Overview of features covered:
- Interaction on the website: Adding comments and feedback to content on the website
- Grasple Questions: Explanation how to embed Grasple questions in the book.
- Adding interactive h5p elements: Embedding interactive HTML-blocks in the book
- Exclude parts of book from published book
- Page download options
- Python-enabled interactivity: Run Python code live in the browser
- Widgets
- Exercise checking using check-answer button
- JupyterLite-Sphinx: Including interactive pieces of content in the book.
- Configuration
- How to add `JupyterLite` to a page
To see examples for these features, go to the Example chapter.
To see examples for these features, go to the [Examples chapter](/book/examples/overview.md).

10
book/features/python_interactivity.md
View file

@ -1,10 +0,0 @@
# Python-enabled interactivity
```{admonition} User types
:class: tip
This section is useful for user type 5-6.
```
In general, there are two option to include python-enabled interactivity embedded in your book:
- Using our [own sphinx-thebe extension](./live_code.md) which 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!
- Using [JupyterLite](jupyterlite/jupyterlite.md) to create 'iframe-like' Ipython consoles / jupyterbook / jupyter lab environments in your book. As these 'iframes' are separate modules added to your page, the integration with the other content in your book is less flexible as with our sphinx-thebe extension.

25
book/installation-and-setup/creating_content.md
View file

@ -1,38 +1,33 @@
# Creating Content
# Content & Copyright
The previous sections have familiarized you with the necessary software for your user type, the basics of Git, and how to collaborate with your team using Git. TeachBooks provides a [template](https://teachbooks.tudelft.nl/jupyter-book-manual/external/template/README.html) you can use to create your book on GitHub, ensuring that your repository contains all the files you may need. Now it's time to create your own content. This section will provide an overview of these components and help you get started on your content.
The previous sections have familiarized you with the necessary software for your user type, the basics of Git, and how to collaborate with your team using Git. Now it's time to create your own content. This section will provide an overview of the copy right laws which need to be taking into account when creating and including content at TU Delft!
```{Important}
Please ensure you respect copy right laws when creating and including content! Don't forget to go through our checklist.
```
## Checklist
# Checklist - Copy Right
Although the focus of TeachBooks is mostly to help the teaching staff create interactive textbooks for their students, it can be attractive to spread ones wings a bit and reach a wider audience. The following section will be all about what you have to keep in mind in terms of copy right and what you should know to avoid major legal issues and make your life easier later on when/if you decide to publish your book with an open license, especially via TU Delft Open. For more information you can find everything on the [TU Delft website](https://www.tudelft.nl/library/support/copyright)
Although the focus of TeachBooks is mostly to help the teaching staff create interactive textbooks for their students, it can be attractive to spread ones wings a bit and reach a wider audience. The following section will be all about what you have to keep in mind in terms of copy right and what you should know to avoid major legal issues and make your life easier later on when/if you decide to publish your book with an open license, especially via TU Delft Open. For more information you can find everything on the [TU Delft Copyright website](https://www.tudelft.nl/library/support/copyright)
1) Your own new content
**1) Your own new content**
If you have created the content yourself, you are allowed to use it if there are no other agreements in place
2) Somebody else's content
**2) Somebody else's content**
If you want to re-use someone else’s work, you need to ask for permission. When you ask for permission please do it in a written format and let the copyright holders know that you are going to use their work in an open licensed work. If they give you permission, exclude the work from the open licensed conditions applicability, by stating that in the attribution/footnote/caption. Exclude it as well in the colophon of the work. If you have asked for permission and you received no answer back, please consider it as a negative response and abstain using the work you were intended to.
If you really need to re-use someone else’s work, please alsio check whether the copyright exception right to quote is applicable to you.
If you really need to re-use someone else’s work, please also check whether the copyright exception right to quote is applicable to you.
More info: [Citations](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131017) , [Use copyrighted multimedia](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131031) , [Use copyrighted text](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131032)
3) Your own old content
**3) Your own old content**
Always attribute the works that are not created by you. Even if created by you, you need to attribute yourself in order to avoid self-plagiarism. Read how to [here](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131032)
Even if you have created the work yourself but years ago, please check whether you have the right to re-use it. If you have created it while you were under the employment of your previous employer, then you will need to ask permission from them.
4) Open licensed work
**4) Open licensed work**
If you want to re-use someone else’s work, please check whether you can find an open licensed work, which can replace the work you wanted to re-use in the first place. More info: [Open licensed work platforms](https://www.tudelft.nl/library/collecties/open-educational-resources)
If you want to re-use someone else’s work, please check whether you can find an open licensed work, which can replace the work you wanted to re-use in the first place. More info: [Open licensed work platforms](https://www.tudelft.nl/en/library/collections/open-educational-resources)
If you use open licensed work, you need to attribute the license under which the work is licensed and you need to check the compatibility of the licenses. This means you need to check the license that the work you want to reuse has and the license that your TeachBook will be licensed with. More info [here](https://wiki.creativecommons.org/wiki/Wiki/cc_license_compatibility)

65
book/installation-and-setup/creating_content_backup.md
View file

@ -1,65 +0,0 @@
```{Notes Robert}
- the creating content page can be more like an overview/jumping off point (for example, it can point out that a book is 3 things: toc+config+content), then link to existing JB manual, example books, etc, but have a really big colorful box that warns about copyright
- on this main page it would be important to have a checklist for "what to do when starting a book" that includes choosing a license and how to avoid copyright issues, with links to supbages
- creating content subpages:
open source licenses: a short overview of types, pointing out that some are oriented on creative work, others on software. mostly pointing out we don't know the right answer but listing examples of what others have done so far
copyright page (this is where paschalis' bullet points should go)
```
# Creating Content
The previous sections have familiarized you with the necessary software for your user type, the basics of Git, and how to collaborate with your team using Git. TeachBooks provides a [template](https://teachbooks.tudelft.nl/jupyter-book-manual/external/template/README.html) you can use to create your book on GitHub, ensuring that your repository contains all the files you may need. Now it's time to create your own content. This section will provide an overview of these components and help you get started on your content.
# Building Blocks
Creating content for your Jupyter Book involves assembling several key components: the table of contents (`_toc.yml`), the configuration settings (`_config.yml`) and the actual content.
## Table of Contents
## Configuration
## Content
```{Important}
Please ensure you respect copy right laws when creating and including content! Don't forget to go through our checklist.
```
Markdown Files: Write your content in Markdown (.md) files. Markdown is a lightweight markup language with plain text formatting syntax.
Chapters and Sections: Organize your content into chapters and sections, with each chapter being a separate Markdown file.
# Checklist - Copy Right
Although the focus of TeachBooks is mostly to help the teaching staff create interactive textbooks for their students, it can be attractive to spread ones wings a bit and reach a wider audience. The following section will be all about what you have to keep in mind in terms of copy right and what you should know to avoid major legal issues and make your life easier later on when/if you decide to publish your book with an open license, especially via TU Delft Open. For more information you can find everything on the [TU Delft website](https://www.tudelft.nl/library/support/copyright)
1) Your own new content
If you have created the content yourself, you are allowed to use it if there are no other agreements in place
2) Somebody else's content
If you want to re-use someone else’s work, you need to ask for permission. When you ask for permission please do it in a written format and let the copyright holders know that you are going to use their work in an open licensed work. If they give you permission, exclude the work from the open licensed conditions applicability, by stating that in the attribution/footnote/caption. Exclude it as well in the colophon of the work. If you have asked for permission and you received no answer back, please consider it as a negative response and abstain using the work you were intended to.
If you really need to re-use someone else’s work, please alsio check whether the copyright exception right to quote is applicable to you.
More info: [Citations](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131017) , [Use copyrighted multimedia](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131031) , [Use copyrighted text](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131032)
3) Your own old content
Always attribute the works that are not created by you. Even if created by you, you need to attribute yourself in order to avoid self-plagiarism. Read how to [here](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131032)
Even if you have created the work yourself but years ago, please check whether you have the right to re-use it. If you have created it while you were under the employment of your previous employer, then you will need to ask permission from them.
4) Open licensed work
If you want to re-use someone else’s work, please check whether you can find an open licensed work, which can replace the work you wanted to re-use in the first place. More info: [Open licensed work platforms](https://www.tudelft.nl/library/collecties/open-educational-resources)
If you use open licensed work, you need to attribute the license under which the work is licensed and you need to check the compatibility of the licenses. This means you need to check the license that the work you want to reuse has and the license that your TeachBook will be licensed with. More info [here](https://wiki.creativecommons.org/wiki/Wiki/cc_license_compatibility)
When you want to adapt previously published work you need to ask permission for it. Otherwise please check whether you can find an open licensed work that you can adapt if their license it permits it.

BIN
book/installation-and-setup/figures/Terminal.PNG Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
book/installation-and-setup/figures/type 2.jpg
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 217 KiB

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

@ -5,28 +5,54 @@
This page is useful for user type 5.
```
<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> 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.
<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> 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](/book/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/"><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`.
```{admonition} Note
:class: tip
Don't forget to add the package `teachbooks` in the `requirements.txt` files in your book repository and to have it installed in your working environment (`pip install teachbooks`).
```
## 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/"><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. Only two notes: first navigate to the directory where your book is to leave out the `path-to-book` and use `--all` whenever building a book to make sure the table of contents fully updates:
As soon as you've installed your book environment with jupyter-book you can build your book locally. The official <a href="https://jupyterbook.org/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book"></a> documentation is quite extensive. You can navigate to the directory where your book is to leave out the `path-to-book`.
```
teachbooks build <path-to-book> --all
```
Alternatively:
```
jupyter-book build <path-to-book> --all
```
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.
## View the book locally
Once the build process is completed successfully, you will see the file location in your terminal output. Simply open this in the browser (you may have to copy/paste).
Once the build process is completed successfully, you will see the file location in your terminal output. Your terminal will look something like this. Simply open this in the browser (you may have to copy/paste).
```{figure} ./figures/Terminal.PNG
---
width: 80%
name: terminal
align: center
---
Terminal
```
```{admonition} Tip
:class: tip, dropdown
Bookmark the (local) file location for easy access!
```
(setup-local-server)=
## View the book using a local webserver
```{admonition} Note
:class: tip
If your book consists only of markdown files the local python server is not necessary and you can just view the book locally.
```
Some features like JupyterLite and Grasple only work when a webserver serves the HTML content for a book. Rather than building the book in your repository and updating the website on the internet, you can use a local webserver to view the book:
1. Make sure you have the TeachBooks Python package installed (e.g., `pip install teachbooks`)
2. Start a server from the command line with: `teachbooks serve`

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

@ -2,7 +2,8 @@
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.
1. **Students providing feedback on the published website**.<br> <img src="figures/type 1.jpg" alt="Example Image" align="right" width="130" style="margin: 10px;"> There are multiple tools of providing feedback in the built book: a) using the issue button in the top-right corner to directly create issues visible to the editor team. b) Using the [hypothesis](https://jupyterbook.org/en/stable/interactive/comments/hypothesis.html)-extension which allows public/private highlighting and annotating parts of the book. An example can be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html). c) Using the [Utterances](https://jupyterbook.org/en/stable/interactive/comments/utterances.html)-extension which allows commenting on pages for books which are hosted on GitHub visible for everyone. Those comments are converted to issues on GitHub for the editors to handle.
1. **Students providing feedback on the published website**.<br>
<img src="figures/type 1.jpg" alt="Example Image" align="right" width="130" style="margin: 20px;"><br>There are multiple tools of providing feedback in the built book:<br>a) using the issue button in the top-right corner to directly create issues visible to the editor team.<br>b) Using the [hypothesis](https://jupyterbook.org/en/stable/interactive/comments/hypothesis.html)-extension which allows public/private highlighting and annotating parts of the book. An example can be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html).<br>c) Using the [Utterances](https://jupyterbook.org/en/stable/interactive/comments/utterances.html)-extension which allows commenting on pages for books which are hosted on GitHub visible for everyone. Those comments are converted to issues on GitHub for the editors to handle.
2. **Colleague providing feedback on the draft website**. <br>
In a similar manner as students, colleages and team members can leave content related comments on the website through extensions. In this way, multiple teachers can give input in the draft of the textbook and course material without requiring and exact understanding of Jupyter Books or GitLab/GitHub. The responsible teacher (or student assistants) can then make the adaptations to the book as recommended by their colleagues.
@ -11,12 +12,9 @@ Different types of users will interact with the website or the Jupyter Books dif
This type of user requires only very basic knowledge in GitLab/GitHub in order to make changes to the website themselves without needing to install any software! Making adjustments using single text editor only requires the user to be able to login into GitLab/GitHub and edit .md or .ipynb files. The changes can be done directly in the main or publish branch and if a new branch is needed for the changes then the set-up and merging can be taken care of by someone more familiar in GitLab/GitHub.
4. **Colleague making text adjustments to multiple files at the same time locally**. <br>
User 4 is a hybrid between type 3 and 5. Basically this user is making changes by editing the .md files locally using, for example, VS Code. Therefore, this user requires a little bit more knowledge on git (think of pulling and pushing changes) but their main focus remains to make adjustments to the content of the book by editing .md files whereas user type 4 has more knowledge to make changes to python files the book as well. This user can build the book online.
User 4 is a hybrid between type 3 and 5. Basically this user is making changes by editing the .md files locally using, for example, VS Code. Therefore, this user requires a little bit more knowledge on git (think of pulling and pushing changes) but their main focus remains to make adjustments to the content of the book by editing .md files whereas user type 5 has more knowledge to make changes to python files the book as well. This user can build the book online.
5. **Colleague making text and code (especially Python) adjustments to multiple files at the same time locally**. <br>
<img src="figures/type 5.jpg" alt="Example Image" align="right" width="120" style="margin: 10px;">
<img src="figures/type 5.jpg" alt="Example Image" align="right" width="120" style="margin: 20px;"><br>This user has more knowledge in GitLab/GitHub than the previous user and can basically take care of branching and merging by themselves. They know how to work with software for editing .md and .ipynb files. They can use the draft book online to view their changed in the book, or build the book locally.
This user has more knowledge in GitLab/GitHub than the previous user and can basically take care of branching and merging by themselves. They know how to work with software for editing .md and .ipynb files. They can use the draft book online to view their changed in the book, or build the book locally.
<br style="clear:both;">

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

@ -15,10 +15,10 @@ VS Code can be downloaded from [here](https://code.visualstudio.com). The instal
When working with Jupyter Book (or Notebooks in general), these extensions are highly recommended:
- User type 4-6:
- User type 4-5:
- [MyST-Markdown](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) - adds support for MyST markdown, including previews.
- [Spell checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - Spelling checker for source code and text
- User type 5-6
- User type 5
- [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) - enables validation of `.yml` files (the format of the Jupyter Book configuration files).
- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) - for obvious reasons. Also includes Jupyter Notebook rendering.
- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) - Your AI pair progammer

3
requirements.txt
View file

@ -2,9 +2,8 @@ jupyter-book
teachbooks
sphinx-inline-tabs
jupyterlite-sphinx
jupyterbook_patches
--extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple
sphinx-thebe ~= 0.9.9
--extra-index-url https://gitlab.tudelft.nl/api/v4/projects/17983/packages/pypi/simple
jupyterbook_patches ~= 0.1.4
download_link_replacer @ git+https://gitlab.tudelft.nl/mude/sphinx-download-link-replacer