mirror of
https://github.com/TeachBooks/manual.git
synced 2026-11-13 23:05:51 +00:00
Compare commits
No commits in common. "release" and "V1.0.0" have entirely different histories.
167 changed files with 1284 additions and 8373 deletions
22
.github/dependabot.yml
vendored
22
.github/dependabot.yml
vendored
|
|
@ -1,22 +0,0 @@
|
|||
# To get started with Dependabot version updates, you'll need to specify which
|
||||
# package ecosystems to update and where the package manifests are located.
|
||||
# Please see the documentation for all configuration options:
|
||||
# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
|
||||
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "gitsubmodule" # See documentation for possible values
|
||||
directory: "/" # Location of package manifests
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "sunday"
|
||||
time: "22:59"
|
||||
- package-ecosystem: "pip" # See documentation for possible values
|
||||
directory: "/" # Location of package manifests
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "sunday"
|
||||
time: "22:59"
|
||||
ignore:
|
||||
- dependency-name: "sphinx-thebe"
|
||||
- dependency-name: "docutils"
|
||||
4
.github/workflows/call-deploy-book.yml
vendored
4
.github/workflows/call-deploy-book.yml
vendored
|
|
@ -4,15 +4,13 @@ on:
|
|||
push:
|
||||
branches:
|
||||
- '**'
|
||||
# - '!dependabot**'
|
||||
# If your git repository has the TeachBooks / Jupyter Book v1 within some-subfolder next to
|
||||
# If your git repository has the Jupyter Book 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.
|
||||
#
|
||||
paths:
|
||||
- book/**
|
||||
- .github/workflows/call-deploy-book.yml
|
||||
- requirements.txt
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
|
|
|
|||
6
.gitignore
vendored
6
.gitignore
vendored
|
|
@ -135,9 +135,3 @@ _contents/
|
|||
# Jupyterlite
|
||||
_output/
|
||||
book/.jupyterlite.doit.db
|
||||
|
||||
# TeachBooks
|
||||
**.teachbooks/
|
||||
book/_toc_with_local_paths.yml
|
||||
book/_git/
|
||||
book/conf.py
|
||||
70
.gitlab-ci.yml
Normal file
70
.gitlab-ci.yml
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
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
|
||||
image: continuumio/miniconda3
|
||||
rules:
|
||||
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
|
||||
script:
|
||||
- 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 == "release" && $CI_PIPELINE_SOURCE == "push"
|
||||
variables:
|
||||
TAG: $TAG_LATEST
|
||||
- if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push"
|
||||
variables:
|
||||
TAG: $TAG_DRAFT
|
||||
before_script:
|
||||
- docker info
|
||||
script:
|
||||
- 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 == "release" && $CI_PIPELINE_SOURCE == "push"
|
||||
before_script:
|
||||
- docker info
|
||||
- docker stop $CI_PROJECT_NAME || exit_code=$?
|
||||
- if [ $exit_code -ne 0 ]; then echo "Container not found, cannot stop"; else docker rm $CI_PROJECT_NAME; fi
|
||||
script:
|
||||
- docker run -d --restart always -p 8000:8000 --name $CI_PROJECT_NAME $TAG_LATEST # Make sure to use a different port for each book!
|
||||
environment:
|
||||
name: production
|
||||
url: https://interactivetextbooks.citg.tudelft.nl/jupyter-book-manual
|
||||
# Deploy the draft version of the book
|
||||
deploy-draft:
|
||||
stage: deploy
|
||||
image: docker
|
||||
rules:
|
||||
- if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push"
|
||||
before_script:
|
||||
- docker info
|
||||
- docker stop $CI_PROJECT_NAME-draft || exit_code=$?
|
||||
- if [ $exit_code -ne 0 ]; then echo "Container not found, cannot stop"; else docker rm $CI_PROJECT_NAME-draft; fi
|
||||
script:
|
||||
- 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
|
||||
51
.gitmodules
vendored
51
.gitmodules
vendored
|
|
@ -1,60 +1,27 @@
|
|||
[submodule "book/external/Nested-Books"]
|
||||
path = book/external/Nested-Books
|
||||
url = https://github.com/TeachBooks/Nested-Books.git
|
||||
branch = manual-description
|
||||
[submodule "book/external/template"]
|
||||
path = book/external/template
|
||||
url = https://github.com/TeachBooks/template.git
|
||||
branch = manual_description
|
||||
[submodule "book/external/deploy-book-workflow"]
|
||||
path = book/external/deploy-book-workflow
|
||||
url = https://github.com/TeachBooks/deploy-book-workflow.git
|
||||
branch = manual_docs
|
||||
[submodule "book/external/latex-to-markdown-conversion"]
|
||||
path = book/external/latex-to-markdown-conversion
|
||||
url = https://gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion.git
|
||||
[submodule "book/external/Useful_python_code"]
|
||||
path = book/external/Useful_python_code
|
||||
url = https://github.com/TeachBooks/Useful_python_code.git
|
||||
branch = manual
|
||||
[submodule "book/external/TeachBooks"]
|
||||
path = book/external/TeachBooks
|
||||
url = https://github.com/TeachBooks/TeachBooks.git
|
||||
[submodule "book/external/Sphinx-Image-Inverter"]
|
||||
path = book/external/Sphinx-Image-Inverter
|
||||
url = https://github.com/TeachBooks/Sphinx-Image-Inverter.git
|
||||
branch = Manual
|
||||
[submodule "book/external/Download-Link-Replacer"]
|
||||
path = book/external/Download-Link-Replacer
|
||||
url = https://github.com/TeachBooks/Download-Link-Replacer.git
|
||||
branch = manual_docs
|
||||
[submodule "book/external/Sphinx-Grasple-public"]
|
||||
path = book/external/Sphinx-Grasple-public
|
||||
url = https://github.com/TeachBooks/Sphinx-Grasple-public.git
|
||||
branch = manual_docs
|
||||
[submodule "book/external/Sphinx-TUDelft-theme"]
|
||||
path = book/external/Sphinx-TUDelft-theme
|
||||
url = https://github.com/TeachBooks/Sphinx-TUDelft-theme.git
|
||||
branch = Manual
|
||||
[submodule "book/external/teachbooks-sphinx-tippy"]
|
||||
path = book/external/teachbooks-sphinx-tippy
|
||||
url = https://github.com/TeachBooks/teachbooks-sphinx-tippy.git
|
||||
branch = Manual
|
||||
[submodule "book/external/annotater"]
|
||||
path = book/external/annotater
|
||||
url = https://github.com/TeachBooks/annotater
|
||||
branch = manual
|
||||
[submodule "book/external/Sphinx-launch-buttons"]
|
||||
path = book/external/Sphinx-launch-buttons
|
||||
url = https://github.com/TeachBooks/Sphinx-launch-buttons.git
|
||||
branch = manual
|
||||
[submodule "book/external/Sphinx-Named-Colors"]
|
||||
path = book/external/Sphinx-Named-Colors
|
||||
url = https://github.com/TeachBooks/Sphinx-Named-Colors.git
|
||||
branch = manual
|
||||
[submodule "book/external/sphinx-iframes"]
|
||||
path = book/external/sphinx-iframes
|
||||
url = https://github.com/TeachBooks/sphinx-iframes.git
|
||||
branch = manual
|
||||
[submodule "book/external/Sphinx-PRIME-applets"]
|
||||
path = book/external/Sphinx-PRIME-applets
|
||||
url = https://github.com/TeachBooks/Sphinx-PRIME-applets.git
|
||||
branch = manual
|
||||
[submodule "book/external/JupyterBook-Patches"]
|
||||
path = book/external/JupyterBook-Patches
|
||||
url = https://github.com/TeachBooks/JupyterBook-Patches.git
|
||||
branch = manual_docs
|
||||
[submodule "book/external/Download-Link-Replacer"]
|
||||
path = book/external/Download-Link-Replacer
|
||||
url = https://github.com/TeachBooks/Download-Link-Replacer.git
|
||||
|
|
|
|||
51
CITATION.cff
51
CITATION.cff
|
|
@ -1,51 +0,0 @@
|
|||
# This CITATION.cff file was generated with cffinit.
|
||||
# Visit https://bit.ly/cffinit to generate yours today!
|
||||
|
||||
cff-version: 1.2.0
|
||||
message: 'If you use this Book, please cite it using these metadata.'
|
||||
authors:
|
||||
- email: info@teachbooks.io
|
||||
name: 'TeachBooks Development Team'
|
||||
website: 'https://teachbooks.io/'
|
||||
title: 'TeachBooks Manual source code'
|
||||
preferred-citation:
|
||||
type: book
|
||||
authors:
|
||||
- email: info@teachbooks.io
|
||||
name: 'TeachBooks Development Team'
|
||||
website: 'https://teachbooks.io/'
|
||||
url: 'https://doi.org/10.5281/zenodo.15100847'
|
||||
identifiers:
|
||||
- type: doi
|
||||
value: 10.5281/zenodo.15100848
|
||||
description: Zenodo record
|
||||
- type: url
|
||||
value: 'https://teachbooks.io/manual/'
|
||||
description: 'Published book on GitHub Pages'
|
||||
- type: url
|
||||
value: 'https://github.com/TeachBooks/manual'
|
||||
description: 'GitHub repository'
|
||||
abstract: >-
|
||||
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
|
||||
and advanced usages for new and existing users with or without skills
|
||||
on this topic.
|
||||
keywords:
|
||||
- TeachBooks
|
||||
- Manual
|
||||
- 'Jupyter Book'
|
||||
title: 'TeachBooks Manual'
|
||||
institution:
|
||||
name: 'TeachBooks'
|
||||
license: CC-BY-4.0
|
||||
license-url: 'https://creativecommons.org/licenses/by/4.0/'
|
||||
copyright: '© 2025 TeachBooks'
|
||||
version: v1.2.1
|
||||
date-released: '2025-03-28'
|
||||
languages:
|
||||
- en
|
||||
contact:
|
||||
- email: info@teachbooks.io
|
||||
name: 'TeachBooks Development Team'
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
# All files in the repo
|
||||
* @Tom-van-Woudenberg
|
||||
8
Dockerfile
Normal file
8
Dockerfile
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
FROM continuumio/miniconda3
|
||||
WORKDIR /book
|
||||
COPY book/ .
|
||||
RUN apt-get update && apt-get -y install git gcc
|
||||
COPY requirements.txt requirements.txt
|
||||
RUN pip install -r requirements.txt
|
||||
RUN jupyter book build .
|
||||
ENTRYPOINT [ "python", "-m", "http.server", "8000", "--directory", "/book/_build/html" ]
|
||||
67
LICENSE
67
LICENSE
|
|
@ -1,7 +1,7 @@
|
|||
The license of this manual itself is CC BY 4.0. The same license is used for [](external/Nested-Books) and [](external/template). The license of other included materials are provided below.:
|
||||
|
||||
Attribution 4.0 International
|
||||
|
||||
=======================================================================
|
||||
|
||||
Creative Commons Corporation ("Creative Commons") is not a law firm and
|
||||
does not provide legal services or legal advice. Distribution of
|
||||
Creative Commons public licenses does not create a lawyer-client or
|
||||
|
|
@ -52,6 +52,8 @@ exhaustive, and do not form part of our licenses.
|
|||
for the public:
|
||||
wiki.creativecommons.org/Considerations_for_licensees
|
||||
|
||||
=======================================================================
|
||||
|
||||
Creative Commons Attribution 4.0 International Public License
|
||||
|
||||
By exercising the Licensed Rights (defined below), You accept and agree
|
||||
|
|
@ -371,6 +373,8 @@ Section 8 -- Interpretation.
|
|||
processes of any jurisdiction or authority.
|
||||
|
||||
|
||||
=======================================================================
|
||||
|
||||
Creative Commons is not a party to its public
|
||||
licenses. Notwithstanding, Creative Commons may elect to apply one of
|
||||
its public licenses to material it publishes and in those instances
|
||||
|
|
@ -389,62 +393,3 @@ the avoidance of doubt, this paragraph does not form part of the
|
|||
public licenses.
|
||||
|
||||
Creative Commons may be contacted at creativecommons.org.
|
||||
|
||||
=======================================================================
|
||||
|
||||
[](external/annotater), [](external/deploy-book-workflow), [](external/Download-Link-Replacer), [](external/JupyterBook-Patches), [](external/Sphinx-Image-Inverter), [](external/Sphinx-launch-buttons) and [](external/Useful_python_code) are licensed under BSD 3-Clause license:
|
||||
|
||||
BSD 3-Clause License
|
||||
|
||||
Copyright (c) 2024, TeachBooks
|
||||
|
||||
Redistribution and use in source and binary forms, with or without
|
||||
modification, are permitted provided that the following conditions are met:
|
||||
|
||||
1. Redistributions of source code must retain the above copyright notice, this
|
||||
list of conditions and the following disclaimer.
|
||||
|
||||
2. Redistributions in binary form must reproduce the above copyright notice,
|
||||
this list of conditions and the following disclaimer in the documentation
|
||||
and/or other materials provided with the distribution.
|
||||
|
||||
3. Neither the name of the copyright holder nor the names of its
|
||||
contributors may be used to endorse or promote products derived from
|
||||
this software without specific prior written permission.
|
||||
|
||||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||||
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||||
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
||||
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
||||
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
||||
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
||||
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||||
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
=======================================================================
|
||||
|
||||
[](external/Sphinx-Grasple-public), [](external/Sphinx-TUDelft-theme) and [](external/teachbooks-sphinx-tippy) are licensed under MIT license:
|
||||
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2024, TeachBooks
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
|
|
|
|||
18
README.md
18
README.md
|
|
@ -1,23 +1,19 @@
|
|||
# TeachBooks Manual
|
||||
|
||||
[](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 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/).
|
||||
This manual assists you in creating and collaborating on [JupyterBooks](https://jupyterbook.org/) 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.tudelft.nl/](https://teachbooks.tudelft.nl/).
|
||||
|
||||
## 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 encounter any issues and you have a TU Delft account, report it by clicking <svg class="svg-inline--fa fa-gitlab" aria-hidden="true" focusable="false" data-prefix="fab" data-icon="gitlab" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" data-fa-i2svg=""><path fill="currentColor" d="M503.5 204.6L502.8 202.8L433.1 21.02C431.7 17.45 429.2 14.43 425.9 12.38C423.5 10.83 420.8 9.865 417.9 9.57C415 9.275 412.2 9.653 409.5 10.68C406.8 11.7 404.4 13.34 402.4 15.46C400.5 17.58 399.1 20.13 398.3 22.9L351.3 166.9H160.8L113.7 22.9C112.9 20.13 111.5 17.59 109.6 15.47C107.6 13.35 105.2 11.72 102.5 10.7C99.86 9.675 96.98 9.295 94.12 9.587C91.26 9.878 88.51 10.83 86.08 12.38C82.84 14.43 80.33 17.45 78.92 21.02L9.267 202.8L8.543 204.6C-1.484 230.8-2.72 259.6 5.023 286.6C12.77 313.5 29.07 337.3 51.47 354.2L51.74 354.4L52.33 354.8L158.3 434.3L210.9 474L242.9 498.2C246.6 500.1 251.2 502.5 255.9 502.5C260.6 502.5 265.2 500.1 268.9 498.2L300.9 474L353.5 434.3L460.2 354.4L460.5 354.1C482.9 337.2 499.2 313.5 506.1 286.6C514.7 259.6 513.5 230.8 503.5 204.6z"></path></svg> --> {fa}`lightbulb` on the top right corner of this page. Or contribute directly by creating a merge request in the [repository](https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-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)
|
||||
If you have questions, contact Tom van Woudenberg, Robert Lanzafame or our TA Julie Kirsch at TeachBooks@tudelft.nl, also for non-TU Delft account holders. TU Delft account holder can also contact us in the [MS Teams Open Interactive Textbooks Community](https://teams.microsoft.com/l/team/19%3Ah9-uRcP_yYauh-VuoPFozJVUvHVOB4a0mz1ZWvh4q4Q1%40thread.tacv2/conversations?groupId=3e88c1f3-4a4f-483a-a366-7e617de9ba99&tenantId=096e524d-6929-4030-8cd3-8ab42de0887b)
|
||||
|
||||
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).
|
||||
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).
|
||||
|
||||
## 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.
|
||||
This book will continue to develop, so feel free to contribute https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual! You can do so directly by forking this repository and creating a merge request.
|
||||
|
||||
The released book can be found on on https://teachbooks.io/manual. This page shows the built book of the `release` branch All branches will also be visible as seen in the action's summaries: https://github.com/TeachBooks/mirror_teachbook_manual/actions
|
||||
The released book can be found on on https://teachbooks.tudelft.nl/jupyter-book-manual. This page shows the built book of the `release` branch. The `main` branch is meant for reviewing and is visible here: https://teachbooks.tudelft.nl/jupyter-book-manual/draft. All branches will also be visible on the mirrored repository on GitHub Pages: https://github.com/TeachBooks/mirror_teachbook_manual/actions
|
||||
|
||||
Some parts of this book are taken from other sources in the form of submodules (linked in the folder [book/external](book/external)). To contribute to those pages, contribute to the source repository directly with a fork and merge/pull request. If you intent to clone this book including its submodules, clone using: `git clone --recurse-submodules git@github.com:TeachBooks/manual.git`
|
||||
Some parts of this book are taken from other sources in the form of submodules (linked in the folder [book/external](book/external)). To contribute to those pages, contribute to the source repository directly with a fork and merge/pull request. If you intent to clone this boko including its submodules, clone using: `git clone --recurse-submodules git@gitlab.tudelft.nl:interactivetextbooks-citg/jupyter-book-manual.git`
|
||||
|
||||
Happy book building!
|
||||
|
||||
|
|
|
|||
4
WAIVER
4
WAIVER
|
|
@ -1,4 +0,0 @@
|
|||
Technische Universiteit Delft hereby disclaims all copyright interest in the
|
||||
program “TeachBooks Manual” (a book serving as documentation for various tooling
|
||||
surrounding TeachBooks) written by the Author(s).
|
||||
Stefan Aarninkhof, Dean of Civil Engineering & Geosciences
|
||||
|
|
@ -1,62 +1,38 @@
|
|||
title: TeachBooks Manual
|
||||
author: TeachBooks Development Team and TeachBooks users, built with <a href="https://teachbooks.io/">TeachBooks</a>, <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer"">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt=""></a>
|
||||
author: TeachBooks Team from Delft University of Technology, built with <a href="https://teachbooks.tudelft.nl/">TeachBooks</a> and <a href="https://jupyterbook.org/">Jupyter Book</a>, <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer"">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt=""></a>
|
||||
|
||||
logo: images/Logo_without_background.png
|
||||
|
||||
execute:
|
||||
execute_notebooks: 'auto'
|
||||
execute_notebooks: 'off'
|
||||
|
||||
only_build_toc_files: true
|
||||
|
||||
html:
|
||||
favicon : "images/favicon.ico"
|
||||
baseurl : "https://teachbooks.io/manual/"
|
||||
baseurl : "https://teachbooks.tudelft.nl/jupyter-book-manual/"
|
||||
# START REMOVE-FROM-PUBLISH
|
||||
comments:
|
||||
hypothesis: true
|
||||
# END REMOVE-FROM-PUBLISH
|
||||
|
||||
sphinx:
|
||||
extra_extensions:
|
||||
- sphinx_inline_tabs
|
||||
- sphinx.ext.imgconverter
|
||||
- teachbooks_favourites
|
||||
- teachbooks_sphinx_grasple
|
||||
- sphinx_apa_references
|
||||
- download_link_replacer
|
||||
- jupyterbook_patches
|
||||
config:
|
||||
language: en
|
||||
html_js_files:
|
||||
- https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js
|
||||
thebe_config:
|
||||
use_thebe_lite: true
|
||||
exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb","**/*.gif","**/*.txt","**/*.json",]
|
||||
html_theme_options:
|
||||
logo:
|
||||
text: Manual
|
||||
image_light: TeachBooks_logo.svg
|
||||
image_dark: TeachBooks_logo_inverted.svg
|
||||
repository_url: "https://github.com/TeachBooks/manual/"
|
||||
path_to_docs: "book"
|
||||
repository_branch: "release"
|
||||
repository_url: "https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual"
|
||||
use_repository_button: true
|
||||
use_edit_page_button: true
|
||||
use_issues_button : true
|
||||
launch_buttons:
|
||||
thebe: true
|
||||
html_show_copyright: false
|
||||
html_last_updated_fmt: '%B %-d, %Y'
|
||||
html_static_path: ["images"]
|
||||
mathjax3_config:
|
||||
tex:
|
||||
macros:
|
||||
"newcolor": ['\definecolor{newcolor}{RGB}{111, 29, 119}{\color{newcolor}#1}',1]
|
||||
named_colors_custom_colors: {'onlylight':[165,21,160],'lightanddark':[45,180,117,204,158,110],'hyphen-color':[45,180,117,165,21,160],'attributiongrey':[150,150,150]}
|
||||
metadata_figure_settings:
|
||||
style:
|
||||
placement: hide
|
||||
license:
|
||||
summaries: false
|
||||
individual: false
|
||||
nb_execution_includepatterns: "**/MANUAL.ipynb"
|
||||
git_show_all_authors: true
|
||||
|
||||
teachbooks:
|
||||
attribution_location: margin
|
||||
attribution_color: attributiongrey
|
||||
|
||||
bibtex_bibfiles:
|
||||
- references.bib
|
||||
|
|
|
|||
|
|
@ -1,4 +0,0 @@
|
|||
/* Attribution */
|
||||
div.attribution > .admonition-title::after {
|
||||
content: "\f10d";
|
||||
}
|
||||
|
|
@ -1,19 +0,0 @@
|
|||
:root {
|
||||
--newcolor-light: rgb(111, 29, 119);
|
||||
--newcolor-dark: rgb(255, 167, 255);
|
||||
--newcolor: var(--newcolor-light);
|
||||
}
|
||||
|
||||
html[data-theme="dark"] {
|
||||
--newcolor: var(--newcolor-dark);
|
||||
}
|
||||
|
||||
.newcolor {color: var(--newcolor);}
|
||||
|
||||
.newcolor-same {color: var(--newcolor-light);}
|
||||
|
||||
.newcolor-filter {color: var(--newcolor-light);}
|
||||
|
||||
html[data-theme="dark"] .newcolor-filter {
|
||||
filter: invert(1) hue-rotate(180deg) saturate(1.5);
|
||||
}
|
||||
|
|
@ -255,7 +255,7 @@ const createFigureReference = (path, name, caption) => {
|
|||
+ "{numref}`{number} <" + name + ">`";
|
||||
}
|
||||
|
||||
//Via https://jupyterbook.org/v1/content/references.html#reference-tables
|
||||
//Via https://jupyterbook.org/en/stable/content/references.html#reference-tables
|
||||
const createTableReference = (caption, name) => {
|
||||
return "<b> tabel code: </b><br/>"
|
||||
+"```{table} " + caption + "<br/>"
|
||||
|
|
|
|||
|
|
@ -1,178 +0,0 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>CO2 vs Power</title>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/numeric/1.2.6/numeric.min.js"></script>
|
||||
<script src="https://cdn.plot.ly/plotly-latest.min.js"></script>
|
||||
<style>
|
||||
.slider {
|
||||
display: block;
|
||||
margin-bottom: 10px;
|
||||
width: 100%;
|
||||
}
|
||||
.slider-container {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(3, 1fr);
|
||||
grid-gap: 10px;
|
||||
width: 100%;
|
||||
}
|
||||
.output {
|
||||
margin-top: 20px;
|
||||
padding: 10px;
|
||||
border: 1px solid #ccc;
|
||||
border-radius: 5px;
|
||||
background-color: #f9f9f9;
|
||||
}
|
||||
.output p {
|
||||
margin: 5px 0;
|
||||
}
|
||||
.output .emoji {
|
||||
font-size: 20px;
|
||||
margin-right: 5px;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div id="sliderContainer" class="slider-container"></div>
|
||||
<div id="outputContainer" class="output"></div>
|
||||
|
||||
<script>
|
||||
var RPM = [800, 1000, 1200, 1400, 1700, 1800];
|
||||
var CO2 = [708, 696.889, 688.247, 682.897, 684.955, 697.3];
|
||||
var POW = [161.141, 263.243, 330.51, 381.561, 391.17, 370];
|
||||
|
||||
function weighted_obj(s) {
|
||||
var delta_p = 1 / 3;
|
||||
var delta_c = 1 - delta_p;
|
||||
return -delta_p * POWfunc(s) + delta_c * CO2func(s);
|
||||
}
|
||||
|
||||
var Pt = 460;
|
||||
var Ct = 640;
|
||||
function goal_attainment(s) {
|
||||
return Math.max(Pt - POWfunc(s), CO2func(s) - Ct);
|
||||
}
|
||||
|
||||
function CO2func(s) {
|
||||
return interpolate(RPM, CO2, s);
|
||||
}
|
||||
|
||||
function POWfunc(s) {
|
||||
return interpolate(RPM, POW, s);
|
||||
|
||||
}
|
||||
|
||||
function interpolate(x, y, s) {
|
||||
var i = 1;
|
||||
while (x[i] < s) {
|
||||
i++;
|
||||
}
|
||||
var x0 = x[i - 1];
|
||||
var x1 = x[i];
|
||||
var y0 = y[i - 1];
|
||||
var y1 = y[i];
|
||||
var t = (s - x0) / (x1 - x0);
|
||||
|
||||
// Calculate the coefficients for the cubic spline interpolation
|
||||
var h = x1 - x0;
|
||||
var a = (1 - t) * (1 - t) * (1 - t);
|
||||
var b = 3 * t * (1 - t) * (1 - t);
|
||||
var c = 3 * t * t * (1 - t);
|
||||
var d = t * t * t;
|
||||
|
||||
// Perform cubic spline interpolation
|
||||
var interpolatedValue = a * y0 + b * y[i - 1] + c * y[i] + d * y1;
|
||||
|
||||
return interpolatedValue;
|
||||
}
|
||||
|
||||
function func(x) {
|
||||
|
||||
var weighted_obj_val = weighted_obj(x).toFixed(2);
|
||||
var goal_attainment_val = goal_attainment(x).toFixed(2);
|
||||
|
||||
var outputContainer = document.getElementById("outputContainer");
|
||||
var weighted_obj_val = weighted_obj(x).toFixed(2);
|
||||
var goal_attainment_val = goal_attainment(x).toFixed(2);
|
||||
var POWfunc_val = POWfunc(x).toFixed(2);
|
||||
var CO2func_val = CO2func(x).toFixed(2);
|
||||
|
||||
outputContainer.innerHTML = "<p>Weighted 🏋️ Objective: " + " = - 1/3 * POWfunc(" + x + ") + 2/3 * CO2func(" + x + ") = - 1/3 * " + POWfunc_val + " + 2/3 * " + CO2func_val + " = " + weighted_obj_val + "</p>" +
|
||||
"<p>Goal 🥅 Attainment: max(460 - POWfunc(" + x + "), CO2func(" + x + ") - 640) = max(460 - " + POWfunc_val + ", " + CO2func_val + " - 640) = " + goal_attainment_val ;
|
||||
|
||||
var plotContainer = document.createElement("div");
|
||||
plotContainer.id = "plotContainer";
|
||||
plotContainer.style.height = "400px";
|
||||
outputContainer.appendChild(plotContainer);
|
||||
|
||||
var plotData = [
|
||||
{
|
||||
x: [CO2func(parseFloat(document.getElementById("x").value))],
|
||||
y: [POWfunc(parseFloat(document.getElementById("x").value))],
|
||||
type: 'scatter',
|
||||
mode: 'markers',
|
||||
name: 'Selected RPM'
|
||||
}
|
||||
];
|
||||
|
||||
var plotLayout = {
|
||||
xaxis: {
|
||||
title: 'CO2 (g/kWh)',
|
||||
range: [680, 710]
|
||||
},
|
||||
yaxis: {
|
||||
title: 'Power functions (kW)',
|
||||
range: [400, 150], // Flipped y-axis range
|
||||
},
|
||||
title: {
|
||||
text: 'CO2 vs Power',
|
||||
font: {
|
||||
size: 16
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
Plotly.newPlot('plotContainer', plotData, plotLayout);
|
||||
}
|
||||
|
||||
var sliderContainer = document.getElementById("sliderContainer");
|
||||
var xSlider = document.createElement("input");
|
||||
xSlider.type = "range";
|
||||
xSlider.min = 800;
|
||||
xSlider.max = 1800;
|
||||
xSlider.value = 1000;
|
||||
xSlider.step = 1;
|
||||
xSlider.id = "x";
|
||||
xSlider.oninput = function() {
|
||||
func(parseFloat(document.getElementById("x").value));
|
||||
};
|
||||
xSlider.classList.add("slider");
|
||||
|
||||
var xLabel = document.createElement("label");
|
||||
xLabel.innerHTML = "RPM";
|
||||
xLabel.setAttribute("for", "x");
|
||||
xLabel.style.textAlign = "right";
|
||||
|
||||
var valueDisplay = document.createElement("span");
|
||||
valueDisplay.innerHTML = xSlider.value; // Set the initial value of the display element
|
||||
valueDisplay.style.marginLeft = "10px"; // Add some margin to separate the value from the slider
|
||||
|
||||
xSlider.oninput = function() {
|
||||
valueDisplay.innerHTML = xSlider.value; // Update the value display element when the slider value changes
|
||||
func(parseFloat(document.getElementById("x").value));
|
||||
};
|
||||
|
||||
sliderContainer.appendChild(xLabel);
|
||||
sliderContainer.appendChild(xSlider);
|
||||
sliderContainer.appendChild(valueDisplay); // Append the value display element
|
||||
|
||||
|
||||
var outputContainer = document.getElementById("outputContainer");
|
||||
outputContainer.style.height = "400px";
|
||||
|
||||
|
||||
// Call func with initial values
|
||||
func(parseFloat(document.getElementById("x").value));
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
/* Hide the default Jupyter Book author footer */
|
||||
.component-author {
|
||||
display: none;
|
||||
}
|
||||
144
book/_toc.yml
144
book/_toc.yml
|
|
@ -2,18 +2,10 @@ format: jb-book
|
|||
root: intro
|
||||
|
||||
parts:
|
||||
- caption: Your First TeachBook!
|
||||
chapters:
|
||||
- file: intro/book.md
|
||||
- file: intro/workflow.md
|
||||
- file: intro/template.md
|
||||
- file: intro/next.md
|
||||
- caption: Getting Going!
|
||||
- caption: Getting started!
|
||||
chapters:
|
||||
- file: installation-and-setup/user_types.md
|
||||
- file: installation-and-setup/git.md
|
||||
sections:
|
||||
- file: installation-and-setup/tools
|
||||
- file: installation-and-setup/overview.md
|
||||
sections:
|
||||
- file: installation-and-setup/vscode-setup.md
|
||||
|
|
@ -21,6 +13,7 @@ parts:
|
|||
- file: installation-and-setup/anaconda.md
|
||||
- file: installation-and-setup/git_bash_conda_vs-code.md
|
||||
- file: installation-and-setup/jupyter-book-setup.md
|
||||
- file: external/template/README.md
|
||||
- file: workflows/collaboration.md
|
||||
sections:
|
||||
- file: workflows/milestones_issues.md
|
||||
|
|
@ -29,87 +22,11 @@ parts:
|
|||
- file: workflows/check_changes_online.md
|
||||
- file: workflows/merge_request.md
|
||||
- file: installation-and-setup/collab
|
||||
- file: installation-and-setup/versioning
|
||||
sections:
|
||||
- file: installation-and-setup/versions_URLs
|
||||
- file: installation-and-setup/versioning_changelog
|
||||
- file: installation-and-setup/publisher
|
||||
- file: installation-and-setup/copyright.md
|
||||
sections:
|
||||
- file: installation-and-setup/copyright/considerations
|
||||
- file: installation-and-setup/copyright/licenses
|
||||
- file: installation-and-setup/copyright/recommendations
|
||||
- file: installation-and-setup/tools
|
||||
- file: installation-and-setup/creating_content.md
|
||||
- caption: Features
|
||||
chapters:
|
||||
- file: features/overview.md
|
||||
sections:
|
||||
- file: features/teachbooks_intro.md
|
||||
- file: external/deploy-book-workflow/README.md
|
||||
- file: features/favourites.md
|
||||
- file: external/template/README.md
|
||||
- file: features/easy-editing.md
|
||||
sections:
|
||||
- file: features/write_online.md
|
||||
- file: features/release_book_online.md
|
||||
- file: features/draft-release
|
||||
- file: features/pull_request_build.md
|
||||
- file: features/local_server
|
||||
- file: features/external_toc
|
||||
sections:
|
||||
- file: external/Nested-Books/README.md
|
||||
title: (Deprecated) Share content between books using submodules
|
||||
- file: features/update_env
|
||||
- file: features/versioning
|
||||
- file: features/sphinx_extensions.md
|
||||
sections:
|
||||
- file: external/Download-Link-Replacer/README.md
|
||||
- file: external/Sphinx-launch-buttons/README.md
|
||||
- file: basic-features/utterances.md
|
||||
- file: features/h5p.md
|
||||
sections:
|
||||
- file: examples/h5p_examples.md
|
||||
- file: features/plotly.ipynb
|
||||
- file: external/Sphinx-Grasple-public/README.md
|
||||
- file: features/HTML_javascript.md
|
||||
sections:
|
||||
- file: features/adding_HTML_elements.md
|
||||
- file: features/creating_basic_HTML_elements.md
|
||||
- file: features/live_code
|
||||
sections:
|
||||
- file: features/widgets.ipynb
|
||||
- file: features/exercise_checking.ipynb
|
||||
- file: features/jupyterquiz.ipynb
|
||||
- file: external/sphinx-iframes/README.md
|
||||
- external: https://github.com/TeachBooks/Sphinx-Indexed-Definitions/blob/manual/README.md
|
||||
- file: external/Sphinx-PRIME-applets/README.md
|
||||
- external: "https://github.com/TeachBooks/sphinx-code-examples/blob/main/MANUAL.ipynb"
|
||||
- file: features/sphinx-proof.md
|
||||
- external: "https://github.com/TeachBooks/Sphinx-NB-Execution-Patterns/blob/Manual/README.md"
|
||||
- file: features/exercise.md
|
||||
- external: https://github.com/TeachBooks/Sphinx-ref-graph/blob/manual/README.md
|
||||
- external: https://github.com/TeachBooks/Sphinx-GitHub-Alerts/blob/main/README.md
|
||||
- external: https://github.com/TeachBooks/Sphinx-Metadata-Figure/blob/main/MANUAL.ipynb
|
||||
- external: https://github.com/TeachBooks/Sphinx-Gated-Directives/blob/main/MANUAL.md
|
||||
- external: https://github.com/TeachBooks/TeachBooks-Questions/blob/main/MANUAL.md
|
||||
- external: https://github.com/TeachBooks/TeachBooks-Fetch/blob/main/MANUAL.md
|
||||
- file: features/visuals.md
|
||||
sections:
|
||||
- external: https://github.com/TeachBooks/Sphinx-Accessibility/blob/manual/README.md
|
||||
- file: external/Sphinx-Image-Inverter/README.md
|
||||
- file: external/JupyterBook-Patches/README.md
|
||||
- file: external/Sphinx-TUDelft-theme/README.md
|
||||
- file: external/teachbooks-sphinx-tippy/README.md
|
||||
- file: features/apa
|
||||
- file: external/Sphinx-Named-Colors/README.md
|
||||
- external: https://github.com/TeachBooks/Sphinx-Dropdown-Toggle/blob/main/MANUAL.md
|
||||
- external: https://github.com/TeachBooks/Sphinx-Sticky-Margin/blob/main/MANUAL.md
|
||||
- file: features/students
|
||||
sections:
|
||||
- file: external/annotater/README.md
|
||||
- file: basic-features/hypothesis.md
|
||||
- caption: Original Jupyter Book v1 and Sphinx Features
|
||||
chapters:
|
||||
- file: basic-features/overview.md
|
||||
- file: basic-features/overview
|
||||
sections:
|
||||
- file: basic-features/jupyterbook.md
|
||||
- file: basic-features/figures.md
|
||||
|
|
@ -118,35 +35,50 @@ parts:
|
|||
- file: basic-features/References.md
|
||||
- file: basic-features/code.md
|
||||
- file: basic-features/Code_block_figures
|
||||
- file: basic-features/badges.md
|
||||
- file: basic-features/banner
|
||||
title: Banner or Announcement
|
||||
- file: basic-features/hypothesis.md
|
||||
- file: basic-features/utterances.md
|
||||
- file: features/overview.md
|
||||
sections:
|
||||
- file: external/TeachBooks/README.md
|
||||
- file: external/deploy-book-workflow/README.md
|
||||
- file: external/Nested-Books/README.md
|
||||
- file: external/Download-Link-Replacer/README.md
|
||||
- file: external/Sphinx-Image-Inverter/README.md
|
||||
- file: external/JupyterBook-Patches/README.md
|
||||
- file: features/interactive_element.ipynb
|
||||
sections:
|
||||
- file: features/grasple.md
|
||||
- file: features/h5p.md
|
||||
- file: features/HTML_javascript.md
|
||||
sections:
|
||||
- file: features/adding_HTML_elements.md
|
||||
- file: features/creating_basic_HTML_elements.md
|
||||
- file: features/live_code
|
||||
sections:
|
||||
- file: features/widgets.ipynb
|
||||
- file: features/exercise_checking.ipynb
|
||||
|
||||
- caption: Examples
|
||||
chapters:
|
||||
- file: examples/overview.md
|
||||
sections:
|
||||
- file: examples/book_structure.md
|
||||
- file: examples/live_code.md
|
||||
- file: examples/example_gumbel.ipynb
|
||||
- file: examples/theory_questions.md
|
||||
- file: examples/example_quiz_interactive.ipynb
|
||||
- file: examples/coding_theory_widgets.ipynb
|
||||
- file: examples/parametric_questions.ipynb
|
||||
- file: examples/book_structure.md
|
||||
- file: examples/h5p_examples.md
|
||||
- file: examples/live_code.md
|
||||
- file: examples/example_gumbel.ipynb
|
||||
- file: examples/theory_questions.md
|
||||
- file: examples/example_quiz_interactive.ipynb
|
||||
- file: examples/coding_theory_widgets.ipynb
|
||||
- file: examples/parametric_questions.ipynb
|
||||
|
||||
- caption: Editing Tools
|
||||
- caption: Editing tools
|
||||
chapters:
|
||||
- file: tools/figmaker
|
||||
- file: helper_code/intro.md
|
||||
sections:
|
||||
- file: helper_code/converter.md
|
||||
- file: helper_code/move_images.md
|
||||
- file: external/latex-to-markdown-conversion/README.md
|
||||
- file: external/Useful_python_code/snippit.ipynb
|
||||
- file: external/Useful_python_code/extensionfildownloadreturn.ipynb
|
||||
- file: external/Useful_python_code/figshrinker.ipynb
|
||||
|
||||
- caption: Miscellaneous
|
||||
chapters:
|
||||
- file: references.md
|
||||
- file: credits
|
||||
- file: changelog
|
||||
- file: contact
|
||||
|
|
|
|||
|
|
@ -1,178 +0,0 @@
|
|||
# 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 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
|
||||
|
||||
Badges are small visual indicators often used to convey concise or important information. They can be very useful for categorising or tagging content for the reader like has been done for the subchapters under the [features](../features/overview.md) chapter of this manual.
|
||||
|
||||
There are three types of badges: plain, link and reference (for cross references within book) which are fully customizable and can simply be added with Markdown syntax:
|
||||
|
||||
| Type | Badge | Code Syntax |
|
||||
|--------|----------------------------------------------------------|------------------------------------------------------------------------|
|
||||
| Plain | {bdg-primary}`plain_text` | ``` {bdg-primary}`plain_text` ```
|
||||
| Link | {bdg-link-primary}`https://teachbooks.io/` | ``` {bdg-link-primary}`https://teachbooks.io/` ``` |
|
||||
| Hidden Link | {bdg-link-primary}`TeachBooks <https://https://teachbooks.io/>` | ``` {bdg-link-primary}`TeachBooks <https://https://teachbooks.io/> ` ``` |
|
||||
| Reference | {bdg-ref-primary}`my_ref` | ``` {bdg-ref-primary}`my_ref` ``` |
|
||||
|
||||
Here's an overview of all the available colours:
|
||||
|
||||
| Full Colour | Code Syntax | Colour Outline | Code Syntax |
|
||||
|-------------------------------|----------------------------------|-------------------------------|---------------------------------------|
|
||||
| {bdg}`my_text` | ``` {bdg}`my_text` ``` | | |
|
||||
| {bdg-primary}`my_text` | ``` {bdg-primary}`my_text` ``` | {bdg-primary-line}`my_text` | ``` {bdg-primary-line}`my_text` ``` |
|
||||
| {bdg-secondary}`my_text` | ``` {bdg-secondary}`my_text` ``` | {bdg-secondary-line}`my_text` | ``` {bdg-secondary-line}`my_text` ``` |
|
||||
| {bdg-success}`my_text` | ``` {bdg-success}`my_text` ``` | {bdg-success-line}`my_text` | ``` {bdg-success-line}`my_text` ``` |
|
||||
| {bdg-info}`my_text` | ``` {bdg-info}`my_text` ``` | {bdg-info-line}`my_text` | ``` {bdg-info-line}`my_text` ``` |
|
||||
| {bdg-warning}`my_text` | ``` {bdg-warning}`my_text` ``` | {bdg-warning-line}`my_text` | ``` {bdg-warning-line}`my_text` ``` |
|
||||
| {bdg-danger}`my_text` | ``` {bdg-danger}`my_text` ``` | {bdg-danger-line}`my_text` | ``` {bdg-danger-line}`my_text` ``` |
|
||||
| {bdg-light}`my_text` | ``` {bdg-light}`my_text` ``` | {bdg-light-line}`my_text` | ``` {bdg-light-line}`my_text` ``` |
|
||||
| {bdg-muted}`my_text` | ``` {bdg-muted}`my_text` ``` | {bdg-muted-line}`my_text` | ``` {bdg-muted-line}`my_text` ``` |
|
||||
| {bdg-dark}`my_text` | ``` {bdg-dark}`my_text` ``` | {bdg-dark-line}`my_text` | ``` {bdg-dark-line}`my_text` ``` |
|
||||
| {bdg-white}`my_text` | ``` {bdg-white}`my_text` ``` | {bdg-white-line}`my_text` | ``` {bdg-white-line}`my_text` ``` |
|
||||
| {bdg-black}`my_text` | ``` {bdg-black}`my_text` ``` | {bdg-black-line}`my_text` | ``` {bdg-black-line}`my_text` ``` |
|
||||
|
||||
|
||||
## 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 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:
|
||||
|
||||
```{button-link} https://teachbooks.io
|
||||
:color: primary
|
||||
```
|
||||
|
||||
```
|
||||
```{button-link} https://teachbooks.io
|
||||
:color: primary
|
||||
```
|
||||
```
|
||||
[](../features/overview.md)
|
||||
```{button-ref} feature_overview
|
||||
:color: secondary
|
||||
```
|
||||
|
||||
```
|
||||
```{button-ref} feature_overview
|
||||
:color: secondary
|
||||
```
|
||||
```
|
||||
|
||||
Buttons can be customized in markdown in a similar way as figures. You can experiment with these styles to create buttons that align with your book's theme. Here are the set of parameters which can be customized:
|
||||
|
||||
|
||||
| Parameter | Options | Functionality |
|
||||
|-------------------------------|----------------------------------|-------------------------------|
|
||||
| color | primary, secondary, success, danger, warning, info, light, dark, muted | Set the color of the button (background and font)|
|
||||
| outline | / | white button, coloured outline|
|
||||
| align | left, right, center | Align the button on the page |
|
||||
| expand | / | Expand to fit parent width |
|
||||
| click-parent | / | Make parent container also clickable |
|
||||
| tooltip | / | Add tooltip on hover |
|
||||
| shadow | / | Add shadow CSS |
|
||||
| class | / | Additional CSS classes |
|
||||
|
||||
|
||||
Finally here are some examples:
|
||||
|
||||
```{button-link} https://teachbooks.io
|
||||
:color: warning
|
||||
:shadow:
|
||||
|
||||
TeachBooks
|
||||
```
|
||||
|
||||
```
|
||||
```{button-link} https://teachbooks.io
|
||||
:color: warning
|
||||
:shadow:
|
||||
|
||||
TeachBooks
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
```{button-link} https://teachbooks.io
|
||||
:color: success
|
||||
:expand:
|
||||
|
||||
TeachBooks
|
||||
```
|
||||
|
||||
```
|
||||
```{button-link} https://teachbooks.io
|
||||
:color: success
|
||||
:expand:
|
||||
|
||||
TeachBooks
|
||||
```
|
||||
```
|
||||
|
||||
|
||||
## Icons
|
||||
|
||||
Icons can be included to visually represent actions or categories. They can take many shapes, such as an image or button inserted in-line within a text paragraph. Icons can be integrated using HTML syntax.
|
||||
|
||||
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 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 v1"></a> provides a range of features which are visually appealing and functional.
|
||||
```
|
||||
|
||||
**2. SVG Icons**
|
||||
|
||||
A library of SVG icons can be found in the [Bootstrap](https://icons.getbootstrap.com/#icons) library.
|
||||
|
||||
By scrolling through the available icons in the library you can find just about any icon. Once selected, you need to copy the SVG of the icon to include it in the `path` in the HTML code. This paragraph includes a globe: <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-globe" viewBox="0 0 16 16"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8m7.5-6.923c-.67.204-1.335.82-1.887 1.855A8 8 0 0 0 5.145 4H7.5zM4.09 4a9.3 9.3 0 0 1 .64-1.539 7 7 0 0 1 .597-.933A7.03 7.03 0 0 0 2.255 4zm-.582 3.5c.03-.877.138-1.718.312-2.5H1.674a7 7 0 0 0-.656 2.5zM4.847 5a12.5 12.5 0 0 0-.338 2.5H7.5V5zM8.5 5v2.5h2.99a12.5 12.5 0 0 0-.337-2.5zM4.51 8.5a12.5 12.5 0 0 0 .337 2.5H7.5V8.5zm3.99 0V11h2.653c.187-.765.306-1.608.338-2.5zM5.145 12q.208.58.468 1.068c.552 1.035 1.218 1.65 1.887 1.855V12zm.182 2.472a7 7 0 0 1-.597-.933A9.3 9.3 0 0 1 4.09 12H2.255a7 7 0 0 0 3.072 2.472M3.82 11a13.7 13.7 0 0 1-.312-2.5h-2.49c.062.89.291 1.733.656 2.5zm6.853 3.472A7 7 0 0 0 13.745 12H11.91a9.3 9.3 0 0 1-.64 1.539 7 7 0 0 1-.597.933M8.5 12v2.923c.67-.204 1.335-.82 1.887-1.855q.26-.487.468-1.068zm3.68-1h2.146c.365-.767.594-1.61.656-2.5h-2.49a13.7 13.7 0 0 1-.312 2.5m2.802-3.5a7 7 0 0 0-.656-2.5H12.18c.174.782.282 1.623.312 2.5zM11.27 2.461c.247.464.462.98.64 1.539h1.835a7 7 0 0 0-3.072-2.472c.218.284.418.598.597.933M10.855 4a8 8 0 0 0-.468-1.068C9.835 1.897 9.17 1.282 8.5 1.077V4z"/> . As you can see in the code cell below, you'll need to specify the width, height as well as fill colour.
|
||||
|
||||
```
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-globe" viewBox="0 0 16 16">
|
||||
<path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8m7.5-6.923c-.67.204-1.335.82-1.887 1.855A8 8 0 0 0 5.145 4H7.5zM4.09 4a9.3 9.3 0 0 1 .64-1.539 7 7 0 0 1 .597-.933A7.03 7.03 0 0 0 2.255 4zm-.582 3.5c.03-.877.138-1.718.312-2.5H1.674a7 7 0 0 0-.656 2.5zM4.847 5a12.5 12.5 0 0 0-.338 2.5H7.5V5zM8.5 5v2.5h2.99a12.5 12.5 0 0 0-.337-2.5zM4.51 8.5a12.5 12.5 0 0 0 .337 2.5H7.5V8.5zm3.99 0V11h2.653c.187-.765.306-1.608.338-2.5zM5.145 12q.208.58.468 1.068c.552 1.035 1.218 1.65 1.887 1.855V12zm.182 2.472a7 7 0 0 1-.597-.933A9.3 9.3 0 0 1 4.09 12H2.255a7 7 0 0 0 3.072 2.472M3.82 11a13.7 13.7 0 0 1-.312-2.5h-2.49c.062.89.291 1.733.656 2.5zm6.853 3.472A7 7 0 0 0 13.745 12H11.91a9.3 9.3 0 0 1-.64 1.539 7 7 0 0 1-.597.933M8.5 12v2.923c.67-.204 1.335-.82 1.887-1.855q.26-.487.468-1.068zm3.68-1h2.146c.365-.767.594-1.61.656-2.5h-2.49a13.7 13.7 0 0 1-.312 2.5m2.802-3.5a7 7 0 0 0-.656-2.5H12.18c.174.782.282 1.623.312 2.5zM11.27 2.461c.247.464.462.98.64 1.539h1.835a7 7 0 0 0-3.072-2.472c.218.284.418.598.597.933M10.855 4a8 8 0 0 0-.468-1.068C9.835 1.897 9.17 1.282 8.5 1.077V4z"/>
|
||||
</svg>
|
||||
```
|
||||
|
||||
If you want to keep your files clean, you won't like these svgs. However, your icons is probably available in one of the following icon providers.
|
||||
|
||||
**3. GitHub Octicon Icons**
|
||||
|
||||
[GitHub icons](https://primer.style/foundations/icons) like {octicon}`mark-github` can be added using the syntax:
|
||||
```{octicon}`mark-github` ```
|
||||
|
||||
Where `mark-github` can be replaced by any of the name of the icon provided [here](https://primer.style/foundations/icons)
|
||||
|
||||
By default the icon will be of height 1em (i.e. the height of the font).
|
||||
|
||||
**4. Material Design Icons**
|
||||
|
||||
The use of Material Design Icons like {material-regular}`settings` is explained [here](https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html#material-design-icons)
|
||||
|
||||
**5. FontAwesome Icons**
|
||||
|
||||
The use of FontAwesome Icons like {fas}`spinner` is explained [here](https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html#fontawesome-icons). There's no need to add the FontAwesome CSS.
|
||||
|
||||
**6. Combining Buttons and Icons**
|
||||
|
||||
Icons can also be included within buttons using the icon font for a modern, professional look. The code can also be downloaded in the [Bootstrap](https://icons.getbootstrap.com/#icons) library.
|
||||
|
||||
This button includes a download icon alongside some text: "Download it!".
|
||||
|
||||
Loving this book? <a href="https://jupyterbook.org" class="btn btn-primary">
|
||||
<i class="fas fa-download"></i> Download it!
|
||||
</a>
|
||||
|
||||
```
|
||||
Loving this book? <a href="https://jupyterbook.org" class="btn btn-primary">
|
||||
<i class="fas fa-download"></i> Download it!
|
||||
</a>
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# Banners and Announcements
|
||||
|
||||
A banner can be added to the top of a TeachBook:
|
||||
A banner can be added to the top of a Jupyter Book:
|
||||
|
||||
```{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 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:
|
||||
This is a commonly used feature, described in the [Jupyter Book manual here](https://jupyterbook.org/en/stable/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:
|
||||
|
||||
```
|
||||
sphinx:
|
||||
|
|
|
|||
|
|
@ -2,13 +2,13 @@
|
|||
|
||||
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 TeachBook.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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/en/stable/interactive/hiding.html?highlight=cell%20tag). Specifically, have a look at the sections on *hiding* cell inputs and *removing* cell inputs.
|
||||
|
||||
The workflow of editing cell tags depends on your editor. If you're using Jupyter Lab, you can find instructions [here](https://jupyterbook.org/v1/content/metadata.html#jupyter-cell-tags).
|
||||
The workflow of editing cell tags depends on your editor. If you're using Jupyter Lab, you can find instructions [here](https://jupyterbook.org/en/stable/content/metadata.html#jupyter-cell-tags).
|
||||
|
||||
For example, the following tag is used to convert the code input into either a drop-down (`hide-input`) or make it invisible (replace `hide-input` with `remove-input`). Replace `input` with `output` to do the same with the cell output:
|
||||
```
|
||||
|
|
|
|||
|
|
@ -29,11 +29,9 @@ $$ F = m \cdot a = 10 \cdot 9.81 = 98 \text{N}$$
|
|||
|
||||
To number the equations and refer in text, you need to provide a label to the equation. Just put the label between brackets and place it after the last \$\$, like this:
|
||||
|
||||
```md
|
||||
$$
|
||||
F = m \cdot a
|
||||
$$ (newtons_second_law)
|
||||
```
|
||||
$$
|
||||
F = m \cdot a
|
||||
$$ (newtons_second_law)
|
||||
|
||||
Resulting in:
|
||||
|
||||
|
|
@ -45,5 +43,5 @@ Equation {eq}`show_newtons_second_law` can now be referred to.
|
|||
|
||||
> **Note**
|
||||
>
|
||||
> 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).
|
||||
> 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).
|
||||
>
|
||||
|
|
@ -2,29 +2,29 @@
|
|||
|
||||
To add a figure, just copy the figure to the correct directory. Then, in your markdown file, include the figure as follows:
|
||||
|
||||
````md
|
||||
```{figure} <figurename>.png/.jpg
|
||||
---
|
||||
height/width: <height or width in pixels>
|
||||
name: <name of the figure>
|
||||
align: left / center / right
|
||||
figclass: left blank or "margin"
|
||||
---
|
||||
<Figure caption>
|
||||
```
|
||||
````
|
||||
```{figure} <figurename>.png/.jpg
|
||||
---
|
||||
height/width: <height or width in pixels>
|
||||
name: <name of the figure>
|
||||
align: left / center / right
|
||||
figclass: left blank or "margin"
|
||||
---
|
||||
<Figure caption>
|
||||
```
|
||||
````
|
||||
|
||||
For example:
|
||||
|
||||
````md
|
||||
```{figure} ../images/TUDelft_logo_rgb.png
|
||||
---
|
||||
width: 70%
|
||||
name: demoexample1
|
||||
align: center
|
||||
---
|
||||
example 1: width (70%) as percentage, align center
|
||||
```
|
||||
````
|
||||
```{figure} ../images/TUDelft_logo_rgb.png
|
||||
---
|
||||
width: 70%
|
||||
name: demoexample1
|
||||
align: center
|
||||
---
|
||||
example 1: width (70%) as percentage, align center
|
||||
```
|
||||
````
|
||||
|
||||
provides this output, which looks nice.
|
||||
|
|
@ -39,19 +39,19 @@ example 1: width (70%) as percentage, align center
|
|||
|
||||
Using the name label, you can refer to the figure as done with {numref}`Figure {number} <demoexample1>`.
|
||||
|
||||
You can find more documentation on including figures [here](https://jupyterbook.org/v1/content/figures.html).<br>
|
||||
You can find more documentation on including figures [here](https://jupyterbook.org/en/stable/content/figures.html).<br>
|
||||
|
||||
There are many settings, for instance aligning right:
|
||||
|
||||
````md
|
||||
```{figure} ../images/TUDelft_logo_rgb.png
|
||||
---
|
||||
width: 50%
|
||||
name: demoexample2
|
||||
align: right
|
||||
---
|
||||
example 2: width (50%) as percentage, align right
|
||||
```
|
||||
````
|
||||
```{figure} ../images/TUDelft_logo_rgb.png
|
||||
---
|
||||
width: 50%
|
||||
name: demoexample2
|
||||
align: right
|
||||
---
|
||||
example 2: width (50%) as percentage, align right
|
||||
```
|
||||
````
|
||||
|
||||
with the result:
|
||||
|
|
@ -67,22 +67,22 @@ example 2: width (50%) as percentage, align right
|
|||
|
||||
Aligning right can come with the potential downside (not always wanted) that text is wrapped around the figure. To avoid this one can use `<div>` elements, both before and after the text (make sure to leave an empty line after the `<div>`!):
|
||||
|
||||
````html
|
||||
<div style="clear: both;">
|
||||
and the output
|
||||
</div>
|
||||
<div style="clear: both;">
|
||||
````
|
||||
<div style="clear: both;">
|
||||
and the output
|
||||
</div>
|
||||
<div style="clear: both;">
|
||||
|
||||
```{figure} ../images/TUDelft_logo_rgb.png
|
||||
---
|
||||
width: 50%
|
||||
name: demoexample3
|
||||
align: right
|
||||
---
|
||||
example 3: width (50%) as percentage, align right with additional div style
|
||||
```
|
||||
```{figure} ../images/TUDelft_logo_rgb.png
|
||||
---
|
||||
width: 50%
|
||||
name: demoexample3
|
||||
align: right
|
||||
---
|
||||
example 3: width (50%) as percentage, align right with additional div style
|
||||
```
|
||||
|
||||
</div>
|
||||
</div>
|
||||
````
|
||||
|
||||
<div style="clear: both;">
|
||||
|
|
@ -108,16 +108,16 @@ including `figclass: margin` sets the figure to the column at the right.
|
|||
|
||||
</div>
|
||||
|
||||
````md
|
||||
```{figure} demo97/demo97_figure1.jpg
|
||||
---
|
||||
figclass: margin
|
||||
width: 50%
|
||||
name: demoexample2
|
||||
````
|
||||
```{figure} demo97/demo97_figure1.jpg
|
||||
---
|
||||
figclass: margin
|
||||
width: 50%
|
||||
name: demoexample2
|
||||
|
||||
---
|
||||
example 2:including figclass: margin
|
||||
```
|
||||
---
|
||||
example 2:including figclass: margin
|
||||
```
|
||||
````
|
||||
|
||||
<br>
|
||||
|
|
|
|||
|
|
@ -1,15 +1,6 @@
|
|||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 1-5.
|
||||
```
|
||||
|
||||
{bdg-warning}`Javascript overlay` {bdg-success}`Chrome Extension`
|
||||
````
|
||||
|
||||
# Making comments on the website: Hypothesis
|
||||
|
||||
Hypothesis is a third-party application that allows anyone to make publicly visible comments on a website (once you create a free account). This section explains how to use and install the extension. As this tool requires an account with a third-party, we advise to use our [local-annotator](../external/annotater/README.md) with similar capabilities but which store annotations locally. By default Hypothesis stores annotations publicly, which might confuse other students.
|
||||
Hypothesis is a third-party application that allows anyone to make publicly visible comments on a website (once you create a free account). This section explains how to use and install the extension.
|
||||
|
||||
```{admonition} Be careful of changing website URL's!
|
||||
:class: warning
|
||||
|
|
@ -29,9 +20,28 @@ html:
|
|||
```
|
||||
## Using Hypothesis
|
||||
|
||||
Once on a hypothesis version of this page, look at the top right corner: you will see three icons, an arrow, an eye and a note-pad. Clicking on the arrow will open the extension and allow you to view the annotations. Create an account and log in if you would like to reply or make your own annotations. You can also highlight text, but this is not publicly visible, it is only for your own reference.
|
||||
In this case it is easier to learn by doing! Hypothesis has been enabled for this book, but only in the _draft_ version.
|
||||
|
||||
Note that the annotations are only visible for the page that you are currently viewing. You can see all the Annotations on a website by opening the "Public" menu at the top of the dialog pane, selecting "Public" again in the drop-down, then "View group activity." Make sure you type in the URL to search (e.g., `teachbooks.io/manual`).
|
||||
````{admonition} How to View the Draft Site
|
||||
:class: tip, dropdown
|
||||
You can access the draft version by adding `draft/` at the end of the main book (but before the current page). For example:
|
||||
|
||||
```
|
||||
https://teachbooks.tudelft.nl/jupyter-book-manual/draft/basic-features/hypothesis.html
|
||||
```
|
||||
|
||||
You can find out more about the draft and publish feature on {ref}`this page <publish_students>`.
|
||||
````
|
||||
|
||||
Once on the draft version of this page, look at the top right corner: you will see three icons, an arrow, an eye and a note-pad. Clicking on the arrow will open the extension and allow you to view the annotations. Create an account and log in if you would like to reply or make your own annotations. You can also highlight text, but this is not publicly visible, it is only for your own reference.
|
||||
|
||||
Note that the annotations are only visible for the page that you are currently viewing. You can see all the Annotations on a website by opening the "Public" menu at the top of the dialog pane, selecting "Public" again in the drop-down, then "View group activity." Make sure you type in the URL to search (e.g., `teachbooks.tudelft.nl/jupyter-book-manual`).
|
||||
|
||||
```{admonition} Tips
|
||||
:class: tip
|
||||
|
||||
- use the {ref}`remove_from_publish` feature to enable Hypothesis in the draft book only
|
||||
```
|
||||
|
||||
## Student-controller with browser extension
|
||||
As an alternative to activating this for everyone, you can also advise your students to use the [hypothesis browser extension](https://web.hypothes.is/start/). In this way, students are not distracted by potential unnecessary public annotation and comments by fellow students and teachers.
|
||||
|
|
|
|||
|
|
@ -1,17 +1,18 @@
|
|||
# Anatomy of a TeachBook
|
||||
# Anatomy of a Jupyter Book
|
||||
|
||||
To build a TeachBook, you need three things:
|
||||
To build a Jupyter Book, you need three things:
|
||||
|
||||
1. A configuration file
|
||||
2. A table of contents
|
||||
3. Content
|
||||
|
||||
## The configuration file
|
||||
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:
|
||||
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:
|
||||
|
||||
```yaml
|
||||
title: TeachBook Manual
|
||||
author: TeachBooks development team
|
||||
title: Jupyter Book Manual
|
||||
author: Interactive Textbooks CiTG
|
||||
logo: images/TUDelft_logo_rgb.png
|
||||
copyright: CC BY-NC
|
||||
|
||||
execute:
|
||||
|
|
@ -22,7 +23,7 @@ sphinx:
|
|||
- sphinx_inline_tabs
|
||||
```
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
- `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.
|
||||
|
|
@ -31,7 +32,7 @@ Technically speaking, a `_config.yml` file is not required to build a TeachBook.
|
|||
|
||||
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 v1 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 documentation](https://jupyterbook.org/en/stable/content/execute.html#exclude-files-from-execution).
|
||||
|
||||
|
||||
```{warning}
|
||||
|
|
@ -115,9 +116,6 @@ parts:
|
|||
- file: section_1_2
|
||||
```
|
||||
|
||||
#### Exercise
|
||||
Check out [this exercise](https://teachbooks.io/template/syntax_exercises/007.html) in the TeachBooks template to see for yourself how to structure files with titles!
|
||||
|
||||
### Including a chapter twice
|
||||
In some cases you want to include the same chapter in two different places in your book (for instance parts). However, you do not want to make the same adjustments in different files, the content should only 'live' in one place. The solution is to use `include`:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,8 @@
|
|||
````{margin}
|
||||
# Basic Jupyter Book Features
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for [user type 3-5](../installation-and-setup/user_types.md).
|
||||
```
|
||||
````
|
||||
|
||||
# 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 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.
|
||||
These pages will provide a list of some common, basic book features which are all available in the original <a href="https://jupyterbook.org/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book"></a> package. However, this page includes also best-practices.
|
||||
|
|
|
|||
|
|
@ -1,24 +1,11 @@
|
|||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 3-5.
|
||||
```
|
||||
|
||||
{bdg-white}`GitHub app and Javascript script`
|
||||
````
|
||||
|
||||
# Discussions in your book: Utterances
|
||||
|
||||
[Utterances 🔮](https://utteranc.es/) is a lightweight open-source widget which allows you, your colleages and your students to discuss stuff in a blog post in your book. It is build on GitHub issues, so requires a GitHub repository, although the book can be hosted anywhere (so also on GitLab).
|
||||
|
||||
The [utterances website](https://utteranc.es/) clearly explains the required steps. Three things to take care of are:
|
||||
1. With the current setup of the [deploy book workflow on GitHub](../external/deploy-book-workflow/README.md), this widget only works on the primary branch.
|
||||
2. The baseurl is the root url of your book (the part of the url that doesn't change when opening different pages of the book). It needs to be defined in the `_config.yml` so that utteranc.es knows where to redirect users while interacting with the widget:
|
||||
```
|
||||
html:
|
||||
baseurl : "https://<user/organization>.github.io/<repo>" #Replace this with your own URL
|
||||
```
|
||||
3. It's advised to use `Issue title contains page pathname` as an option on utteranc.es, because that url is most stable.
|
||||
The [utterances website](https://utteranc.es/) clearly explains the required steps. One thing to take care of is how you want to do the issue-mapping with respect to multiple deployed versions (draft version, student version, archived versions):
|
||||
|
||||
- `Issue title contains page pathname`/`Issue title contains page URL` is useful if you want to isolate the comments on each of the branches.
|
||||
- `Issue title contains page title` is useful if you want to show the all comments on all different branches.
|
||||
|
||||
The given script can be added anywhere in your book, just copy the html-script into your `.md`-file or a markdown cell in your `.ipynb`-file. The blogpost is not visible when you do a local build of the book, build it online or use a local python server as shown in {ref}`setup-local-server`.
|
||||
|
||||
|
|
@ -30,7 +17,7 @@ Below you see an example of this feature!
|
|||
|
||||
## Example discussion
|
||||
<script src="https://utteranc.es/client.js"
|
||||
repo="TeachBooks/manual"
|
||||
repo="TeachBooks/utterances_manual"
|
||||
issue-term="pathname"
|
||||
theme="github-light"
|
||||
crossorigin="anonymous"
|
||||
|
|
|
|||
|
|
@ -13,9 +13,9 @@ kernelspec:
|
|||
|
||||
# Videos
|
||||
|
||||
Videos uploaded to YouTube can be embedded in the TeachBook. There are several ways to do so:
|
||||
Videos uploaded to YouTube can be embedded in the Jupyter Book. There are several ways to do so:
|
||||
|
||||
**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
|
||||
**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
|
||||
|
||||
```
|
||||
<iframe
|
||||
|
|
@ -28,21 +28,46 @@ Videos uploaded to YouTube can be embedded in the TeachBook. There are several w
|
|||
></iframe>
|
||||
```
|
||||
|
||||
The src can be used in combination with [](../external/sphinx-iframes/README.md):
|
||||
This HTML-iframe code can be directly included in the markdown file (no need to create a code-cell).
|
||||
|
||||
````
|
||||
```{video} https://www.youtube.com/embed/UCb-b82tzLo?
|
||||
Resulting in the video below:<br>
|
||||
<iframe
|
||||
width="560"
|
||||
height="315"
|
||||
src="https://www.youtube.com/embed/UCb-b82tzLo?"
|
||||
align="center"
|
||||
frameborder="0"
|
||||
allowfullscreen
|
||||
></iframe>
|
||||
|
||||
**2.** The above solution can be 'upgraded', setting a scaling of the video with the width of the screen and align it to the center:
|
||||
```
|
||||
````
|
||||
|
||||
Or the HTML-iframe code can be directly included in the markdown file.
|
||||
|
||||
Resulting in the video below:
|
||||
|
||||
```{video} https://www.youtube.com/embed/UCb-b82tzLo?
|
||||
<div style="display: flex; justify-content: center;">
|
||||
<div style="position: relative; width: 70%; height: 0; padding-bottom: 56.25%;">
|
||||
<iframe
|
||||
src="https://www.youtube.com/embed/YDBr1Lof_mI?si=RhTC31XHv-6gL4Kl"
|
||||
style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
|
||||
frameborder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowfullscreen
|
||||
></iframe>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
With the resulting output:
|
||||
<div style="display: flex; justify-content: center;">
|
||||
<div style="position: relative; width: 70%; height: 0; padding-bottom: 56.25%;">
|
||||
<iframe
|
||||
src="https://www.youtube.com/embed/YDBr1Lof_mI?si=RhTC31XHv-6gL4Kl"
|
||||
style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
|
||||
frameborder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowfullscreen
|
||||
></iframe>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
**2.** Another option is to use a python coding cell. As this code cell should be run when the book is made, you have to change the config file and set `execute_notebooks:` to force. This comes with the downside that it takes considerable more time to deploy the book.
|
||||
**3.** Another option is to use a python coding cell. As this code cell should be run when the book is made, you have to change the config file and set `execute_notebooks:` to force. This comes with the downside that it takes considerable more time to deploy the book.
|
||||
````
|
||||
```{code-cell} ipython3
|
||||
:tags: [remove-input]
|
||||
|
|
|
|||
|
|
@ -1,7 +0,0 @@
|
|||
# Changelog
|
||||
|
||||
## [v1.1.0](https://github.com/TeachBooks/manual/releases/tag/v1.1.0)
|
||||
Various updates with new and updates tooling, exercises and documentation. The full changelog is available here: https://github.com/TeachBooks/manual/releases/tag/v1.1.0
|
||||
|
||||
## [v1.0.0](https://github.com/TeachBooks/manual/releases/tag/V1.0.0)
|
||||
First release
|
||||
|
|
@ -1,15 +0,0 @@
|
|||
# Contact
|
||||
|
||||
## Contact
|
||||
If you encounter any issues report it by clicking {octicon}`mark-github` on the top right corner of this page.
|
||||
|
||||
If you have questions, contact the editors at info@teachbooks.io.
|
||||
|
||||
## 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 pull request.
|
||||
|
||||
The released book can be found on on https://teachbooks.io/manual. This page shows the built book of the `release` branch. All branches will also be visible online, as pointed to in the actions summaries: https://github.com/TeachBooks/mirror_teachbook_manual/actions
|
||||
|
||||
Some parts of this book are taken from other sources in the form of submodules (linked in the folder [book/external](https://github.com/TeachBooks/manual/tree/release/book/external)). To contribute to those pages, contribute to the source repository directly with a fork and merge/pull request. If you intent to clone this book including its submodules, clone using: `git clone --recurse-submodules git@github.com:TeachBooks/manual.git`
|
||||
|
||||
|
||||
|
|
@ -1,70 +0,0 @@
|
|||
(credits)=
|
||||
# Credits and License
|
||||
|
||||
You can refer to this book in its entirety as:
|
||||
|
||||
> TeachBooks Development Team (2024), _TeachBooks Manual_. https://github.com/TeachBooks/manual. Retreived [Month, Year]. CC BY 4.0.
|
||||
|
||||
This book is registered on Zenodo too: [](https://doi.org/10.5281/zenodo.15100848)
|
||||
|
||||
The introduction, structure and decisions on content is done under direction of the TeachBooks Development Team. The content is written by many contributors, of which there are many.
|
||||
|
||||
We anticipate that the content of this book will change continuously. Therefore, if you'd like to refer to a specific chapter, we recommend using the source code directly with the citation that refers to the GitHub repository and lists the date and name of the file. Although content will be added over time, chapter titles and URL's in this book are expected to remain relatively static. You can refer to individual chapters or pages within this book as:
|
||||
|
||||
> `<Title of Chapter or Page>`. In _TeachBooks Manual_. https://github.com/TeachBooks/manual (chapter `./book/intro/`, retrieved [`<date>`]).
|
||||
|
||||
Better yet, include a link to the specific commit! _If you know what this means, we assume you know how to do it._
|
||||
|
||||
## Acknowledgements
|
||||
|
||||
This book has many contributors, many of whom are also key members of the TeachBooks Team:
|
||||
|
||||
- Tom van Woudenberg
|
||||
- Robert Lanzafame
|
||||
- Freek Pols
|
||||
- Dennis den Ouden-van der Horst
|
||||
- Julie Kirsch
|
||||
- Caspar Jungbacker
|
||||
|
||||
All from Delft University of Technology.
|
||||
|
||||
This doesn't include small contributions from various people from within and outside Delft University of Technology.
|
||||
|
||||
A better way to see the contributions is to check the [Contributors Page](https://github.com/TeachBooks/manual/graphs/contributors) of the GitHub repository.
|
||||
|
||||
A big "thank you" is also due to the various colleagues and teaching assistants that have worked as part of the [TeachBooks](https://teachbooks.io/) Team for developing tools and providing support to improve this book, as well as the faculty of Civil Engineering and Geosciences and the Library at Delft University of Technology for significant financial support. The faculties of of Applied Sciences and Electrical Engineering, Mathematics and Computer Science have also provided support in the form of contributions from employees and student assistants..
|
||||
|
||||
## License
|
||||
This manual is [CC BY 4.0 licensed](https://creativecommons.org/licenses/by/4.0/) allowing you to share and adapt the material, as long as the source is named. External resources that are reused in this manual are listed below.
|
||||
|
||||
(external_resources)=
|
||||
### External resources
|
||||
|
||||
Parts of this book are taken from other external resources and reused in various ways. If an author is not listed on a particular page, it is by the Authors, except as follows:
|
||||
|
||||
The following pages are included directly from an external resource and is not edited by the TeachBooks Team:
|
||||
|
||||
- page [](./external/annotater/README.md). Original content licensed under BSD 3-Clause license.
|
||||
- Page [](./external/deploy-book-workflow/README.md). Original content licensed under BSD 3-Clause license.
|
||||
- Page [](./external/Download-Link-Replacer/README.md). Original content licensed under BSD 3-Clause license.
|
||||
- Page [](./external/JupyterBook-Patches/README.md). Original content licensed under BSD 3-Clause license.
|
||||
- Page [](./external/Nested-Books/README.md). Original content licensed under CC BY 4.0 license.
|
||||
- Page [](./external/Sphinx-Grasple-public/README.md). Original content licensed under MIT license.
|
||||
- Page [](./external/Sphinx-Image-Inverter/README.md). Original content licensed under BSD 3-Clause license.
|
||||
- Page [](./external/Sphinx-launch-buttons/README.md). Original content licensed under BSD 3-Clause license.
|
||||
- Page [](./external/Sphinx-TUDelft-theme/README.md). Original content licensed under MIT license.
|
||||
- Page [](./external/teachbooks-sphinx-tippy/README.md). Original content licensed under MIT license.
|
||||
- Page [](./external/template/README.md). Original content licensed under CC BY 4.0 license.
|
||||
- Page [](./external/Sphinx-Named-Colors/README.md). Original content licensed under MIT license.
|
||||
- Page [](indexed_defintions). Original content licensed under MIT license.
|
||||
- Page [](interactive_graph_content). Original content licensed under MIT license.
|
||||
- Pages [](./external/Useful_python_code/extensionfildownloadreturn.ipynb), [](./external/Useful_python_code/figshrinker.ipynb) and [](./external/Useful_python_code/snippit.ipynb). Original content licensed under BSD 3-Clause license.
|
||||
|
||||
The following pages contain content written by others, part of has been reused and/or modified by the TeachBooks Team:
|
||||
- Pages {ref}`copyright` and {ref}`copyright_considerations` include text from {cite:t}`tud_cip_24` that is used in the copyright checklist items. Original content licensed under CC BY.
|
||||
- Page {ref}`copyright_licenses`: {numref}`Figure %s<fig_license_types>` is included unmodified, along with paraphrased and quoted text (including hyperlinks) from {cite:t}`hall21`. Work is licensed under CC BY.
|
||||
- Page {ref}`copyright_licenses`: {numref}`Figure %s<fig_license_compatibility>` is included unmodified. Work is provided by Kennisland under a CC0 license. Accessed at [](https://wiki.creativecommons.org/wiki/File:CC_License_Compatibility_Chart.png) on December 17, 2024.
|
||||
- page [](./features/versioning.md): includes text from {cite:t}`semver` that has been modified. Original content licensed under CC BY 3.0.
|
||||
- page [](./features/external_toc.md): includes text from {cite:t}`teachbooks_package` that has been modified. Original content licensed under MIT.
|
||||
- Page [](./features/exercise.md): includes text from {cite:t}`sphinx-exercise` that has been modified. Original content licensed under MIT license.
|
||||
- Page [](./features/sphinx-proof.md): includes text from {cite:t}`sphinx-proof` that has been modified. Original content licensed under MIT license.
|
||||
|
|
@ -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 TeachBook 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 Jupyter Book 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 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.
|
||||
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.
|
||||
|
||||
## Tagged content
|
||||
|
||||
|
|
|
|||
|
|
@ -6,12 +6,12 @@
|
|||
"tags": []
|
||||
},
|
||||
"source": [
|
||||
"# Programming assignment with checks\n",
|
||||
"# Programming assignment\n",
|
||||
"\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",
|
||||
"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",
|
||||
"\n",
|
||||
"```{Note}\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",
|
||||
"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",
|
||||
"```\n",
|
||||
"\n",
|
||||
"```{custom_download_link} ./example_gumbel_stripped.ipynb\n",
|
||||
|
|
|
|||
|
|
@ -1,4 +1,14 @@
|
|||
# Examples of H5p Quizzes
|
||||
# Types of H5p Quizzes
|
||||
|
||||
This page will show some examples of H5p quizzes built into a variety of TeachBooks to allow the students to test their understanding of the content as they read. H5p quizzes can be used to create a set of Multiple Choice, Drag and Drop, Fill in the blanks, True/False and Image choice questions so the applications are quite versitile and your imagination can be used in creating the questions.
|
||||
|
||||
## Getting started with H5p
|
||||
|
||||
Some best-practices on the use of H5p:
|
||||
- To startup your H5p-account, first login to H5p via Brightspace. You can follow instructions as under [https://www.tudelft.nl/teaching-support/educational-tools/h5p](https://www.tudelft.nl/teaching-support/educational-tools/h5p).
|
||||
- After that, direct login is possible via [tudelft.h5p.com](https://tudelft.h5p.com)
|
||||
- Place your H5p-elements in a shared folder in H5p.
|
||||
- Disable the display options "Toolbar Below Content" and "Display author's name to public (anonymous users) (only relevant when content's status is set to Public )" for each
|
||||
|
||||
## Dialog cards
|
||||
|
||||
|
|
@ -6,7 +16,7 @@ Dialog cards can be used to ask open questions about the content students are re
|
|||
|
||||
**Engineering Systems Optimization**
|
||||
|
||||
A great example of this can be found in the book: Engineering Systems Optimization. [Chapter 4](https://teachbooks.io/engineering-systems-optimization/2023/pages/moo_example.html) called Mulit-objective optimization has an in depth sub-chapter which is used to compare the relation between engine power and emissions and how to optimize for both.
|
||||
A great example of this can be found in the book: Engineering Systems Optimization. [Chapter 4](https://teachbooks.github.io/engineering-systems-optimization/2023/pages/moo_example.html) called Mulit-objective optimization has an in depth sub-chapter which is used to compare the relation between engine power and emissions and how to optimize for both.
|
||||
|
||||
```{figure} figures/Live_code.PNG
|
||||
---
|
||||
|
|
@ -18,19 +28,27 @@ Problem Statement
|
|||
|
||||
As can be seen on the right-hand-side menu, the sub-chapter includes the problem statement, the elaboration on the model and solution method and finally an exercise for the student. The code in the page is activated by pressing the live code button which will make the code cells editable and executable. Additionally, interactive figures are included into the text with movable sliders to directly see the effect of the changes made.
|
||||
|
||||
```{iframe} ../_static/power.html
|
||||
:height: 580px
|
||||
:width: 100%
|
||||
```{figure} figures/Live_code2.PNG
|
||||
---
|
||||
width: 600
|
||||
align: center
|
||||
---
|
||||
Interactive Graph
|
||||
```
|
||||
|
||||
The H5p quizzes can shine in the section on questions, discussions and comments. Next to many multiple choice questions (which are discussed later) there are dialog cards which can ask more conceptual and open ended questions. Pressing on the blue button `Turn` will flip around the card and reveal the model answer. The great thing about the integration of both interactive aspects (coding and questions) helps the student to play around with the code and understand the topic from a less theoretical point-of-view.
|
||||
|
||||
```{h5p} https://tudelft.h5p.com/content/1292260184374358717/embed
|
||||
```{figure} figures/cards1.PNG
|
||||
---
|
||||
width: 700
|
||||
align: center
|
||||
---
|
||||
Dialoge Card
|
||||
```
|
||||
|
||||
```{h5p} https://tudelft.h5p.com/content/1292260188487459217/embed
|
||||
```
|
||||
**Try it out!**
|
||||
|
||||
<iframe src="https://tudelft.h5p.com/content/1292050206829217497/embed" aria-label="PA1 File Contents" width="1088" height="637" 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>
|
||||
|
||||
## Question Set
|
||||
|
||||
|
|
@ -40,10 +58,20 @@ Question sets consist of a question and one or more possible answers to that que
|
|||
|
||||
The following question sets are taken from chapter 3.3. Weighted least-squares estimation of the MUDE 23/24 book. The chapter builds on the previous chapter on simple least-squares estimation and dwelves into the importance and properties of the weight matrix. The student is primarily quizzed using multiple choice questions to check their understanding. The answers can be provided in the shape of text, figures, equations, matrices and probably much more.
|
||||
|
||||
```{h5p} https://tudelft.h5p.com/content/1292060781042105617/embed
|
||||
```{figure} figures/Question_set_1.PNG
|
||||
---
|
||||
width: 600
|
||||
align: center
|
||||
---
|
||||
Text Answers
|
||||
```
|
||||
|
||||
```{h5p} https://tudelft.h5p.com/content/1292046737060674407/embed
|
||||
```{figure} figures/Question_set_2.PNG
|
||||
---
|
||||
width: 600
|
||||
align: center
|
||||
---
|
||||
Equations Answers
|
||||
```
|
||||
|
||||
Since these questions are meant to develop the understanding of the students, feedback is vital! Feedback can be built into the questions to explain the reasoning behind a correct answer.
|
||||
|
|
@ -68,8 +96,7 @@ Tips
|
|||
|
||||
Have a look at the following 7 questions.
|
||||
|
||||
```{h5p} https://tudelft.h5p.com/content/1292062157562749767/embed
|
||||
```
|
||||
<iframe src="https://tudelft.h5p.com/content/1292062157562749767/embed" aria-label="quiz_uniform_motion" width="1088" height="637" 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>
|
||||
|
||||
## Complex fill in the blanks
|
||||
|
||||
|
|
@ -79,7 +106,12 @@ The complex fill in the blanks can be used to evaluate numerical answers.
|
|||
|
||||
Chapter 3.7. Non-linear least-squares estimation from the MUDE 23/24 book makes use of the complex fill in the blanks quiz in order to check that the students understood the composition of the Jacobian Matrix specifically used in deriving the linearized functional model. This model is essential for accurately estimating values and assessing system behavior of complex processes that arent linear.
|
||||
|
||||
```{h5p} https://tudelft.h5p.com/content/1292064774866067777/embed
|
||||
```{figure} figures/blanks1.PNG
|
||||
---
|
||||
width: 600
|
||||
align: center
|
||||
---
|
||||
Answer Boxes
|
||||
```
|
||||
As you can see, the precision of the answer sought for is specified and the figure below shows again the incorporation of feedback.
|
||||
|
||||
|
|
@ -93,24 +125,18 @@ Wrong Answer + Feedback
|
|||
|
||||
**MUDE - Optimization**
|
||||
|
||||
Since the cells can be used to evaluate numerical answers, they are an easy way to quiz the student on matrices and evaluate the result of each position independently. The optimization team of MUDE took this a step further and used this set-up to quiz the students on the SIMPLEX method. This method automates the solving of the augmented form of a linear programming problem with continuous variables. It makes use of tables and the manipulation of equations to find the optimal values. Unfortunately, with a large number of variables this tables tend to get quite big and filling in the cells becomes laborious.
|
||||
Since the cells can be used to evaluate numerical answers, they are an easy way to quiz the student on matrices and evaluate the result of each position indidependently. The optimization team of MUDE took this a step further and used this set-up to quiz the students on the SIMPLEX method. This method automates the solving of the augmented form of a linear programing problem with continuous variables. It makes use of tables and the manipulation of equations to find the optimal vaues. Unfortunately, with a large number of variables this tables tend to get quite big and filling in the cells becomes laborous.
|
||||
|
||||
```{h5p} https://tudelft.h5p.com/content/1292131432784432037/embed
|
||||
```{figure} figures/blanks3.PNG
|
||||
---
|
||||
width: 600
|
||||
align: center
|
||||
---
|
||||
SIMPLEX Method
|
||||
```
|
||||
**Truss structure**
|
||||
**Try it out!**
|
||||
|
||||
Truss structures are modelled as rigid bars (so elements which cannot deform) connected by hinges (so elements can rotate with respect to one each other). In our model, hinges are indicate with a circle, and bars with a line. For example, the structure you've seen in the second example (with two diagonal bars removed) is modelled as follows:
|
||||
|
||||
```{figure} ../images/Truss1.svg
|
||||
:name: truss structure
|
||||
|
||||
Bars and hinges in truss structure
|
||||
```
|
||||
|
||||
Now that you've been introduced to truss structures, answer the following question:
|
||||
|
||||
```{h5p} https://tudelft.h5p.com/content/1291910926067816717/embed
|
||||
```
|
||||
<iframe src="https://tudelft.h5p.com/content/1292010272694757307/embed" aria-label="Example MUDE" width="1088" height="637" 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>
|
||||
|
||||
## True or False
|
||||
|
||||
|
|
@ -128,15 +154,18 @@ align: center
|
|||
Problem Statement
|
||||
```
|
||||
|
||||
The small circles below the question indicates that there are more questions in this series which can be viewed by clicking on the blue arrow pointing towards the left or right. Open the second, fourth and fifth question:
|
||||
|
||||
```{h5p} https://tudelft.h5p.com/content/1292120485436114287/embed
|
||||
```{figure} figures/truefalse1.PNG
|
||||
---
|
||||
width: 600
|
||||
align: center
|
||||
---
|
||||
True or False
|
||||
```
|
||||
The small circles below the question indicates that there are more questions in this series which can be viewed by clicking on the blue arrow pointing towards the left or right.
|
||||
|
||||
**Try it out!**
|
||||
|
||||
```{h5p} https://tudelft.h5p.com/content/1292061623388939257/embed
|
||||
```
|
||||
<iframe src="https://tudelft.h5p.com/content/1292061623388939257/embed" aria-label="quiz_blue_vs_LS" width="1088" height="637" 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>
|
||||
|
||||
## Drag and Drop
|
||||
|
||||
|
|
@ -144,15 +173,16 @@ Drag and Drop questions are useful to make the distinction between different con
|
|||
|
||||
**MUDE - Optimization**
|
||||
|
||||
In this chapter, it was important that the students made the distinction between the terminology and mathematical meaning between different elements of the graphical solution method. A drag and drop question was used to link the term to its definition. The answer boxes can be dragged to the correct title in a playful manner.
|
||||
In this chapter, it was important that the students made the distinction between the terminology and mathematical meaning between different elements of the graphical solution method. A drag and drop question was used to link the term to its definition. The answer boxes can be dragged to the correct title in a playful manner.jup
|
||||
|
||||
The fourth question in this question set is a drag and drop question:
|
||||
|
||||
```{h5p} https://tudelft.h5p.com/content/1292121213033110307/embed
|
||||
```{figure} figures/drag1.PNG
|
||||
---
|
||||
width: 600
|
||||
align: center
|
||||
---
|
||||
Drag and Drop
|
||||
```
|
||||
|
||||
The correct answer leads to:
|
||||
|
||||
```{figure} figures/drag2.PNG
|
||||
---
|
||||
width: 600
|
||||
|
|
|
|||
|
|
@ -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 TeachBook format with live coding.
|
||||
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.
|
||||
|
||||
```{Note}
|
||||
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.
|
||||
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.
|
||||
```
|
||||
|
||||
2. [Combining theory with interactive questions and extensive coding assignments](example_quiz_interactive.ipynb)
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ This page will show some examples where live coding is used in combination with
|
|||
|
||||
## Python for Engineers
|
||||
|
||||
[Python for engineers](https://teachbooks.io/learn-python/intro.html) is a book used to introduce basic programming concepts to students coming from different universities where programming is not a big part of the curriculum like at TU Delft. The students are encouraged to follow the course online before the start of the year to hit the ground running in September. Chapter 7 introduces the students to [Matplotlib](https://teachbooks.io/learn-python/07/Theory/01.html) and teaches them various ways of making a graph.
|
||||
[Python for engineers](https://teachbooks.github.io/learn-python/intro.html) is a book used to introduce basic programming concepts to students coming from different universities where programming is not a big part of the curriculum like at TU Delft. The students are encouraged to follow the course online before the start of the year to hit the ground running in September. Chapter 7 introduces the students to [Matplotlib](https://teachbooks.github.io/learn-python/07/Theory/01.html) and teaches them various ways of making a graph.
|
||||
|
||||
Live coding is the perfect learning tool as the students can see how the code relates to the visual result of the graph. subsequently, they can adapt the code and observe the changes. Let's have a look at the implementation.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
# Overview
|
||||
# TeachBooks Examples
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -12,13 +12,11 @@ Truss structures are structures assembled of straight elements connected in node
|
|||
Examples of these structures are commonly found in rail bridges like the one below:
|
||||
|
||||
```{figure} theory_questions_images/pic0.jpg
|
||||
:class: dark-light
|
||||
:width: 400
|
||||
```
|
||||
Furthermore, these structures are commonly found in building as well, both invisible and visible:
|
||||
|
||||
```{figure} theory_questions_images/pic1.jpg
|
||||
:class: dark-light
|
||||
:width: 400
|
||||
```
|
||||
|
||||
|
|
|
|||
2
book/external/Download-Link-Replacer
vendored
2
book/external/Download-Link-Replacer
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 03feccf6efa55d14da78cf4259cedb8a7585ad91
|
||||
Subproject commit bb7884aaf0c0205b2c0b8a7bb676e929528b2e33
|
||||
2
book/external/JupyterBook-Patches
vendored
2
book/external/JupyterBook-Patches
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 99aeda40ae0cfa06eb290ba5c3a6b9b81eb3992d
|
||||
Subproject commit a476ff813e481dcab65d02cb869266cb6a704451
|
||||
2
book/external/Nested-Books
vendored
2
book/external/Nested-Books
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit c365e770730fb5abb3426b06062e69a3a325b336
|
||||
Subproject commit 60370834c33ea9b7754d685ecb5bc2d3a8a0ebc1
|
||||
1
book/external/Sphinx-Grasple-public
vendored
1
book/external/Sphinx-Grasple-public
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit 0dc28b45ef6184e67b8219bd4494c6f54ad8ccd0
|
||||
2
book/external/Sphinx-Image-Inverter
vendored
2
book/external/Sphinx-Image-Inverter
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit ca1280ccadfc17f611b6f411dddb77329710dd85
|
||||
Subproject commit 7db6dbbed739366e1b60e4b6349db97b943ec540
|
||||
1
book/external/Sphinx-Named-Colors
vendored
1
book/external/Sphinx-Named-Colors
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit 1307f44c8d64fb98ce4649f585805666e90ec3aa
|
||||
1
book/external/Sphinx-PRIME-applets
vendored
1
book/external/Sphinx-PRIME-applets
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit cf8849136e1303e1a2fa2a8ed7296cde6b3b2d68
|
||||
1
book/external/Sphinx-TUDelft-theme
vendored
1
book/external/Sphinx-TUDelft-theme
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit 3815645c5cfef3ebbdc8070e649e4c7331b680e3
|
||||
1
book/external/Sphinx-launch-buttons
vendored
1
book/external/Sphinx-launch-buttons
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit 9e70fbca8fb7bacb3e6d9c58349f04d6245082dc
|
||||
1
book/external/TeachBooks
vendored
Submodule
1
book/external/TeachBooks
vendored
Submodule
|
|
@ -0,0 +1 @@
|
|||
Subproject commit 3f723638df29972b468a550740195ce0e61b8d29
|
||||
2
book/external/Useful_python_code
vendored
2
book/external/Useful_python_code
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit c80863d19f7fde7a452200baa4b4fafe12debc95
|
||||
Subproject commit a647c34fa7b50cb95ef0c1d34ad07599292336ad
|
||||
1
book/external/annotater
vendored
1
book/external/annotater
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit d1f41f93ffe87a305956de405dac47daaad3bc69
|
||||
2
book/external/deploy-book-workflow
vendored
2
book/external/deploy-book-workflow
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit da54eb463cd0bac2a3e78dcce7067b2a81a8c3d1
|
||||
Subproject commit 69f12482bf328a472b70d5f9c859729121ff0342
|
||||
1
book/external/latex-to-markdown-conversion
vendored
Submodule
1
book/external/latex-to-markdown-conversion
vendored
Submodule
|
|
@ -0,0 +1 @@
|
|||
Subproject commit f71092bfdb2e3d5d2f580bac5e31ff695806e7d3
|
||||
1
book/external/sphinx-iframes
vendored
1
book/external/sphinx-iframes
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit 2bc21b6174b8e7dbd15c862c219bd506e06f9d13
|
||||
1
book/external/teachbooks-sphinx-tippy
vendored
1
book/external/teachbooks-sphinx-tippy
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit 6122c67f86a7c9b95f349c80316571e277f0a66b
|
||||
2
book/external/template
vendored
2
book/external/template
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 1ab90c5092b69aa8e1421e598ff43433bd97a9d8
|
||||
Subproject commit 809352d4db017f40cdd78654adc3addc4c3eed86
|
||||
|
|
@ -1,32 +1,18 @@
|
|||
````{margin}
|
||||
# Interactive HTML/JavaScript elements
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 5.
|
||||
```
|
||||
|
||||
{bdg-danger}`iframe`
|
||||
````
|
||||
|
||||
# Interactive HTML/JavaScript elements
|
||||
|
||||
In this section, we will discuss how to [create](creating_basic_HTML_elements.md) and [embed](adding_HTML_elements.md) interactive HTML/Javascript elements created in HTML/JavaScript in a TeachBook. These HTML/Javascript element work very fluently and don't require a python kernel running in the background.
|
||||
|
||||
This could be for example interactive 3d figures:
|
||||
|
||||
```{iframe} ../_static/element_render_box.html
|
||||
:width: 600px
|
||||
:height: 400px
|
||||
```
|
||||
<iframe src="../_static/element_render_box.html" width="600" height="400" frameborder="0"></iframe>
|
||||
|
||||
Or other interactive graphs:
|
||||
|
||||
```{iframe} ../_static/element_pdf_and_cdf.html
|
||||
:width: 600px
|
||||
:height: 300px
|
||||
```
|
||||
<iframe src="../_static/element_pdf_and_cdf.html" width="600" height="300" frameborder="0"></iframe>
|
||||
|
||||
```{iframe} https://openla.ewi.tudelft.nl/applet/lines_and_planes/normal_equation_plane_origin?iframe=true
|
||||
:width: 600px
|
||||
:height: 500px
|
||||
```
|
||||
<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>
|
||||
|
|
@ -1,30 +1,14 @@
|
|||
````{margin}
|
||||
{bdg-danger}`iframe`
|
||||
````
|
||||
|
||||
# Adding interactive HTML/JavaScript elements
|
||||
|
||||
In this section, we will discuss how to embed interactive elements created in HTML/JavaScript in a TeachBook. If you are interested in learning how to create these elements yourself, we will discuss an example in the [next article](creating_basic_HTML_elements.md). As an example, let us discuss how to embed an interactive 3D model of a subsurface environment I created:
|
||||
|
||||
```{iframe} ../_static/element_render_box.html
|
||||
:width: 600px
|
||||
:height: 400px
|
||||
```
|
||||
<iframe src="../_static/element_render_box.html" width="600" height="400" frameborder="0"></iframe>
|
||||
|
||||
## Storing the HTML file
|
||||
TeachBooks like this one are built from a Git project, comprising of different files and folders that are assembled into a webpage. It is generally not possible to paste the code of your HTML element directly into one of the project's Markdown files. Instead, you will have to store the files separately somewhere in the folder structure, then embed them later on. For this project, the book's root folder contains a ´_static´ folder which we can use to store our HTML/JS file. Some elemenets - such as the one above - may require additional files. The HTML element above, for instance, specifies a renderer using [THREE.js](https://threejs.org/) that displays a digital model. This model is specified as an .obj file (which defines its geometry) and a .mtl file (which defines its materials - its colors, reflectivity, transparency, and so on). We can store these files in the same ´_static´ folder.
|
||||
|
||||
## Embedding HTML files via iframes
|
||||
If we want to embed our HTML/JS element in a Markdown page, we must use an inline frame, also known as an iframe. In a book, an iframe can be added using [](../external/sphinx-iframes/README.md):
|
||||
|
||||
````
|
||||
```{iframe} ../_static/element_render_box.html
|
||||
:width: 600px
|
||||
:height: 300px
|
||||
```
|
||||
````
|
||||
|
||||
or alternatively using raw HTML:
|
||||
If we want to embed our HTML/JS element in a Markdown page, we must use an inline frame, also known as an iframe. In code, an iframe looks like this:
|
||||
|
||||
```html
|
||||
<iframe src="../_static/element_render box.html" width="600" height="300" frameborder="0"></iframe>
|
||||
|
|
@ -46,7 +30,7 @@ Let's take a closer look at the source. Since this project uses a local file str
|
|||
- Finally, the string `"element_render_box.html"` selects the HTML file we want to embed. We are now in `book/_static/element_render_box.html`.
|
||||
|
||||
## Viewing result at local build
|
||||
To view the final result locally, it's required to setup a {ref}`local Python webserver <setup-local-server>`.
|
||||
To view the final result locally, it's required to setup a [local python webserver](setup-local-server).
|
||||
|
||||
## HTML code for the 3D render element
|
||||
|
||||
|
|
|
|||
|
|
@ -1,133 +0,0 @@
|
|||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 4 and 5.
|
||||
```
|
||||
|
||||
{bdg-primary}`Sphinx Extension`
|
||||
|
||||
````
|
||||
|
||||
(apa)=
|
||||
# APA References
|
||||
|
||||
## Introduction
|
||||
|
||||
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.
|
||||
|
||||
## Installation
|
||||
|
||||
To use APA-references, install the [Sphinx-APA-References extension](https://github.com/TeachBooks/Sphinx-APA-References) by following these two steps:
|
||||
|
||||
**Step 1: Install the Package**
|
||||
|
||||
Install the module `sphinx-apa-references` package using `pip`:
|
||||
```
|
||||
pip install sphinx-apa-references
|
||||
```
|
||||
|
||||
**Step 2: Add to `requirements.txt`**
|
||||
|
||||
Make sure that the package is included in your project's `requirements.txt` to track the dependency:
|
||||
```
|
||||
sphinx-apa-references
|
||||
```
|
||||
|
||||
**Step 3: Enable in `_config.yml`**
|
||||
|
||||
In your `_config.yml` file, add the extension to the list of Sphinx extra extensions (**important**: underscore, not dash this time) and specify the location of your bib file (note indentation of the bibtex file path specification; any number of bib files are allowed):
|
||||
```
|
||||
sphinx:
|
||||
extra_extensions:
|
||||
.
|
||||
.
|
||||
.
|
||||
- sphinx_apa_references
|
||||
.
|
||||
.
|
||||
.
|
||||
bibtex_bibfiles: "<path_to_bib_file>/references.bib"
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
All references are now made in APA-style. Here are five examples how to create a citation in APA style:
|
||||
|
||||
| Syntax | Result with 1 author | Result with many authors | Explanation |
|
||||
| :---: | :---: | :---: | :---: |
|
||||
|`{cite:t}` | {cite:t}`jason_moore` | {cite:t}`dummyreference` | Textual citation |
|
||||
|`{cite:p}`| {cite:p}`jason_moore` | {cite:p}`dummyreference` | Parenthetical citation |
|
||||
|`{cite}`| {cite}`jason_moore` | {cite}`dummyreference` | Same as `{cite:p}` |
|
||||
|`{cite:ts}` | {cite:ts}`jason_moore` | {cite:ts}`dummyreference` | Same as `{cite:t}`, but without abbreviation of authors |
|
||||
|`{cite:ps}`| {cite:ps}`jason_moore` | {cite:ps}`dummyreference` |Same as `{cite:p}`, but without abbreviation of authors |
|
||||
|
||||
For more options on the in-line citation style, see https://jupyterbook.org/v1/content/citations.html#change-the-in-line-citation-style.
|
||||
|
||||
The references section at the end of your book will also be formatted in APA style:
|
||||
|
||||
::::{admonition} Example of APA References
|
||||
:class: example
|
||||
|
||||
```{iframe} ../references.html
|
||||
:class: no-blend
|
||||
```
|
||||
::::
|
||||
|
||||
## Duplicate label warning
|
||||
|
||||
You might encounter a warning during the build process that has this structure:
|
||||
|
||||
```
|
||||
<filename>:<lineno>: WARNING: duplicate label "<authors>, <year>" for keys "<key1>" and "<key2>"
|
||||
```
|
||||
|
||||
This is might have different cause, but often it is because two different references have the same author(s) and the same year. A common solution is to add letters to the year in the `.bib` file, like this:
|
||||
|
||||
```bibtex
|
||||
@misc{launch_buttons,
|
||||
author = {{TeachBooks}},
|
||||
title = {Custom launch buttons},
|
||||
url = {https://github.com/TeachBooks/Sphinx-launch-buttons},
|
||||
year = {2024a},
|
||||
note = {Retrieved December, 2024. BSD-3-Clause.},
|
||||
}
|
||||
|
||||
@misc{nested,
|
||||
author = {{TeachBooks}},
|
||||
title = {Git workflow: Share content between book},
|
||||
url = {https://github.com/TeachBooks/Nested-Books},
|
||||
year = {2024b},
|
||||
note = {Retrieved December, 2024. CC BY 4.0.},
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
This does negate the automatic ordering of references by the order `authors > year > title`, so our advice is to only use this solution when the bibliography contains duplicate author-year combinations ánd the bibliography is final. That way the you can use the sorted order with warnings to determine the correct letters to add to the years.
|
||||
|
||||
## Implementation
|
||||
|
||||
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 v1 features, [as described here](https://jupyterbook.org/v1/content/citations.html#change-the-in-line-citation-style), this extension implements a complete APA style, as well as enforcing round brackets (like this).
|
||||
|
||||
### Previous implementation
|
||||
|
||||
APA referencing was previously implemented by including a local extension in a book subdirectory `_ext` (described [here](https://github.com/jupyter-book/jupyter-book/issues/1090)). To upgrade, once this Sphinx extension is implemented in your book, the local extension files in `_ext` can be deleted and the four lines indicated below removed from your `_config.yml` file:
|
||||
|
||||
```yaml
|
||||
sphinx:
|
||||
config:
|
||||
.
|
||||
.
|
||||
.
|
||||
bibtex_reference_style: author_year_round # remove
|
||||
bibtex_default_style: myapastyle # remove
|
||||
.
|
||||
.
|
||||
.
|
||||
local_extensions:
|
||||
apastyle: _ext/ # remove
|
||||
bracket_citation_style: _ext/ # remove
|
||||
```
|
||||
|
|
@ -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 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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,6 @@
|
|||
# Creating basic interactive HTML/JavaScript elements
|
||||
|
||||
```{iframe} ../_static/element_pdf_and_cdf.html
|
||||
:width: 600px
|
||||
:height: 300px
|
||||
```
|
||||
<iframe src="../_static/element_pdf_and_cdf.html" width="600" height="300" frameborder="0"></iframe>
|
||||
|
||||
At the bottom of this page, I will provide the full code for the interactive element above. In this section, let us go through the code one piece at a time. Let us begin from the top.
|
||||
|
||||
|
|
@ -53,7 +50,7 @@ The first few lines of our JavaScript code are simple. To scale our element with
|
|||
var width = vw;
|
||||
|
||||
// Create the canvas. We will use only part of it for the main plot
|
||||
var svg = d3.select("#click") // This selects the svg using its id
|
||||
var svg = d3.select("#click") // This selects the div
|
||||
.attr("width", width) // This defines the canvas' width
|
||||
.attr("height", height) // This defines the canvas' height
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,104 +0,0 @@
|
|||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 4 and 5.
|
||||
```
|
||||
{bdg-primary}`Sphinx Extension`
|
||||
|
||||
````
|
||||
|
||||
# Multilingual 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">
|
||||
<path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8m7.5-6.923c-.67.204-1.335.82-1.887 1.855A8 8 0 0 0 5.145 4H7.5zM4.09 4a9.3 9.3 0 0 1 .64-1.539 7 7 0 0 1 .597-.933A7.03 7.03 0 0 0 2.255 4zm-.582 3.5c.03-.877.138-1.718.312-2.5H1.674a7 7 0 0 0-.656 2.5zM4.847 5a12.5 12.5 0 0 0-.338 2.5H7.5V5zM8.5 5v2.5h2.99a12.5 12.5 0 0 0-.337-2.5zM4.51 8.5a12.5 12.5 0 0 0 .337 2.5H7.5V8.5zm3.99 0V11h2.653c.187-.765.306-1.608.338-2.5zM5.145 12q.208.58.468 1.068c.552 1.035 1.218 1.65 1.887 1.855V12zm.182 2.472a7 7 0 0 1-.597-.933A9.3 9.3 0 0 1 4.09 12H2.255a7 7 0 0 0 3.072 2.472M3.82 11a13.7 13.7 0 0 1-.312-2.5h-2.49c.062.89.291 1.733.656 2.5zm6.853 3.472A7 7 0 0 0 13.745 12H11.91a9.3 9.3 0 0 1-.64 1.539 7 7 0 0 1-.597.933M8.5 12v2.923c.67-.204 1.335-.82 1.887-1.855q.26-.487.468-1.068zm3.68-1h2.146c.365-.767.594-1.61.656-2.5h-2.49a13.7 13.7 0 0 1-.312 2.5m2.802-3.5a7 7 0 0 0-.656-2.5H12.18c.174.782.282 1.623.312 2.5zM11.27 2.461c.247.464.462.98.64 1.539h1.835a7 7 0 0 0-3.072-2.472c.218.284.418.598.597.933M10.855 4a8 8 0 0 0-.468-1.068C9.835 1.897 9.17 1.282 8.5 1.077V4z"/>
|
||||
</svg> " button, like you might be used to seeing on just about any website. The use of the button, however, is completey customizable and may be used in many different ways.
|
||||
|
||||
## Installation
|
||||
|
||||
1. Install the Sphinx Launch Buttons extension from the GitHub repository. Paste the following line, in your terminal. Make sure you activated your book building environment.
|
||||
|
||||
```
|
||||
pip install git+https://github.com/TeachBooks/Sphinx-launch-buttons.git
|
||||
```
|
||||
|
||||
2. To use the extension in your book, you need to include it in your `_config.yml` file.
|
||||
|
||||
```
|
||||
sphinx:
|
||||
extra_extensions:
|
||||
- custom-launch-buttons
|
||||
```
|
||||
|
||||
3. Then you need to include a `_launch_buttons.yml` file in the same location as your `_config.yml` file. The following code cell shows the main structure of that file.
|
||||
|
||||
```
|
||||
buttons:
|
||||
- type : dropdown
|
||||
|
||||
- type : button
|
||||
```
|
||||
|
||||
Here, `buttons` is an array of launch buttons, each can be identified using 2 types: 'dropdown' or 'button'. The cell above shows 2 buttons, one of type `dropdown` and one of type `button`.
|
||||
|
||||
The button/dropdown can be visualised using either an [svg icon](https://icons.getbootstrap.com/#icons) or text.
|
||||
|
||||
```
|
||||
buttons:
|
||||
- type : dropdown
|
||||
label: Language
|
||||
- type : button
|
||||
icon : <svg> ...
|
||||
</svg>
|
||||
```
|
||||
4. Lastly you need to specifiy the items of your button. So assuming you want to have different language versions, each item will be one of the languages.
|
||||
|
||||
```
|
||||
buttons:
|
||||
- type : dropdown
|
||||
label: Language
|
||||
|
||||
- type : button
|
||||
icon : <svg> ...
|
||||
</svg>
|
||||
items:
|
||||
- label: English
|
||||
url: url of branch
|
||||
- label: Nederlands
|
||||
url: url of branch
|
||||
```
|
||||
As you can see in the `items:` line, each dropdown option links to the branch of the repository in the respective language.
|
||||
|
||||
## Setting up your repository
|
||||
|
||||
For the implementation to your book, it is handy to create a branch for each language version you want to offer. Make a new branch using for example main as a source. Assuming we want to create a dutch version of you can call this branch `Dutch` or `Nederlands`.
|
||||
|
||||
You will then need to translate the content in the dutch branch to dutch which can take some time. From experience, [DeepL](https://www.deepl.com/en/translator) is a good tool for this but any AI chatbot might be helpful as well. Make sure to proofread the translation.
|
||||
|
||||
You'll need to add (merge) the updated `_config.yml` and the new `_launch_buttons.yml` to all of your branches.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
buttons:
|
||||
- type: dropdown
|
||||
icon: <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-globe" viewBox="0 0 16 16">
|
||||
<path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8m7.5-6.923c-.67.204-1.335.82-1.887 1.855A8 8 0 0 0 5.145 4H7.5zM4.09 4a9.3 9.3 0 0 1 .64-1.539 7 7 0 0 1 .597-.933A7.03 7.03 0 0 0 2.255 4zm-.582 3.5c.03-.877.138-1.718.312-2.5H1.674a7 7 0 0 0-.656 2.5zM4.847 5a12.5 12.5 0 0 0-.338 2.5H7.5V5zM8.5 5v2.5h2.99a12.5 12.5 0 0 0-.337-2.5zM4.51 8.5a12.5 12.5 0 0 0 .337 2.5H7.5V8.5zm3.99 0V11h2.653c.187-.765.306-1.608.338-2.5zM5.145 12q.208.58.468 1.068c.552 1.035 1.218 1.65 1.887 1.855V12zm.182 2.472a7 7 0 0 1-.597-.933A9.3 9.3 0 0 1 4.09 12H2.255a7 7 0 0 0 3.072 2.472M3.82 11a13.7 13.7 0 0 1-.312-2.5h-2.49c.062.89.291 1.733.656 2.5zm6.853 3.472A7 7 0 0 0 13.745 12H11.91a9.3 9.3 0 0 1-.64 1.539 7 7 0 0 1-.597.933M8.5 12v2.923c.67-.204 1.335-.82 1.887-1.855q.26-.487.468-1.068zm3.68-1h2.146c.365-.767.594-1.61.656-2.5h-2.49a13.7 13.7 0 0 1-.312 2.5m2.802-3.5a7 7 0 0 0-.656-2.5H12.18c.174.782.282 1.623.312 2.5zM11.27 2.461c.247.464.462.98.64 1.539h1.835a7 7 0 0 0-3.072-2.472c.218.284.418.598.597.933M10.855 4a8 8 0 0 0-.468-1.068C9.835 1.897 9.17 1.282 8.5 1.077V4z"/>
|
||||
</svg>
|
||||
items:
|
||||
- label: English
|
||||
url: https://teachbooks.github.io/files-and-folders/EN
|
||||
- label: Nederlands
|
||||
url: https://teachbooks.github.io/files-and-folders/NL
|
||||
```
|
||||
|
||||
The code in the above cell is the `_launch_buttons.yml` file of a repository called "files-and-folders". The buttons created look like this:
|
||||
|
||||
```{figure} figures/language_button.PNG
|
||||
---
|
||||
width: 50%
|
||||
name: language_button
|
||||
---
|
||||
Custom Button
|
||||
```
|
||||
|
|
@ -1,22 +0,0 @@
|
|||
import os
|
||||
import json
|
||||
|
||||
def list_file_types(directory):
|
||||
file_types = set()
|
||||
for root, _, files in os.walk(directory):
|
||||
for file in files:
|
||||
_, ext = os.path.splitext(file)
|
||||
if ext: # Only include files with extensions
|
||||
file_types.add(ext)
|
||||
return sorted(file_types)
|
||||
|
||||
def format_file_types(file_types):
|
||||
formatted = [f"**/*{ext}" for ext in file_types]
|
||||
return formatted
|
||||
|
||||
if __name__ == "__main__":
|
||||
book_directory = r"c:\Users\tomvanwoudenbe\Git\book\book"
|
||||
file_types = list_file_types(book_directory)
|
||||
formatted_file_types = format_file_types(file_types)
|
||||
print("File types in the directory (formatted):")
|
||||
print(json.dumps(formatted_file_types))
|
||||
|
|
@ -1,95 +0,0 @@
|
|||
|
||||
````{margin}
|
||||
|
||||
```{note}
|
||||
|
||||
{bdg-link-secondary}`Uses TeachBooks package <./teachbooks_intro.html>`
|
||||
|
||||
{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>`
|
||||
|
||||
{bdg-link-light}`Supported by Deploy Book workflow <../external/deploy-book-workflow/README.html>`
|
||||
|
||||
```
|
||||
|
||||
```{tip}
|
||||
This page is useful for user type 3-5.
|
||||
```
|
||||
|
||||
```{seealso}
|
||||
|
||||
[{octicon}`mark-github` Repository](https://github.com/TeachBooks/teachbooks)
|
||||
|
||||
[{octicon}`book` Documentation](https://teachbooks.readthedocs.io/latest/cli/cli.html)
|
||||
|
||||
```
|
||||
|
||||
````
|
||||
|
||||
(draft-release)=
|
||||
# Draft-Release Workflow
|
||||
|
||||
Often it is necessary to prepare, review and edit materials in parallel to material that is currently being used by students, or another target audience. This workflow enables an author to easily maintain separate versions of a book without having to repeatedly comment out lines of a table of contents or page when building different versions. It is also easy to implement in CI/CD settings (it is already implemented in the {ref}`Deploy Book Workflow <deploy-book-workflow>`, which builds our TeachBooks).
|
||||
|
||||
```{admonition} Why is this useful?
|
||||
:class: tip
|
||||
|
||||
Consider a case where you have been using two branches to develop and maintain a book: `release` (shared with students) and `draft` (shared with colleagues to review contents before release). You are probably also using other branches to develop contents, but rely on the `draft` branch as a way to collect the "finalized-but-not-yet-released" material. Things go smoothly as long as you add pages to the `draft` branch one at a time, then merge the branch into `release` as they are needed.
|
||||
|
||||
But what happens when you have 2 pages: one is ready to share with students, but the other is still being reviewed by your colleague. The only way to get the proper page into release is to comment the undesired page in the ToC using a commit on `draft`, merge the commit into `release`, then uncomment the ToC in a new commit on `draft`. This is very tedious, and prone to error as there it is not straightforward to tell which pages are available in the `draft` versus `release` books!
|
||||
|
||||
The Draft-Release workflow solves this problem by using commented tags to clearly denote which pages are available in the `draft` book and which are left out of the `release` book.
|
||||
```
|
||||
|
||||
The workflow is enabled by a `teachbooks` CLI feature that identifies and removes any lines from the files `_config.yml` and `_toc.yml` file that are surrounded by `REMOVE-FROM-RELEASE` tags.
|
||||
|
||||
For example, pages in a developed book (e.g., `draft` branch) can be manually stripped out of the table of contents when a merge request from `draft` to `release` is made. This prevents the page being included in the released book. Pages marked with this feature are still visible in the `draft` book. Lines tagged in the configuration file `_config.yml` can be used in exactly the same manner. The tag is applied as follows:
|
||||
|
||||
```yaml
|
||||
format: jb-book
|
||||
root: intro
|
||||
|
||||
parts:
|
||||
- caption: ...
|
||||
chapters:
|
||||
- file: ...
|
||||
...
|
||||
# START REMOVE-FROM-RELEASE
|
||||
- file: files_to_remove
|
||||
# END REMOVE-FROM-RELEASE
|
||||
```
|
||||
|
||||
There is no limit to the number of stripped sections, they can be sequential and indentation does not matter.
|
||||
|
||||
To invoke the tag and remove content during the book build process, use the following optional argument when building the book with the `teachbooks` package:
|
||||
|
||||
```
|
||||
teachbooks build --release book
|
||||
```
|
||||
|
||||
This is done in the [deploy-book-workflow](deploy-book-workflow) by including the branches for which preprocessing needs to be done the repository variable `BRANCHES_TO_PREPROCESS` which is by default set to ` ` (just a space = no branch). It should be a space-separated list of branch names, e.g. 'main second third'.
|
||||
|
||||
Note that `teachbooks build book` would build a book without stripping the tagged lines, just as `jupyter-book build book` would. This is called "draft mode" and is the default behavior. You can recognize it in the stdout after running the `build` command:
|
||||
|
||||
```bash
|
||||
TeachBooks: running build with strategy 'draft'
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
The package is currently [available on PyPI](https://pypi.org/project/teachbooks/) and can be installed as follows:
|
||||
|
||||
```
|
||||
pip install teachbooks
|
||||
```
|
||||
|
||||
The first stable release (`v1.0.0`) is expected to be released in Spring 2025. Until then the package is very much useable but will be updated frequently. Therefore, get in the habit of updating the package regularly:
|
||||
|
||||
```bash
|
||||
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 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.
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 3-5.
|
||||
```
|
||||
````
|
||||
|
||||
# Easy Editing Process
|
||||
|
||||
The following tools are created by TeachBooks to ease the process of making books. We acknowledge that making books is a difficult process; it requires advanced knowledge on CLI, python packages, html-files, data-storage and website hosting. The tools in this chapter are intended for those users who lack knowledge on these topics (which includes most of the TeachBooks' community members itself).
|
||||
|
|
@ -1,88 +0,0 @@
|
|||
````{margin}
|
||||
```{attributiongrey} Attribution
|
||||
:class: attribution
|
||||
This page reuses MIT licensed content from {cite:t}`sphinx-exercise`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
|
||||
```
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 3-5.
|
||||
```
|
||||
+++
|
||||
{bdg-primary}`Sphinx Extension`
|
||||
{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>`
|
||||
{bdg-link-primary-line}`Included in TeachBooks Favourites <./favourites.html>`
|
||||
````
|
||||
|
||||
# Sphinx exercise
|
||||
|
||||
This extensions provides an easy way to add exercises and solutions to your book. It is created by the Executable Books team and is [documented here](https://ebp-sphinx-exercise.readthedocs.io/en/latest/).
|
||||
|
||||
TeachBooks has made some small modifications to the original extension, such that it works well with translated books; this modified version is located in the repository [github.com/TeachBooks/sphinx-exercise](https://github.com/TeachBooks/sphinx-exercise).
|
||||
|
||||
## What does it do?
|
||||
|
||||
This extension defines exercises and solutions as new admonition types:
|
||||
|
||||
```{exercise}
|
||||
:label: my-exercise
|
||||
|
||||
Recall that $n!$ is read as "$n$ factorial" and defined as
|
||||
$n! = n \times (n - 1) \times \cdots \times 2 \times 1$.
|
||||
|
||||
There are functions to compute this in various modules, but let's
|
||||
write our own version as an exercise.
|
||||
|
||||
In particular, write a function `factorial` such that `factorial(n)` returns $n!$
|
||||
for any positive integer $n$.
|
||||
```
|
||||
|
||||
````{solution} my-exercise
|
||||
:label: my-solution
|
||||
|
||||
Here's one solution.
|
||||
|
||||
```{code-block} python
|
||||
def factorial(n):
|
||||
k = 1
|
||||
for i in range(n):
|
||||
k = k * (i + 1)
|
||||
return k
|
||||
|
||||
factorial(4)
|
||||
```
|
||||
````
|
||||
|
||||
More information can be found in the [official documentation](https://ebp-sphinx-exercise.readthedocs.io/en/latest/).
|
||||
|
||||
## Installation
|
||||
To use this extenstion, follow these steps:
|
||||
|
||||
**Step 1: Install the Package**
|
||||
|
||||
Install the TeachBooks' version of `sphinx-exercise` package using `pip`:
|
||||
```
|
||||
pip install sphinx-exercise @ git+https://github.com/TeachBooks/sphinx-exercise.git
|
||||
```
|
||||
|
||||
**Step 2: Add to `requirements.txt`**
|
||||
|
||||
Make sure that the package is included in your project's `requirements.txt` to track the dependency:
|
||||
```
|
||||
sphinx-exercise @ git+https://github.com/TeachBooks/sphinx-exercise.git
|
||||
```
|
||||
|
||||
**Step 3: Enable in `_config.yml`**
|
||||
|
||||
In your `_config.yml` file, add the extension to the list of Sphinx extra extensions (**important**: underscore, not dash this time):
|
||||
```
|
||||
sphinx:
|
||||
extra_extensions:
|
||||
.
|
||||
.
|
||||
.
|
||||
- sphinx_exercise
|
||||
.
|
||||
.
|
||||
.
|
||||
```
|
||||
|
|
@ -1,122 +0,0 @@
|
|||
````{margin}
|
||||
```{attributiongrey} Attribution
|
||||
:class: attribution
|
||||
This page reuses MIT licensed content from {cite:t}`teachbooks_package`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
|
||||
```
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 3-5.
|
||||
```
|
||||
|
||||
{bdg-link-secondary}`Uses TeachBooks package <./teachbooks_intro.html>`
|
||||
|
||||
{bdg-success}`WebApp`
|
||||
````
|
||||
|
||||
(external-toc)=
|
||||
# Sharing content between books in table of contents
|
||||
|
||||
## Introduction
|
||||
|
||||
When creating books, you might want to reuse material from other people or from other books you made. In some cases you might even want to have the exact same material into your book. You could do so by manually copying material over. However, whenever the source material is updated, you have to do that again. As an alternative, you can use the underlying git system to refer to the source file directly. This allows you to pick a specific version, or keep the most up-to-date version of it. This pages explains how to do so directly in the table of contents using the **External Content** (or **External TOC**) feature which is part of the TeachBooks Python package, or by making use of the [TeachBooks Recombiner](https://teachbooks.io/recombiner/).
|
||||
|
||||
Previously, this book feature was implemented using [submodules](../external/Nested-Books/README.md), but the implementation was more difficult to use. Despite this, submodules are still a widely used Git feature that can be very useful for book authors, so check out the [submodules page](../external/Nested-Books/README.md) to learn more, especially if the External TOC tool does not satisfy your needs. Submodules have a few additional features not (yet) implemented using the External TOC.
|
||||
|
||||
The External TOC features are incorporated in the teachbooks package starting with version `0.2.0`. The [TeachBooks Recombiner](https://teachbooks.io/recombiner/) is a webapp to ease that process.
|
||||
|
||||
## What does it do?
|
||||
|
||||
This functionality, part of the [TeachBooks package](https://github.com/TeachBooks/TeachBooks) allows you to refer to `.ipynb`, `.md` and `.rst` files stored on public repositories. These files are then handles as if they were normal files in your book, leading to a the file as a page in your built book. To prevent issues it validates that the external content has a permissive license, automatically combines any `reference.bib` files, and warns you if there's a mismatch in `requirements.txt` or with plugins in `_config.yml`. Furthermore, it adds an attribution admonition (like the one on this page) to the page, showing the source of the file in the built book.
|
||||
|
||||
To ease the process, the webapp [TeachBooks Recombiner](https://teachbooks.io/recombiner/) allows you to select the pages to take from other books and generate the syntax to add them to your book.
|
||||
|
||||
## Installation
|
||||
To use this extension, follow these steps:
|
||||
|
||||
**Step 1: Install the Package**
|
||||
|
||||
Install the module `teachbooks` package using `pip`:
|
||||
```
|
||||
pip install teachbooks>=0.2.0
|
||||
```
|
||||
|
||||
**Step 2: Add to `requirements.txt`**
|
||||
|
||||
Make sure that the package is included in your project's `requirements.txt` to track the dependency:
|
||||
```
|
||||
teachbooks>=0.2.0
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
To use the functionality, take the URL of a file and add it to your `_toc.yml` as follows:
|
||||
|
||||
```yaml
|
||||
format: jb-book
|
||||
root: .
|
||||
|
||||
parts:
|
||||
- caption: ...
|
||||
chapters:
|
||||
- file: ...
|
||||
.
|
||||
.
|
||||
.
|
||||
- external: <link to GitHub / GitLab source .md or .ipynb file>
|
||||
.
|
||||
.
|
||||
.
|
||||
```
|
||||
|
||||
The link can be pointing to a file on a branch (which will take the most recent version of that file on the branch) or a commit or tag (which will take a specific version of the file). For example:
|
||||
- `external: https://github.com/TeachBooks/manual/blob/release/book/intro.md` will take the most recent version of the intro page of this book on the release branch
|
||||
- `external: https://github.com/TeachBooks/manual/blob/06d67e8a0110c94d9147ce07090656dedc7d0e64/README.md` will take the file during the state of a specific commit (06d67e8).
|
||||
- `external: https://github.com/TeachBooks/manual/blob/v1.1.1/README.md` will take the file during the state of a specific tag (v1.1.1)
|
||||
|
||||
These links can be created manually, copied from your browser, or generated using the [TeachBooks Recombiner](https://teachbooks.io/recombiner/). For the TeachBooks Recombiner: add the book you want to take content from, select the chapters and follow the instructions which gives you the syntax to add to your `_toc.yml`.
|
||||
|
||||
If you're building your book online in GitHub, the [deploy-book-workflow](../external/deploy-book-workflow/README.md) will deal with these files during the `teachbooks build` command. If you want to build the book locally, run the command `teachbooks build`.
|
||||
|
||||
If the source file is from another book, the contents of the `requirements.txt`, `_config.yml` are checked for any missing/incompatible entries. If this leads to compatibility issue, you'll be warned during the build which will help you solve these dependencies or plugins manually by updating your main book's `_config.yml` and `requirements.txt`
|
||||
Additionally, any `references.bib` files are merged into your main book's `references.bib` file, and the licenses of the external content are validated to allow for re-use. External content without a permissive license will result in an error to try to prevent any accidental copyright infringement.
|
||||
|
||||
### Configuration
|
||||
The attribution admonition can be configured in the `_config.yml` file. You can adapt the location (top or margin), colour (making use of the sphinx extension [Sphinx-Named-Colors](../external/Sphinx-Named-Colors/README.md)), and symbol (by adding a custom CSS class). This leads to a similar admonition as mentioned [in the chapter on recommendations for copyright and licenses](custom_attribution).
|
||||
|
||||
To adapt the location of the admonition (margin or top, top is default option), you can use the following configuration:
|
||||
|
||||
```yaml
|
||||
teachbooks:
|
||||
attribution_location: margin
|
||||
```
|
||||
|
||||
To adapt the colour of the admonition (with for example a grey colour, default is blue), you can use the following configuration. Make sure to add the `sphinx-named-colors` extension to your environment (e.g., `requirements.txt`):
|
||||
|
||||
```yaml
|
||||
sphinx:
|
||||
config:
|
||||
named_colors_custom_colors: {'attributiongrey':[150,150,150]}
|
||||
extra_extensions:
|
||||
- sphinx_named_colors
|
||||
|
||||
teachbooks:
|
||||
attribution_color: attributiongrey
|
||||
```
|
||||
|
||||
To adapt the symbol of the admonition (with for example double quotes), you can add the following [custom CSS class](../_static/attribution.css) to `book/_static/attribution.css`:
|
||||
|
||||
```css
|
||||
/* Attribution */
|
||||
div.attribution > .admonition-title::after {
|
||||
content: "\f10d";
|
||||
}
|
||||
```
|
||||
|
||||
Note that, when making a changes for the configuration locally they are not incorporated to existing external content.
|
||||
You will need to remove the `_git/` folder or run `teachbooks clean --external` and re-run the build command to see the changes. When building the book on i.e. GitHub Actions, the `_git/` folder is always rebuild from scratch.
|
||||
|
||||
|
||||
## Contribute
|
||||
|
||||
This tool's repository is stored on [GitHub](https://github.com/TeachBooks/TeachBooks). If you'd like to contribute, you can create a fork and open a pull request on the [GitHub repository](https://github.com/TeachBooks/TeachBooks).
|
||||
|
|
@ -1,97 +0,0 @@
|
|||
````{margin}
|
||||
|
||||
```{note}
|
||||
{bdg-primary}`Sphinx Extension`
|
||||
|
||||
{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>`
|
||||
|
||||
```
|
||||
|
||||
```{tip}
|
||||
This page is useful for user type 3-5.
|
||||
```
|
||||
|
||||
```{seealso}
|
||||
|
||||
[{octicon}`mark-github` Repository](https://github.com/TeachBooks/TeachBooks-Favourites)
|
||||
|
||||
[{octicon}`pencil` Exercise](https://teachbooks.io/template/extension_exercises/017.html)
|
||||
|
||||
```
|
||||
|
||||
````
|
||||
|
||||
# TeachBooks Favourites
|
||||
|
||||
TeachBooks Favourites is a Sphinx extension which collects all of TeachBooks' favourite features in one place (including tools originally by TeachBooks and from other sources). It is included by default in the [TeachBooks Template](../external/template/README.md) or can be installed independently. The features included are:
|
||||
|
||||
- [Sphinx-Thebe from TeachBooks](./live_code.ipynb)
|
||||
- [Jupyterbook patches](../external/JupyterBook-Patches/README.md)
|
||||
- [Download link replacer](../external/Download-Link-Replacer/README.md)
|
||||
- [Sphinx image inverter](../external/Sphinx-Image-Inverter/README.md)
|
||||
- [Sphinx iframes](../external/sphinx-iframes/README.md)
|
||||
- [Sphinx exercise (from Executable Books including TeachBooks contributions)](https://ebp-sphinx-exercise.readthedocs.io/en/latest/)
|
||||
- [Teachbooks Sphinx tippy](../external/teachbooks-sphinx-tippy/README.md)
|
||||
- [Sphinx named colors](../external/Sphinx-Named-Colors/README.md)
|
||||
- [Sphinx dropdown toggle](../_git/github.com_TeachBooks_Sphinx-Dropdown-Toggle/main/MANUAL.md)
|
||||
- [Sphinx proof (from Executable Books including TeachBooks contributions)](https://sphinx-proof.readthedocs.io/en/latest/)
|
||||
- [Sphinx code examples](../_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.ipynb)
|
||||
- [Sphinx accessibility](../_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.md)
|
||||
- [Sphinx toggle button (from Executable Books including TeachBooks contributions)](https://sphinx-togglebutton.readthedocs.io/en/latest/)
|
||||
- [Notebook execution patterns](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.md)
|
||||
- [Sphinx Launch Buttons](../external/Sphinx-launch-buttons/README.md)
|
||||
- [Sphinx GitHub Alerts](../_git/github.com_TeachBooks_Sphinx-GitHub-Alerts/main/README.md)
|
||||
- [Sphinx Metadata Figure](../_git/github.com_TeachBooks_Sphinx-Metadata-Figure/main/MANUAL.ipynb)
|
||||
- [Sphinx last updated by git (from Matthias Geier, TeachBooks version of the original)](https://github.com/TeachBooks/sphinx-last-updated-by-git)
|
||||
- [Sphinx Gated Directives](../_git/github.com_TeachBooks_Sphinx-Gated-Directives/main/MANUAL.md)
|
||||
- [Teachbooks Zoomies](https://github.com/TeachBooks/TeachBooks-Zoomies/)
|
||||
- [TeachBooks Questions](../_git/github.com_TeachBooks_TeachBooks-Questions/main/MANUAL.md)
|
||||
- [Sphinx Sticky Margin](../_git/github.com_TeachBooks_Sphinx-Sticky-Margin/main/MANUAL.md)
|
||||
- [TeachBooks Fetch](../_git/github.com_TeachBooks_TeachBooks-Fetch/main/MANUAL.md)
|
||||
- [Sphinx to do (from core sphinx](https://www.sphinx-doc.org/en/master/usage/extensions/todo.html)
|
||||
|
||||
The extension [Open in new tab](https://pypi.org/project/sphinx-new-tab-link/) is nice, but is not compatible with all setups (dependency clash) so is not included in TeachBooks-Favourites.
|
||||
|
||||
All features which are part of TeachBooks Favourites are include the following label on their respective pages in this manual: {bdg-primary-line}`Part of TeachBooks Favourites`. If you'd like to use specific features, but not the entire TeachBooks Favourites, you can remove this extension and replace it with the individual extensions you want to use.
|
||||
|
||||
## Installation
|
||||
To install TeachBooks-Favourites, follow these steps:
|
||||
|
||||
**Step 1: Install the Package**
|
||||
|
||||
Install the `teachbooks-favourites` package using `pip`:
|
||||
```
|
||||
pip install git+https://github.com/TeachBooks/TeachBooks-Favourites
|
||||
```
|
||||
|
||||
**Step 2: Add to `requirements.txt`**
|
||||
|
||||
Make sure that the package is included in your project's `requirements.txt` to track the dependency:
|
||||
```
|
||||
git+https://github.com/TeachBooks/TeachBooks-Favourites
|
||||
```
|
||||
|
||||
**Step 3: Enable in `_config.yml`**
|
||||
|
||||
In your `_config.yml` file, add the extension to the list of Sphinx extra extensions (**important**: underscore, not dash this time):
|
||||
```
|
||||
sphinx:
|
||||
extra_extensions:
|
||||
- teachbooks_favourites
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
For using the various package we refer to the different manuals linked above.
|
||||
|
||||
All extensions are loaded with their default settings.
|
||||
|
||||
## Contribute
|
||||
|
||||
Do you think we missed an extension that should really be included? Let us know by either
|
||||
|
||||
- creating a fork of this repository and submitting a pull request, in which you added the extension to the files
|
||||
- `README.md`
|
||||
- `pyproject.toml`
|
||||
- `src\teachbooks_favourites\__init__.py`
|
||||
- opening an issue.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 7.1 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 30 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 3.4 KiB |
33
book/features/github_deploy.md
Normal file
33
book/features/github_deploy.md
Normal file
File diff suppressed because one or more lines are too long
70
book/features/grasple.md
Normal file
70
book/features/grasple.md
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
# Grasple questions
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 3-5.
|
||||
```
|
||||
|
||||
[Grasple](https://app.grasple.com/) gives you an embed code for each exercise which looks like this, which can be added cirectly to your markdown-file.
|
||||
```html
|
||||
<iframe height="560" src="https://embed.grasple.com/exercises/767782d5-023a-4b49-a1f3-874fca626c8e?id=79907" title="Grasple Exercise 79907" width="100%" allow="clipboard-read; clipboard-write"></iframe>
|
||||
```
|
||||
|
||||
The embed link is created for an exercise under 'More'- 'Embed Exercise'
|
||||
|
||||
This iframe can be embedded into your Jupyter book.
|
||||
|
||||
```{admonition} Note
|
||||
:class: tip
|
||||
This feature doesn't display in a book that is viewed locally via your browser, unless you set up a local webserver (instructions [here](setup-local-server)).
|
||||
```
|
||||
The code shown above gives:
|
||||
<iframe height="560" src="https://embed.grasple.com/exercises/767782d5-023a-4b49-a1f3-874fca626c8e?id=79907" title="Grasple Exercise 79907" width="100%" allow="clipboard-read; clipboard-write"></iframe>
|
||||
|
||||
More information on Grasple and the support of TU Delft can be found on: [Teaching Support - Educational Tools - Grasple](https://www.tudelft.nl/en/teaching-support/educational-tools/grasple)
|
||||
|
||||
## Replace iframe by QR code for printed version
|
||||
Dani Balague Guardia created an [extension](https://github.com/dbalague/sphinx-grasple) which allows you to easily add Grasple question with some formatting and, more importantly, the creation of QR codes in the PDF version of the page. This leads to the source link of the iframe.
|
||||
|
||||
This extension can be installed by running
|
||||
|
||||
`pip install git+https://github.com/dbalague/sphinx-grasple`
|
||||
|
||||
The grasple exercise as shown above can now be added as follows in your markdown file:
|
||||
```markdown
|
||||
::::{grasple}
|
||||
:url: https://embed.grasple.com/exercises/767782d5-023a-4b49-a1f3-874fca626c8e?id=79907
|
||||
:label: grasple_exercise_1
|
||||
:dropdown:
|
||||
:description: Example of exercise which goes along
|
||||
|
||||
::::
|
||||
```
|
||||
|
||||
This leads to the following html in the Jupyter book. Remark: again, the iframe doesn't locally in VScode or in the build file, only on the hosted version.
|
||||
<div class="grasple admonition" id="grasple_exercise_1">
|
||||
|
||||
<p class="admonition-title"><span class="caption-number">Grasple Exercise 1 </span></p>
|
||||
<div class="section" id="admonition-content">
|
||||
<div class="side-by-side docutils container">
|
||||
<div class="description-container docutils container">
|
||||
<p></p><p>Example of exercise which goes along</p>
|
||||
<p></p>
|
||||
</div>
|
||||
</div>
|
||||
<details class="dropdown"><summary>Show/Hide Content</summary><iframe src="https://embed.grasple.com/exercises/767782d5-023a-4b49-a1f3-874fca626c8e?id=79907" width="100%" height="400px"></iframe></details></div>
|
||||
</div>
|
||||
|
||||
In the PDF this leads to:
|
||||
```{figure} ../images/Grasple_pdf.png
|
||||
```
|
||||
|
||||
|
||||
The extension requires an extension of the `config.yml` file:
|
||||
```markdown
|
||||
extra_extensions:
|
||||
- sphinx_grasple
|
||||
- sphinx.ext.imgconverter
|
||||
```
|
||||
|
||||
The extension should be installed both locally and on the server.
|
||||
|
|
@ -1,27 +1,15 @@
|
|||
````{margin}
|
||||
# Adding interactive h5p elements
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 3-5.
|
||||
```
|
||||
|
||||
{bdg-danger}`iframe`
|
||||
````
|
||||
|
||||
# H5p interactive elements
|
||||
|
||||
## Instruction
|
||||
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)).
|
||||
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:
|
||||
|
||||
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):
|
||||
|
||||
````
|
||||
```{h5p} https://....h5p.com/content/.../embed
|
||||
```
|
||||
````
|
||||
|
||||
Alternative, you can use raw html (lacking proper dark mode conversion):
|
||||
```html
|
||||
<iframe src="https://....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>
|
||||
<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>
|
||||
```
|
||||
|
||||
A full list of all available interactive elements is available on the website of [H5p](https://h5p.org/content-types-and-applications), these include among others:
|
||||
|
|
@ -31,14 +19,18 @@ A full list of all available interactive elements is available on the website of
|
|||
- Interactive video
|
||||
- Image hotspot
|
||||
|
||||
Some best-practices on the use of H5p:
|
||||
- H5p requires its own hosting. TU Delft provides this for TU Delft employees.
|
||||
- To startup your H5p-account, first login to H5p via Brightspace. You can follow instructions as under [https://www.tudelft.nl/teaching-support/educational-tools/h5p](https://www.tudelft.nl/teaching-support/educational-tools/h5p).
|
||||
- After that, direct login is possible via [tudelft.h5p.com](https://tudelft.h5p.com)
|
||||
- Place your H5p-elements in a shared folder in H5p.
|
||||
- Disable the display options "Toolbar Below Content" and "Display author's name to public (anonymous users) (only relevant when content's status is set to Public )" for each element for a smooth experience. On the other hand, the options 'Toolbar below content' in combination with 'Allow users to download content' allow people to reuse your questions, making them more open.
|
||||
- Use it in combination with [](../external/sphinx-iframes/README.md) to allow for a proper dark mode, dynamic scaling and a transparent background.
|
||||
More information on H5p: [Teaching Support - Educational Tools - H5P](https://www.tudelft.nl/teaching-support/educational-tools/h5p)
|
||||
|
||||
In the next subpage, these exampled are shown.
|
||||
## Example
|
||||
Truss structures are modelled as rigid bars (so elements which cannot deform) connected by hinges (so elements can rotate with respect to one each other). In our model, hinges are indicate with a circle, and bars with a line. For example, the structure you've seen in the second example (with two diagonal bars removed) is modelled as follows:
|
||||
|
||||
More information on H5p using the TU Delft provided hosting: [Teaching Support - Educational Tools - H5P](https://www.tudelft.nl/teaching-support/educational-tools/h5p)
|
||||
```{figure} ../images/Truss1.svg
|
||||
:name: truss structure
|
||||
|
||||
Bars and hinges in truss structure
|
||||
```
|
||||
|
||||
Now that you've been introduced to truss structures, answer the following question:
|
||||
|
||||
|
||||
<iframe src="https://tudelft.h5p.com/content/1291910926067816717/embed" aria-label="Modelling truss structures" 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>
|
||||
|
|
@ -9,7 +9,7 @@
|
|||
"source": [
|
||||
"# Interactive content: Elements not including Python\n",
|
||||
"\n",
|
||||
"To add interactivity to the book, you can make use of interactive elements which are embedded in the book. You've a few options:\n",
|
||||
"To add interactivity to the book, you can make use of interactive elements which are embedded in the book. You've four options:\n",
|
||||
"\n",
|
||||
" - Admonition: question provided in normal markdown language with answers in a drowdown menu. There's no feedback delivered to the student, only the correct answer no matter what the student's thinking/work.\n",
|
||||
" - JupyterQuiz: code-based implementation of multiple-choiche questions and numerical answer questions. This is a basic open course tool which requires you to write your quiz questions in Python language as a `dict` or to a `.json` file.\n",
|
||||
|
|
@ -291,9 +291,7 @@
|
|||
},
|
||||
"source": [
|
||||
"## H5p\n",
|
||||
"\n",
|
||||
"```{h5p} https://tudelft.h5p.com/content/1292010272694757307/embed\n",
|
||||
"```\n"
|
||||
"<iframe src=\"https://tudelft.h5p.com/content/1292010272694757307/embed\" aria-label=\"Exmple MUDE\" width=\"1088\" height=\"637\" 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>"
|
||||
]
|
||||
},
|
||||
{
|
||||
|
|
@ -304,15 +302,7 @@
|
|||
},
|
||||
"source": [
|
||||
"## Grasple\n",
|
||||
"\n",
|
||||
"::::{grasple}\n",
|
||||
":iframeclass: dark-light\n",
|
||||
":url: https://embed.grasple.com/exercises/156d55e4-8198-4bc7-a2c1-c0cb0ff3fef8?id=80710\n",
|
||||
":label: grasple_exercise_80710\n",
|
||||
":dropdown:\n",
|
||||
":description: Example exercise\n",
|
||||
"\n",
|
||||
"::::"
|
||||
"<iframe height=\"560\" src=\"https://embed.grasple.com/exercises/156d55e4-8198-4bc7-a2c1-c0cb0ff3fef8?id=80710\" title=\"Grasple Exercise 80710\" width=\"100%\" allow=\"clipboard-read; clipboard-write\"></iframe>"
|
||||
]
|
||||
},
|
||||
{
|
||||
|
|
@ -323,10 +313,7 @@
|
|||
"\n",
|
||||
"The example below shows a custom HTML/Javascript element\n",
|
||||
"\n",
|
||||
"```{iframe} ../_static/element_pdf_and_cdf.html\n",
|
||||
":width: 600px\n",
|
||||
":height: 300px\n",
|
||||
"```"
|
||||
"<iframe src=\"../_static/element_pdf_and_cdf.html\" width=\"600\" height=\"300\" frameborder=\"0\"></iframe>"
|
||||
]
|
||||
},
|
||||
{
|
||||
|
|
|
|||
|
|
@ -23,9 +23,9 @@ When you have installed `jupyterlite-xeus-python`, the kernel will automatically
|
|||
}
|
||||
}
|
||||
|
||||
## Updating the TeachBook's `_config.yml`
|
||||
## Updating the Jupyter Book `_config.yml`
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
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 `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`.
|
||||
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`.
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# JupyterLite-Sphinx
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## An example
|
||||
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
|
@ -4,21 +4,14 @@
|
|||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"````{margin}\n",
|
||||
"# Interactive content: Run Python inside your book\n",
|
||||
"\n",
|
||||
"```{admonition} User types\n",
|
||||
":class: tip\n",
|
||||
"This section is useful for user type 5.\n",
|
||||
"```\n",
|
||||
"\n",
|
||||
"{bdg-primary}`Sphinx Extension`\n",
|
||||
"{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>`\n",
|
||||
"{bdg-link-primary-line}`Included in TeachBooks Favourites <./favourites.html>`\n",
|
||||
"\n",
|
||||
"```` \n",
|
||||
"\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 TeachBook 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 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",
|
||||
|
|
@ -38,21 +31,6 @@
|
|||
"print('hello world')"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"```{note}\n",
|
||||
"There are two tools presented on this page: Sphinx-Thebe and JupyterLite (at the bottom). Both tools rely on Pyodide, a software tool that is the backbone allowing for a Jupyter Notebook-like experience in a web browser without requiring the user to install any software.\n",
|
||||
"\n",
|
||||
"Most of the TeachBooks Team uses a custom version of Sphinx-Thebe, a Sphinx Extension, because it can be integrated directly in a TeachBooks and provides a notebook-style experience (a \"your page is a notebook\" experience), whereas JupyterLite is more of a \"notebook-in-a-window-in-your-page\" experience.\n",
|
||||
"\n",
|
||||
"This use of Sphinx-Thebe with Pyodide was made possible in Summer 2023 by Max Guichard, originally as a set of static files loaded in the [MUDE Book](https://mude.citg.tudelft.nl/book). In January of 2024 this was converted to a custom Sphinx extension hosted on [MUDE's TU Delft GitLab](https://gitlab.tudelft.nl/mude/sphinx-thebe/-/tree/lite-main?ref_type=heads). As of February, 2025, we are currently working on improving this extension and providing it via PyPI, similar to our other tools. Stay tuned!\n",
|
||||
"\n",
|
||||
"Sphinx-Thebe can be configured to use two types of \"computers\" in the background: Pyodide (what we use, running _100% in the browser_) and Binder, which is a third-party service that provides cloud-based computers for free (i.e., code runs on a separate server). This is a great tool, but often the time required to wait for the free cloud computer to be ready is too long (or simply does not work). As most of our teaching applications only require simple pieces of code, we prefer the Pyodide-based options because it is more reliable and loads faster.\n",
|
||||
" ```"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
|
|
@ -60,12 +38,13 @@
|
|||
"## Setting up Python live coding\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 line:\n",
|
||||
"For `requirements.txt` add the following lines:\n",
|
||||
"```\n",
|
||||
"git+https://github.com/TeachBooks/Sphinx-Thebe\n",
|
||||
"--extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple\n",
|
||||
"sphinx-thebe ~= 0.9.9\n",
|
||||
"```\n",
|
||||
"\n",
|
||||
"This will download the correct version of the sphinx extension when the book is built (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",
|
||||
|
|
@ -74,7 +53,7 @@
|
|||
"\n",
|
||||
"Afterwards, this sphinx extension needs to be enabled in your book. This can be done by adding the following lines to `_config.yml`:\n",
|
||||
"\n",
|
||||
"```yaml\n",
|
||||
"```\n",
|
||||
"launch_buttons:\n",
|
||||
" thebe: true\n",
|
||||
"\n",
|
||||
|
|
@ -90,14 +69,14 @@
|
|||
"The `html_js_files` link calls for some required javascript files. `use_thebe_lite` makes sure you initiate our adapted sphinx thebe extensions. The `exclude_patterns` makes sure you import all files so that they can be accessed from your code, except for the files matching the patterns shown.\n",
|
||||
"\n",
|
||||
":::{note}\n",
|
||||
"If you've a lot of big files which are not used by the code, the build book repository might grow a lot in size. Include unnecessary filetypes like images (i.e. `\"**/*.png`) to `exclude_patterns`. Make sure you use proper markdown or MyST syntax for referencing to images. Using HTML code might lead to figures not being available in the final book. You can use [this python script](./directories.py) to list all filetypes in your book.\n",
|
||||
"If you've a lot of big files which are not used by the code, the build book repository might grow a lot in size. Include unnecessary filetypes like images (i.e. `\"**/*.png`) to `exclude_patterns`. Make sure you use proper markdown or MyST syntax for referencing to images. Using HTML code might lead to figures not being available in the final book.\n",
|
||||
":::\n",
|
||||
"\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 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",
|
||||
"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/en/stable/basics/repository.html)).\n",
|
||||
"\n",
|
||||
"```yaml\n",
|
||||
"```\n",
|
||||
"sphinx:\n",
|
||||
" config:\n",
|
||||
" html_js_files:\n",
|
||||
|
|
@ -119,7 +98,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 v1 (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 (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",
|
||||
|
|
@ -166,29 +145,16 @@
|
|||
"\n",
|
||||
"```python\n",
|
||||
"%pip install package_name\n",
|
||||
"```\n",
|
||||
"\n",
|
||||
"### Import module from subdirectory\n",
|
||||
"In case you've a module in a subdirectory you cannot do directly `import <module_name> as <local_module_name>`. To solve this, you first have to add that subdirectory to the path with `sys.path.insert(1, '/<module_name/subdirectory>')` (preferably in a hidden cell with `theme-remove-input-init`)"
|
||||
"```"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"## Exercises and examples with executable code\n",
|
||||
"\n",
|
||||
"To include executable code in your book inside exercises and/or examples, you can use the Sphinx extension [Sphinx-Exercises](https://ebp-sphinx-exercise.readthedocs.io/en/latest/syntax.html#alternative-gated-syntax) and/or the Sphinx extension {ref}`Sphinx-Code-Examples <sphinx-code-examples-gated>`.\n",
|
||||
"\n",
|
||||
"## Alternative with JupyterLite (less well integrated)\n",
|
||||
"\n",
|
||||
"Another option to use python in your browser is to use [JupyterLite](https://jupyterlite.readthedocs.io/en/stable/). However, compared to Sphinx-Thebe, described above, this doesn't give a similar seamless interface within your page. Nevertheless, depending on your application, JupyterLite could be a useful tool, especially as it allows for three IDE types: Jupyter Notebook, Jupyter Lab and the iPython REPL.\n",
|
||||
"\n",
|
||||
"One example use case is 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. If you need to manage several different environments for JupyterLite within the book, you can use a JupyterLite session from a separate repo with the jupyter lab interface anyway, so you get the full browser experience. Alternatively, the ipython REPL better can be useful, as shown in our [Python for Engineers book](https://teachbooks.io/learn-python/main/Python_Toolbox.html).\n",
|
||||
"\n",
|
||||
"```{tip}\n",
|
||||
"The TeachBooks Team has focused primarily on the use of Sphinx-Thebe and has not looked at JupyterLite over the last couple years. If you have an interesting application of this tool for teaching, please get in touch, we would love to see it! You can use [GitHub Discussions](https://github.com/orgs/TeachBooks/discussions) or sent us an email at [info@teachbooks.io](mailto:info@teachbooks.io).\n",
|
||||
"```\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."
|
||||
]
|
||||
}
|
||||
],
|
||||
|
|
|
|||
|
|
@ -1,143 +0,0 @@
|
|||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 4-5.
|
||||
```
|
||||
|
||||
{bdg-link-secondary}`Uses TeachBooks package <./teachbooks_intro.html>`
|
||||
````
|
||||
|
||||
(setup-local-server)=
|
||||
# Local Server to view interactive elements locally
|
||||
|
||||
Perhaps you have already noticed that when building a book and testing it locally on your computer, some features do not work the way you expect, or worse---do not work at all! This is because many interactive features rely on browser functionality to work properly, for example: Grasple/H5p iframe exercises, Sphinx-Thebe Python interactivity and HTML/Javascript elements. Although the website is _static_ (i.e., there is no code running on a webserver that generates the content), modern web browsers have their own internal computing environments that run processes to deliver the rich content we desire in our books.
|
||||
|
||||
Technically what is needed to facilitate this during the editing and checking of your book locally is a **static web server** that can serve the files in the `./book/_build/html` directory of your book (this subdirectory is created as a result of the command `build book`). We refer to this as a **local server** because it is running on your local machine.
|
||||
|
||||
```{admonition} Why do you need a local server?
|
||||
:class: tip
|
||||
|
||||
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>`.
|
||||
|
||||
This page presents just a few additional examples that are used by TeachBooks collaborators. There are many more options available out there, for example, [this list illustrates many servers that can be activated with a single line of code!](https://gist.github.com/willurd/5720255).
|
||||
|
||||
```{tip}
|
||||
Remember that the browser is serving static files provided by the local server and does not always keep track when they are updated.
|
||||
|
||||
You should reload the page if you are editing and rebuilding the book. You can try `CTRL+R` `ctrl`+`F5`. If this does not work, on Chrome try right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`.
|
||||
```
|
||||
|
||||
(teachbooks-serve)=
|
||||
## TeachBooks Server: `teachbooks serve`
|
||||
|
||||
If you have the TeachBooks Python package installed (`pip install teachbooks`), starting a server is as simple as:
|
||||
|
||||
```bash
|
||||
teachbooks serve
|
||||
```
|
||||
|
||||
See the {ref}`TeachBooks Package page <teachbooks-serve>` for additional guidance on using the CLI tool.
|
||||
|
||||
|
||||
By default it assumes you have a book in `./book/`, are running the command from the root `./` of your repository and will serve `./book/_build/html`. If not, it will serve the repository root. You can also specify the directory to serve:
|
||||
|
||||
```bash
|
||||
teachbooks serve path unconventional_book_dir/_build/html
|
||||
```
|
||||
|
||||
```{tip}
|
||||
Remember that the browser is serving static files provided by the local server and does not always keep track when they are updated.
|
||||
|
||||
You should reload the page if you are editing and rebuilding the book. You can try `CTRL+R` `ctrl`+`F5`. If this does not work, on Chrome try right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`.
|
||||
```
|
||||
|
||||
To stop the server, simply run
|
||||
|
||||
```bash
|
||||
teachbooks serve stop
|
||||
```
|
||||
|
||||
The CLI tool is set up to make the book edit and check workflow as easy as possible locally:
|
||||
- you can rebuild the book without restarting the server.
|
||||
- it reuses an existing server if already running.
|
||||
- it prints the URL where the book is served after building the book to easily access it by clicking the link in standard output.
|
||||
- the `teachbooks serve stop` command prevents Python processes running in the backgroudn and slowing down your computer (it saves the server state in a pickle file).
|
||||
|
||||
### Installation of TeachBooks
|
||||
|
||||
The TeachBooks package is currently [available on PyPI](https://pypi.org/project/teachbooks/) and can be installed as follows:
|
||||
|
||||
```
|
||||
pip install teachbooks
|
||||
```
|
||||
|
||||
The first stable release (`v1.0.0`) is expected to be released in Spring 2025. Until then the package is very much useable but will be updated frequently. Therefore, get in the habit of updating the package regularly:
|
||||
|
||||
```bash
|
||||
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 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.
|
||||
|
||||
## Live Server: a VS Code Extension
|
||||
|
||||
A local server is easy to initialize directly in VS Code using the Live Server extension. Once installed, it can be activated with a "Go Live" button in the bottom right corner of VS Code. The extension will automatically serve index.html, so depending on your book build settings you may need to navigate to the correct directory/file manually using the URL address in the browser.
|
||||
|
||||
````{admonition} Install Live Serve Extension
|
||||
:class: tip
|
||||
|
||||
You can install this extension by searching for `Live Server` (or even easier, extension ID `ritwickdey.LiveServer`)in the Visual Studio Code extensions marketplace.
|
||||
|
||||
```{figure} https://github.com/ritwickdey/live-server-web-extension/raw/master/img/icon.png
|
||||
---
|
||||
width: 10%
|
||||
name: live-server-icon
|
||||
```
|
||||
````
|
||||
|
||||
|
||||
## Python Server: `python -m http.server`
|
||||
|
||||
The Python standard library has a built-in server that can be activated from the command line. This is a simple way to serve a book locally
|
||||
|
||||
```
|
||||
python -m http.server
|
||||
```
|
||||
|
||||
If you don't mind typing a bit more, you can specify the port number and the directory to serve:
|
||||
|
||||
```
|
||||
python -m http.server 8000 --directory book/_build/html
|
||||
```
|
||||
|
||||
This is actually what the `teachbooks serve` command is using, but there we have added additional features to make the process more user-friendly for the book edit and check workflow.
|
||||
|
||||
### Stopping the Python Server
|
||||
|
||||
It can be challenging to stop the Python server, especially when using Windows OS. Even though you may force end the process (e.g., with `CMD+C`), the server may still be running in the background.
|
||||
|
||||
For Mac and Linux users (or for Windows if you have Git Bash installed or another Unix-type terminal), you can try this:
|
||||
|
||||
```bash
|
||||
pid=$(ps aux | grep http.server | head -n 1 | awk '{ print $2 }')
|
||||
kill -9 $pid
|
||||
```
|
||||
|
||||
Or this:
|
||||
|
||||
```bash
|
||||
tskill python
|
||||
```
|
||||
|
||||
A Windows-specific command for the CMD prompt or Powershell is:
|
||||
|
||||
```
|
||||
TASKKILL /IM python.exe /F
|
||||
```
|
||||
|
|
@ -1,30 +1,12 @@
|
|||
(feature_overview)=
|
||||
# Overview
|
||||
# TeachBooks Features
|
||||
|
||||
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!
|
||||
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!
|
||||
|
||||
Since the list of TeachBook features is getting quite long, we have grouped them in categories:
|
||||
- [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)
|
||||
- [TeachBooks student-view features](./students.md)
|
||||
This chapter provides a list of commonly used book features together with sub-pages that provide additional information on:
|
||||
- the purpose
|
||||
- how to install them
|
||||
- how to use them
|
||||
- where to find the source code
|
||||
|
||||
Additionally, not all features are built and shared in the same way. We do our best to make sure that as many tools as possible are included automatically when using our TeachBooks Template Book; if you are not using the Template, we try to make sure each of our tools can be used independently. For transparency, tags will help differentiate between the different backgrounds of the features:
|
||||
- {bdg-warning}`Javascript overlay`
|
||||
- {bdg-success}`Chrome Extension`
|
||||
- {bdg-white}`GitHub App and Javascript script`
|
||||
- {bdg-link-secondary}`Python Package: teachbooks <./teachbooks_intro.html>`
|
||||
- {bdg-link-light}`GitHub Reusable Action: Deploy Book workflow <../external/deploy-book-workflow/README.html>`
|
||||
- {bdg-link-light}`GitHub Template: TeachBooks Template <../external/template/README.html>`
|
||||
- {bdg-dark}`Git Workflow`
|
||||
- {bdg-primary}`Sphinx Extension`
|
||||
- {bdg-link-primary-line}`TeachBooks Favourites <./favourites.html>`
|
||||
- {bdg-danger}`iframe`
|
||||
- {bdg-success}`WebApp`
|
||||
To see examples for these features, go to the [Examples chapter](../examples/overview.md).
|
||||
|
||||
For each feature, the purpose, installation process and usage is elaborated in the respective sub-sections.
|
||||
|
||||
To see examples of these features, go to the [Examples chapter](../examples/overview.md).
|
||||
|
||||
As the [TeachBooks Python Package](./teachbooks_intro.md), the [Deploy Book Workflow](../external/deploy-book-workflow/README.md), [TeachBooks Favourites](./favourites.md) and the [TeachBook template](../external/template/README.md) are important tools that incorporate and deploy more than one feature, an additional explanation is provided here in subpages to this page in more detail, with links to other pages in this manual where individual features are described.
|
||||
File diff suppressed because one or more lines are too long
|
|
@ -1,105 +0,0 @@
|
|||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 3-5.
|
||||
```
|
||||
````
|
||||
|
||||
# Build pull requests from forks
|
||||
|
||||
When writing a TeachBook it is useful to automatically build and view these changes online. This exactly why we designed and build the [deploy-book-workflow](../external/deploy-book-workflow/README.md) tool, which also allows for multiple versions of your book to exist at any time with customizable URL's. However, it doesn't cover all use cases. Luckily, **Read the Docs** is a free tool that can easily be used for this purpose. It also provides a very easy way to view differences between versions on each page!
|
||||
|
||||
Pull Requests are a key tool for allowing anyone with a GitHub account to make a contribution to your work by forking your repository, adding commits, then sending them back to your repository via a Pull Request. Unfortunately you are not able to automatically build the book based on proposed changes in a pull request from a fork of your repository, as this requires the deploy-book-workflow in the fork to have GitHub Actions enabled to show the proposed changes in the book. Furthermore, when proposing your contribution in a pull request, you'd have to manually refer to your own built book (e.g., with a hyperlink). This process can be made easier by using [Read the Docs](https://about.readthedocs.com/?ref=readthedocs.org), as it can automatically build a book based on changes proposed in a pull request, and includes a link to the book directly in the pull request page.
|
||||
|
||||
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 v1; it is carried out using a Jupyter Book command to generate a Sphinx configuration file, for example:
|
||||
|
||||
```
|
||||
jupyter-book config sphinx book/
|
||||
```
|
||||
|
||||
In theory this should work with the TeachBooks Python package `teachbooks` as well as local extensions (e.g., those in `book/_ext` like [](./apa.md)), but we have not checked this yet. If you are interested, try setting it up as a PR related to [this issue](https://github.com/TeachBooks/Read-the-Docs-example-book/issues/3).
|
||||
|
||||
```{tip}
|
||||
Once set up, this tool is only accessible via the Pull Request page for a repository in the 'Checks' part of the automated rule set box (illustrated below under 'Usage'). This is different from our deploy-book-workflow, which is accessed under the Actions tab of a GitHub repository.
|
||||
|
||||
A Read the Docs account and admin privelages for a repository are the only requirements needed set this up; all visitors to the pull request page will be able to view the book, including the differencing feature.
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
After visiting the summary page of a pull request you will be able to see the following line (_make sure you click "show all checks" to see it!_):
|
||||
|
||||
|
||||
|
||||
Click 'Details' to see the logs of the build process.
|
||||
|
||||
Whenever the build is done, click 'Details' again to see the build book. Tip, click `d` or add `?readthedocs-diff=true` to the url to see the differences on the pages highlighted. Note that this differencing functionality is not perfect as it might indicate elements which are not changed intentionally. It is known to have issues visualizing changes associated with buttons, LaTeX and figures.
|
||||
|
||||
### Example
|
||||
As an example, Read the Docs is configured in this [example book](https://github.com/TeachBooks/Read-the-Docs-example-book). Fork it and open a pull request to test it's functionality.
|
||||
|
||||
There's an example [pull request](https://github.com/TeachBooks/Read-the-Docs-example-book/pull/1) with corresponding [built book on Read the Docs](https://read-the-docs-example-book--1.org.readthedocs.build/1/intro2.html?readthedocs-diff=true).
|
||||
|
||||
## Setting up
|
||||
|
||||
This tool is a specific automation rule that is enabled within the GitHub pull request ecosystem.
|
||||
|
||||
### Add configuration file to your repository
|
||||
|
||||
Add a file `.readthedocs.yaml` to the root of your repository, containing the following content:
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
|
||||
build:
|
||||
os: ubuntu-24.04
|
||||
tools:
|
||||
python: "3.13"
|
||||
jobs:
|
||||
pre_build:
|
||||
- "jupyter-book config sphinx book/"
|
||||
|
||||
python:
|
||||
install:
|
||||
- requirements: requirements.txt
|
||||
|
||||
sphinx:
|
||||
builder: html
|
||||
fail_on_warning: true
|
||||
configuration: book/conf.py
|
||||
```
|
||||
|
||||
You might need to add `standard-imghdr` to your `requirements.txt` file if the build fails when you've configured it in Read the Docs (if the error tells you `ModuleNotFoundError: No module named 'imghdr'`)
|
||||
|
||||
### Setup Read The Docs account
|
||||
|
||||
Setup an account at [app.readthedocs.org/accounts/login/](https://app.readthedocs.org/accounts/login/?next=/dashboard/). We recommend using your GitHub account for authentication.
|
||||
|
||||
When authorizing Read the Docs for your GitHub account, you can also grant access by Read the Docs for an organization of which you are an owner, as well, which we also recommend.
|
||||
|
||||
### Authorize access to organization
|
||||
|
||||
When you didn't do so in the previous step, or you'd like to grant access at a later moment, you can grant/revoke access by Read the Docs to your organization by following these menu items in settings: [`personal GitHub Settings - Integrations - Applications - Authorized OAuth Apps - Read the Docs Community`](https://github.com/settings/connections/applications/fae83c942bc1d89609e2).
|
||||
|
||||
### Add project in Read The Docs
|
||||
|
||||
On your [dashboard](https://app.readthedocs.org/dashboard/), add a new project. Find your GitHub repository (you might need to refresh your repositories if you've recently updated authorizations).
|
||||
|
||||
### Enable Pull Request build
|
||||
|
||||
In the setting of your newest project, enable build of pull request by selecting the option in `Building - Pull request builds - Build pull requests for this project`.
|
||||
|
||||
### Additional settings
|
||||
|
||||
The following settings are recommended:
|
||||
- `Setup` - `Settings` - `URL versioning scheme` - `Multiple versions without translations (/<version>/<filename>)`, as translated books can be implemented with [](../external/Sphinx-launch-buttons/README.md)
|
||||
- `Setup` - `Settings` - `Addons` - `Search` - disabled, as your books already contain a search function and the Read the Docs search functions requires [additional setup](https://docs.readthedocs.com/platform/stable/intro/sphinx.html#configure-read-the-docs-search)
|
||||
- `Setup` - `Settings` - `Addons` - `Link previews` - disabled, `Multiple versions without translations (/<version>/<filename>)`, as previews can be implemented with [](../external/teachbooks-sphinx-tippy/README.md)
|
||||
- `Setup` - `Settings` - `Automation rules` - `Add rule`, to build all tagged versions of your book:
|
||||
- `Description`: 'Build all tags'
|
||||
- `Match`: `Custom Match`
|
||||
- `Custom match`: `.*`
|
||||
- `Version type`: `Tag`
|
||||
- `Action`: `Activate version`
|
||||
|
|
@ -1,257 +0,0 @@
|
|||
````{margin}
|
||||
|
||||
```{note}
|
||||
|
||||
{bdg-link-light}`GitHub Reusable Action: Deploy Book workflow <../external/deploy-book-workflow/README.html>`
|
||||
|
||||
{bdg-link-light}`Part of TeachBooks Template <../external/template/README.html>`
|
||||
|
||||
{bdg-link-secondary}`Uses TeachBooks package <./teachbooks_intro.html>`
|
||||
|
||||
```
|
||||
|
||||
```{tip}
|
||||
This section is useful for user type 3-5.
|
||||
```
|
||||
|
||||
```{seealso}
|
||||
|
||||
[{octicon}`mark-github` Repository deploy book workflow](https://github.com/TeachBooks/deploy-book-workflow)
|
||||
|
||||
[{octicon}`book` Publish version on separate (fixed) URLs](../installation-and-setup/versions_URLs.md)
|
||||
|
||||
{octicon}`pencil` Exercises:
|
||||
- [Your version of the book](https://teachbooks.io/template/exercises/004.html)
|
||||
- [Deploy book workflow](https://teachbooks.io/template/extension_exercises/015.html)
|
||||
|
||||
```
|
||||
|
||||
````
|
||||
|
||||
# Share book online for multiple versions
|
||||
|
||||
As you'll start working on your TeachBook, you'll probably want to share it online. And over time you'll create more and more versions of your book, for example for different academic years.
|
||||
|
||||
Our Deploy Book Workflow (described in general [here](../external/deploy-book-workflow/README.md)) allows you to do so. It builds your book for all branches in your repository and releases them online via GitHub Pages. In simplified terms, it automatically builds the book website based on updates to your repository, creates multiple instances of your book (defined by each branch) and provides the ability to customize the URL's at which each instance of the book can be accessed. This tool is designed specifically for educational contexts, for example, when you may want to preserve book versions from multiple academic years so that students are able to access it later.
|
||||
|
||||
Sharing your book online has many features and customizations:
|
||||
- Automatic and manual building and releasing of your book online via GitHub Pages using a Reusable GitHub Actions. See explanation [below](how_to_start).
|
||||
- Ability to release both private (GitHub Pro, GitHub Team, GitHub Enterprise Cloud, or GitHub Enterprise Server required) and public (GitHub Free is enough) repositories. GitHub Teams is free for teachers as described in the [GitHub documentation](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers). If you have an organization for your TeachBook on GitHub, link your GitHub team rights to your organization as described on the [GitHub website](https://github.com/team#organizations).
|
||||
- Releasing all or a selection of branches, allowing to build a draft version of the TeachBook online which reduces the need for local builds of the book. See explanation [below](gh-workflow-settings).
|
||||
- Allowing use of submodules within your book. For private submodules, see the explanation [below](private_submodules)
|
||||
- Converting branch-names to well-defined URLs. See explanation [below](gh-workflow-settings).
|
||||
- Customizable settings on where the books should be deployed including alias for branch-names and selection of one branch to be deployed on root. The workflow will gives warnings if these settings are ill-defined or conflicting. Although aliases are generally not allowed by GitHub Pages, it seems you can use one alias, but not more. See explanation [below](gh-workflow-settings).
|
||||
- Customizable behavior of book URL root directory, either by redirecting the root to one of the branches or by copying or moving one of the branches to root. See explanation [below](gh-workflow-settings).
|
||||
- Adds an 'archived'-banner to old branches / branches of previous years. See explanation [below](gh-workflow-settings).
|
||||
- Custom 404 "Page Not Found" page with buttons for redirecting to Homepage (e.g., book intro page), "Go Back" or Repository home.
|
||||
- Provides a summary describing where the TeachBook is released, errors in the build process per branch and how the release step is configured. See explanation [below](gh-workflow-summary)
|
||||
- Caching of already built books so that it can be partially reused when another branch is released or the next build contains critical errors. See explanation [below](gh-caching)
|
||||
- Caching of python environment to speed up the workflow. See explanation [below](gh-caching)
|
||||
|
||||
(how_to_start)=
|
||||
## How to start using this workflow
|
||||
|
||||
The Deploy Book Workflow is by default incorporated into any book that has been created using the [TeachBooks Template](https://github.com/TeachBooks/template).
|
||||
|
||||
Feel free to use it for your existing TeachBook as well:
|
||||
1. Add [`teachbooks`](https://github.com/TeachBooks/TeachBooks) to your `requirements.txt` file in your root folder
|
||||
2. Move all the TeachBook files (including `_config.yml` and `_toc.yml`) to a subdirectory `book/`.
|
||||
3. Copy the [`call-deploy-book.yml`](https://github.com/TeachBooks/template/blob/main/.github/workflows/call-deploy-book.yml) workflow to the `/.github/workflows` folder in your repository (the file is located in the TeachBooks Template repository becuase that file then refers to the file `deploy-book.yml` located in _this_ repository).
|
||||
4. Set source for GitHub pages to GitHub Actions under <svg aria-label="Edit repository metadata" role="img" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-gear float-right"> <path d="M8 0a8.2 8.2 0 0 1 .701.031C9.444.095 9.99.645 10.16 1.29l.288 1.107c.018.066.079.158.212.224.231.114.454.243.668.386.123.082.233.09.299.071l1.103-.303c.644-.176 1.392.021 1.82.63.27.385.506.792.704 1.218.315.675.111 1.422-.364 1.891l-.814.806c-.049.048-.098.147-.088.294.016.257.016.515 0 .772-.01.147.038.246.088.294l.814.806c.475.469.679 1.216.364 1.891a7.977 7.977 0 0 1-.704 1.217c-.428.61-1.176.807-1.82.63l-1.102-.302c-.067-.019-.177-.011-.3.071a5.909 5.909 0 0 1-.668.386c-.133.066-.194.158-.211.224l-.29 1.106c-.168.646-.715 1.196-1.458 1.26a8.006 8.006 0 0 1-1.402 0c-.743-.064-1.289-.614-1.458-1.26l-.289-1.106c-.018-.066-.079-.158-.212-.224a5.738 5.738 0 0 1-.668-.386c-.123-.082-.233-.09-.299-.071l-1.103.303c-.644.176-1.392-.021-1.82-.63a8.12 8.12 0 0 1-.704-1.218c-.315-.675-.111-1.422.363-1.891l.815-.806c.05-.048.098-.147.088-.294a6.214 6.214 0 0 1 0-.772c.01-.147-.038-.246-.088-.294l-.815-.806C.635 6.045.431 5.298.746 4.623a7.92 7.92 0 0 1 .704-1.217c.428-.61 1.176-.807 1.82-.63l1.102.302c.067.019.177.011.3-.071.214-.143.437-.272.668-.386.133-.066.194-.158.211-.224l.29-1.106C6.009.645 6.556.095 7.299.03 7.53.01 7.764 0 8 0Zm-.571 1.525c-.036.003-.108.036-.137.146l-.289 1.105c-.147.561-.549.967-.998 1.189-.173.086-.34.183-.5.29-.417.278-.97.423-1.529.27l-1.103-.303c-.109-.03-.175.016-.195.045-.22.312-.412.644-.573.99-.014.031-.021.11.059.19l.815.806c.411.406.562.957.53 1.456a4.709 4.709 0 0 0 0 .582c.032.499-.119 1.05-.53 1.456l-.815.806c-.081.08-.073.159-.059.19.162.346.353.677.573.989.02.03.085.076.195.046l1.102-.303c.56-.153 1.113-.008 1.53.27.161.107.328.204.501.29.447.222.85.629.997 1.189l.289 1.105c.029.109.101.143.137.146a6.6 6.6 0 0 0 1.142 0c.036-.003.108-.036.137-.146l.289-1.105c.147-.561.549-.967.998-1.189.173-.086.34-.183.5-.29.417-.278.97-.423 1.529-.27l1.103.303c.109.029.175-.016.195-.045.22-.313.411-.644.573-.99.014-.031.021-.11-.059-.19l-.815-.806c-.411-.406-.562-.957-.53-1.456a4.709 4.709 0 0 0 0-.582c-.032-.499.119-1.05.53-1.456l.815-.806c.081-.08.073-.159.059-.19a6.464 6.464 0 0 0-.573-.989c-.02-.03-.085-.076-.195-.046l-1.102.303c-.56.153-1.113.008-1.53-.27a4.44 4.44 0 0 0-.501-.29c-.447-.222-.85-.629-.997-1.189l-.289-1.105c-.029-.11-.101-.143-.137-.146a6.6 6.6 0 0 0-1.142 0ZM11 8a3 3 0 1 1-6 0 3 3 0 0 1 6 0ZM9.5 8a1.5 1.5 0 1 0-3.001.001A1.5 1.5 0 0 0 9.5 8Z"></path> </svg>`Settings` - <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-browser"> <path d="M0 2.75C0 1.784.784 1 1.75 1h12.5c.966 0 1.75.784 1.75 1.75v10.5A1.75 1.75 0 0 1 14.25 15H1.75A1.75 1.75 0 0 1 0 13.25ZM14.5 6h-13v7.25c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25Zm-6-3.5v2h6V2.75a.25.25 0 0 0-.25-.25ZM5 2.5v2h2v-2Zm-3.25 0a.25.25 0 0 0-.25.25V4.5h2v-2Z"></path> </svg> `Pages` - `Build and deployment` - `Source` - `GitHub Actions` (as long as you don't do this the workflow deploys all branches which build successfully).
|
||||
5. Trigger the workflow by making an edit to the TeachBook by editing and committing changes to one of the files in the `book/` subdirectory (available under <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-code UnderlineNav-octicon d-none d-sm-inline"> <path d="m11.28 3.22 4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L13.94 8l-3.72-3.72a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215Zm-6.56 0a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042L2.06 8l3.72 3.72a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L.47 8.53a.75.75 0 0 1 0-1.06Z"></path></svg> `Code`) or manually activating the workflow under <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-play UnderlineNav-octicon d-none d-sm-inline"> <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path></svg>`Actions` - `All workflows` - `call-deploy-book` - `Run workflow` - `Use workflow from branch: <the branch you did step 1, 2 and 3 in>` - `Run workflow` (this workflow).
|
||||
6. Now checkout the progress and summary of the releasing workflow under <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-play UnderlineNav-octicon d-none d-sm-inline"> <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path></svg>`Actions` - `All workflows` - `call-deploy-book` -`<the most recent workflow run>`.
|
||||
|
||||
(gh-workflow-settings)=
|
||||
## Customize the workflow: TeachBook releasing settings
|
||||
You can adapt the behaviour by setting repository variables as explained [here](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository) or using the [VS Code Extension GitHub Actions](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-github-actions). Define the following repository variables:
|
||||
- `PRIMARY_BRANCH` which is set to `main` whenever it's not defined in the repository variables.
|
||||
- This sets the branch or alias (when using 'redirect' for `BEHAVIOR_PRIMARY`) which is shown on root.
|
||||
- It is advised to show either your default branch on root, or the branch shared with your primary/active book audience (e.g., your current students).
|
||||
- `BEHAVIOR_PRIMARY` which is set to `redirect` whenever it's not defined in the repository variables.
|
||||
- This indicates whether to copy the PRIMARY_BRANCH to root ('copy'), move the PRIMARY_BRANCH to root ('move') or redirect from root to the PRIMARY_BRANCH ('redirect')
|
||||
- Advised to use 'redirect' if you expect to archive a version in the future so that the URL doesn't change for the reader (e.g., to preserve URL containing the current academic year shared with students).
|
||||
- Use copy or move when you only expect readers to use the root URL. Move is useful to remove unnecessary build artifacts and if you don't need to visit the URL containing the branch or alias name.
|
||||
- `BRANCH_ALIASES` which is set to ` ` (just a space) whenever it's not defined in the repository variables.
|
||||
- This defines an alias (custom URL) for a branch
|
||||
- Variables should be a space-separated list of branch names, e.g. 'alias:really-long-branch-name`
|
||||
- If no alias is wanted, `BRANCH_ALIASES` may be set to ` ` (just a space)
|
||||
- `BRANCHES_TO_DEPLOY` which is set to `*` (all branches) whenever it's not defined in the repository variables.
|
||||
- This defines the branches to deploy.
|
||||
- It should be a space-separated list of branch names, e.g. 'main second third'.
|
||||
- `BRANCHES_TO_PREPROCESS` which is set to ` ` (just a space = no branch) whenever it's not defined in the repository variables
|
||||
- This defines the branches to preprocess with the [`TeachBooks` package](./draft-release.md), which removed book-pages and config lines defined with `# START REMOVE-FROM-RELEASE` and `# END REMOVE-FROM-RELEASE`
|
||||
- It should be a space-separated list of branch names, e.g. 'main second third'.
|
||||
- If no preprocessing is required, `BRANCH_TO_PREPROCESS` may be set to ' ' (space).
|
||||
- `BRANCHES_ARCHIVED` which is set to ` ` (space, no branch) whenever it's not defined in the repository variables
|
||||
- This adds a banner to the released branch: You are viewing an archived version of the book. Click here for the latest version.
|
||||
- It should be a space-separate list of branch names, e.g. 'main second third'.
|
||||
|
||||
In `call-deploy-book.yml` itself you can specify the trigger for this workflow. By default, a push to any branch triggers the workflow. You can limit the branches or subdirectories.
|
||||
|
||||
## Additional GitHub settings
|
||||
We advise you to enable two options in the general repository setting regarding pull requests in GitHub:
|
||||
- Enable `Always suggest updating pull request branches`, suggesting a merge from the default branch into any separate branch before merging into main.
|
||||
- Enable `Automatically delete head branches` to delete branches after they are merged (you'll still be able to restore those).
|
||||
|
||||
## Common Usage Examples
|
||||
|
||||
Relevant use cases are explained here, along with an explanation for how to set up the workflow accordingly. Note that it is not required to set your `PRIMARY_BRANCH` to the default branch of your GitHub repository; this is a choice that is determined by what version of the source code you want visitors to see (i.e., work in progress, or the most recent "complete" or "released" version of a book).
|
||||
|
||||
### Books with active users of different versions (academic years)
|
||||
|
||||
Consider a case where each academic year you would like to create a new book for your students. However, you need to ensure that students from previous years can still access "their" version of the book.
|
||||
|
||||
Assume for this example that we are working in the "my_organization" GitHub Organization in repository "my_book" and that the current academic year is 2025, and that we have one or more books in our repository from previous years. The desired URL structure is thus:
|
||||
- students from this year use the book at `my_organization.github.io/my_book/2025/`
|
||||
- students from last year use the book at `my_organization.github.io/my_book/2024/`
|
||||
- visitors to `my_organization.github.io/my_book/` will automatically be redirected to the book from the current year
|
||||
|
||||
To create this behavior, do the following:
|
||||
|
||||
- Create a branch for each year: a logical name would have format `YYYY`, (technically it can be anything, as the URL can be set to `YYYY` with `BRANCH_ALIASES`).
|
||||
- Set `PRIMARY_BRANCH` to the branch for the current academic year (e.g., `2025`)
|
||||
- Set `BEHAVIOR_PRIMARY` to `redirect` (default)
|
||||
|
||||
#### Alternative without redirect to current year
|
||||
|
||||
One possible modification to this setup would be if you are progressively releasing content to your current students (e.g., `2025`) but you wanted visitors to `my_organization.github.io/my_book/` to see a complete version of your book. Assuming that the ideal version for such visitors is the completed book from the previous year (`2024`), you could do this:
|
||||
- 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 v1 banner feature](https://jupyterbook.org/v1/web/announcements.html).
|
||||
|
||||
### Books with active editors working in parallel
|
||||
|
||||
Consider a case where several authors are working on material for a book and you would like to be able to see the work of any author at any time. You also have a branch that is used to share finalized material with your readers (we call this a "release" branch) and a branch that is used to collect and review the work of all authors before releasing it (we call this a "draft" branch).
|
||||
|
||||
Assume for this example that we are working in the "my_organization" GitHub Organization in repository "my_book." The released book is on branch `release` the draft book is on branch `draft`; author branches are `author_1`, `author_2`, etc. The desired URL structure is thus:
|
||||
- official (released) version of the book is at `my_organization.github.io/my_book/`
|
||||
- draft version of the book is at `my_organization.github.io/my_book/draft/`
|
||||
- the work of each author can be found at `my_organization.github.io/my_book/author_1/`, etc.
|
||||
|
||||
To create this behavior, do the following:
|
||||
|
||||
- Create a branch for each author as well as `release` and `draft` branches
|
||||
- Set `draft` to the default branch
|
||||
- Set `PRIMARY_BRANCH` to `release`
|
||||
- Set `BEHAVIOR_PRIMARY` to `copy`
|
||||
|
||||
Note that in this situation we strongly recommend using the Draft-Release workflow that is incorporated in the TeachBooks Python package, which allows you to restrict specific content from appearing in the `release` book that is already incorporated in the `draft` book. [Find out more here](./draft-release.md). This is useful, for example, if you would like to review many chapters, but release only one at a time, or use a banner in the draft book (e.g., via `_config.yml`) but not the released book.
|
||||
|
||||
#### Why make the draft branch default?
|
||||
|
||||
What if you want to make sure the source code for the released book is visible in the repository, rather than the draft version (e.g., you want to make sure external visitors see this version of the material)? You can do this by making `release` your default branch instead of `draft`. However, this also means that Pull Requests will be default be made into the `release` branch instead of `draft`, which may alter the working method of your team in an undesirable way (e.g., not being able to use a `draft` branch, accidentally releasing material before checking on `draft`, or having to manually adjust every PR that is created by GitHub to merge into `draft` instead of `release`).
|
||||
|
||||
(private_submodules)=
|
||||
## Private submodules
|
||||
In case your book includes private submodules, you'll need to create a Personal Access Token (classic) with at least the scope `repo` as described in the [github documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), and add this token with the name `GH_PAT` as a `Repository secret` or `Organization secret` (<svg aria-label="Edit repository metadata" role="img" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-gear float-right"> <path d="M8 0a8.2 8.2 0 0 1 .701.031C9.444.095 9.99.645 10.16 1.29l.288 1.107c.018.066.079.158.212.224.231.114.454.243.668.386.123.082.233.09.299.071l1.103-.303c.644-.176 1.392.021 1.82.63.27.385.506.792.704 1.218.315.675.111 1.422-.364 1.891l-.814.806c-.049.048-.098.147-.088.294.016.257.016.515 0 .772-.01.147.038.246.088.294l.814.806c.475.469.679 1.216.364 1.891a7.977 7.977 0 0 1-.704 1.217c-.428.61-1.176.807-1.82.63l-1.102-.302c-.067-.019-.177-.011-.3.071a5.909 5.909 0 0 1-.668.386c-.133.066-.194.158-.211.224l-.29 1.106c-.168.646-.715 1.196-1.458 1.26a8.006 8.006 0 0 1-1.402 0c-.743-.064-1.289-.614-1.458-1.26l-.289-1.106c-.018-.066-.079-.158-.212-.224a5.738 5.738 0 0 1-.668-.386c-.123-.082-.233-.09-.299-.071l-1.103.303c-.644.176-1.392-.021-1.82-.63a8.12 8.12 0 0 1-.704-1.218c-.315-.675-.111-1.422.363-1.891l.815-.806c.05-.048.098-.147.088-.294a6.214 6.214 0 0 1 0-.772c.01-.147-.038-.246-.088-.294l-.815-.806C.635 6.045.431 5.298.746 4.623a7.92 7.92 0 0 1 .704-1.217c.428-.61 1.176-.807 1.82-.63l1.102.302c.067.019.177.011.3-.071.214-.143.437-.272.668-.386.133-.066.194-.158.211-.224l.29-1.106C6.009.645 6.556.095 7.299.03 7.53.01 7.764 0 8 0Zm-.571 1.525c-.036.003-.108.036-.137.146l-.289 1.105c-.147.561-.549.967-.998 1.189-.173.086-.34.183-.5.29-.417.278-.97.423-1.529.27l-1.103-.303c-.109-.03-.175.016-.195.045-.22.312-.412.644-.573.99-.014.031-.021.11.059.19l.815.806c.411.406.562.957.53 1.456a4.709 4.709 0 0 0 0 .582c.032.499-.119 1.05-.53 1.456l-.815.806c-.081.08-.073.159-.059.19.162.346.353.677.573.989.02.03.085.076.195.046l1.102-.303c.56-.153 1.113-.008 1.53.27.161.107.328.204.501.29.447.222.85.629.997 1.189l.289 1.105c.029.109.101.143.137.146a6.6 6.6 0 0 0 1.142 0c.036-.003.108-.036.137-.146l.289-1.105c.147-.561.549-.967.998-1.189.173-.086.34-.183.5-.29.417-.278.97-.423 1.529-.27l1.103.303c.109.029.175-.016.195-.045.22-.313.411-.644.573-.99.014-.031.021-.11-.059-.19l-.815-.806c-.411-.406-.562-.957-.53-1.456a4.709 4.709 0 0 0 0-.582c-.032-.499.119-1.05.53-1.456l.815-.806c.081-.08.073-.159.059-.19a6.464 6.464 0 0 0-.573-.989c-.02-.03-.085-.076-.195-.046l-1.102.303c-.56.153-1.113.008-1.53-.27a4.44 4.44 0 0 0-.501-.29c-.447-.222-.85-.629-.997-1.189l-.289-1.105c-.029-.11-.101-.143-.137-.146a6.6 6.6 0 0 0-1.142 0ZM11 8a3 3 0 1 1-6 0 3 3 0 0 1 6 0ZM9.5 8a1.5 1.5 0 1 0-3.001.001A1.5 1.5 0 0 0 9.5 8Z"></path> </svg>`Settings` > <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-key-asterisk"> <path d="M0 2.75A2.75 2.75 0 0 1 2.75 0h10.5A2.75 2.75 0 0 1 16 2.75v10.5A2.75 2.75 0 0 1 13.25 16H2.75A2.75 2.75 0 0 1 0 13.25ZM2.75 1.5c-.69 0-1.25.56-1.25 1.25v10.5c0 .69.56 1.25 1.25 1.25h10.5c.69 0 1.25-.56 1.25-1.25V2.75c0-.69-.56-1.25-1.25-1.25Z"></path><path d="M8 4a.75.75 0 0 1 .75.75V6.7l1.69-.975a.75.75 0 0 1 .75 1.3L9.5 8l1.69.976a.75.75 0 0 1-.75 1.298L8.75 9.3v1.951a.75.75 0 0 1-1.5 0V9.299l-1.69.976a.75.75 0 0 1-.75-1.3L6.5 8l-1.69-.975a.75.75 0 0 1 .75-1.3l1.69.976V4.75A.75.75 0 0 1 8 4Z"></path></svg>`Secrets and variables` > `Actions` > `Repository secrets` or `Organization secrets`.) Furthermore, manually copy the workflow (.github/workflows/deploy-book.yml) in your own repository as the authorization doesn't work with the called workflow.
|
||||
|
||||
(gh-workflow-summary)=
|
||||
## View the workflow progress and summary
|
||||
|
||||
Whenever the workflow is triggered, its progress and a summary can be seen under the <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-play UnderlineNav-octicon d-none d-sm-inline"> <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path></svg>`Actions`- `All workflows` - `call-deploy-book` in GitHub! It shows you a descriptive summary:
|
||||
- Ill-defined repository configuration variables (in `Annotations`)
|
||||
- Which branches are released and where (`https://<username/organization_name>.github.io/<repository_name>` (case sensitive)) including which branch is released on the website root and the applied alias
|
||||
- Errors in the build process
|
||||
- How the repository variables are defined during the build.
|
||||
|
||||
Here's an example for a summary for the template book:
|
||||
|
||||
> ### Branches deployed
|
||||
> | Branch 🎋 | Link 🔗 | Build status ☑️ |
|
||||
> | :--- | :--- | :--- |
|
||||
> | main | [https://teachbooks.github.io/template/main](https://teachbooks.github.io/template/main) | ✅ `Released` |
|
||||
> | version2 | [https://teachbooks.github.io/template/version2](https://teachbooks.github.io/template/version2) | 🔴 `Build failed [1]` |
|
||||
> | version3 | [https://teachbooks.github.io/template/version3](https://teachbooks.github.io/template/version3) | ⭕ `Build failed [2]` |
|
||||
>
|
||||
> #### Legend for build status
|
||||
> ✅ `Released` - build success, new version released.
|
||||
>
|
||||
> 🔴 `Build failed [1]` - build failure, previous version of the book reused.
|
||||
>
|
||||
> ⭕ `Build failed [2]` - build failure, no previous version reused.
|
||||
>
|
||||
> #### Primary book at root
|
||||
> The book at the website root <https://teachbooks.github.io/template/> redirects to the primary branch `main` (status: ✅ `Released`).
|
||||
>
|
||||
> ### Aliases
|
||||
> | Alias ➡️ | Target 🎯 | Link 🔗 | Build status ☑️ |
|
||||
> | :--- | :--- | :--- | :---- |
|
||||
> | draft | main | [https://teachbooks.github.io/template/draft](https://teachbooks.github.io/template/draft) | ✅ `Released` |
|
||||
>
|
||||
> ### Preview of build errors & warnings
|
||||
> For more details please see the corresponding `build-books` jobs in the left pane.
|
||||
>
|
||||
> On branch `version2`:
|
||||
> ```
|
||||
> <20>[91m/home/runner/work/template/template/book/some_content/overview.md:5: WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]<5D>[39;49;00m
|
||||
> ```
|
||||
>
|
||||
> On branch `version3`:
|
||||
> ```
|
||||
> /home/runner/work/_temp/ff8c8325-8d8b-4c0b-a2b2-32d2169c55bc.sh: line 8: teachbooks: command not found
|
||||
> ```
|
||||
>
|
||||
> ### Repository configuration variables
|
||||
> Variables can be set at <https://github.com/TeachBooks/template/settings/variables/actions>
|
||||
>
|
||||
> ```
|
||||
> PRIMARY_BRANCH=main (default value used)
|
||||
> BRANCH_ALIASES=draft:main
|
||||
> BRANCHES_TO_DEPLOY=* (default value used)
|
||||
> BRANCHES_TO_PREPROCESS=main
|
||||
> BEHAVIOR_PRIMARY=redirect (default value used)
|
||||
> BRANCHES_ARCHIVED= (default value used)
|
||||
> ```
|
||||
|
||||
(gh-caching)=
|
||||
## Caching
|
||||
|
||||
The GitHub Action [Cache](https://github.com/actions/cache) is used in the Deploy Book Workflow (DBW) to save time when building the book. This is accompliched by caching two sets of files for each branch: 1) the Python virtual environment, and 2) the build artifact (the HTML files forming each book website).
|
||||
|
||||
The reason for doing this stems from the primary purpose of the Deploy Book Workflow, which builds many versions of a book based on each branch, as well as creating a Python virtual environment from the `requirements.txt` file in the repository. A unique environment for each branch is necessary to test changes to book dependencies and configuration in an isolated way, but can dramatically increase the time required to build all versions of the book when the DBW runs. In addition, it also takes time to build the book itself. For this reason, both of these sets of files are cached (although at the moment, most of the time savings is primarily caching the build artifact).
|
||||
|
||||
This works by hashing a specific set of files and including that in the filename of the cache. Every time the workflow is triggered, a new hashed filename is created and compared to the list of existing caches to see if one with the same name exists; if so, the cache is reused. If not, a new environment and/or build artifact is constructed and a new cache is made.
|
||||
|
||||
Cached files can be found in GitHub under the Actions tab, then looking for the "Caches" section under the "Management" pane on the left hand side of the screen. For example, this link shows the [caches for this TeachBooks Manual](https://github.com/TeachBooks/manual/actions/caches). If needed, caches can be deleted manually from this page. A cache will expire if unused for longer than 1 week or if the maximum allowed disk space for all cached files is exceeded (both are GitHub policies).
|
||||
|
||||
Files created during a GitHub Action are called [artifacts](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow). Although this is _not_ the same thing as a cache, the files in a specific cache or artifact are identical. Artifacts have their own expiration period, which is possible to [customize in the repository settings](https://docs.github.com/en/organizations/managing-organization-settings/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-organization) (default is 90 days). Unexpired artifacts can be viewed at the bottom of any workflow run summary that is available on the Actions tab of a GitHub repository.
|
||||
|
||||
To add even more confusion to the situation, if an artifact built during an Action is a set of HTML files (a website) that are used to create a GitHub Pages website, the files served when visiting the URL for that are stored on a webserver; they are _not_ the artifact files, but are identical. Fortunately webserver files are preserved indefinitely (or until GitHub changes this policy), meaning that even though your cache or artifact may be deleted, the website will still remain active.
|
||||
|
||||
The cache is a key component of the DBW and leads to several considerations for the building and maintenance of a book, which are explained below, after the criteria for each cache type are described.
|
||||
|
||||
### Cached Environment
|
||||
|
||||
The DBW uses [Python virtual environments](https://docs.python.org/3/library/venv.html) (`python -m venv .venv`) and `python -m pip install -r requirements.txt` to install packages and create the book building environment. The entire `.venv` directory is preserved in the cache with a file name beginning with `venv-...`. The week number is also included in the file hash, which ensures that a new hash is created at least once per week.
|
||||
|
||||
Once created during a successful build action, an existing cached environment will be found and reused unless two specific criteria are met: 1) a book build is required (replacing the cached build artifact), _and_ 2) the `requirements.txt` file is changed. Requirements for a "book build" are described in the next section.
|
||||
|
||||
Note that any change to the `requirements.txt` file will trigger creation of a new environment, not necessarily one that specifies the version number of a package.
|
||||
|
||||
Note that Specifying package version numbers explicitly and updating them via [Dependabot](./update_env.md) is an excellent way to ensure that environments in the DBW are always up to date and this issue is avoided.
|
||||
|
||||
If you are _not_ using Dependabot and are not able to get your packages updated when the DBW is running, delete the cache manually and rerun your GitHub Actions job (go to Actions tab, then looking for the "Caches" section under the "Management" pane on the left hand side of the screen).
|
||||
|
||||
### Cached Build Artifacts
|
||||
|
||||
Build artifacts are the HTML files that define the website (i.e., the book) and are typically located in the subdirectory `book/_build/html` of a repository once the book is built. Note that these files are typically only visible if you are building the book locally, as they are not committed to the repository by default (i.e., `.gitignore`). For users only using the DBW and the GitHub browswer editor, downloading the build cache is the easiest way to view these files, which have filenames beginnig with `html-build-<branch-name>-...`.
|
||||
|
||||
Once created during a successful build action, an existing cached build artifact will be found and reused unless _any_ of three specific criteria are met: 1) a change is made to a file in `book/`, 2) the `requirements.txt` file is changed, or 3) the status of a branch as archive or preprocess has changed (`BRANCHES_TO_PREPROCESS` of `BRANCHES_ARCHIVED`).
|
||||
|
||||
Immediately after a successful build action, the book website files exist in three places: cache, artifact and on a GitHub webserver. However, as described at the beginning of this section, the cache will be automatically deleted after 1 week, if unused, and the artifact will be deleted based on the setting in your repository (90 days by default).
|
||||
|
||||
### Effect of Caching on Book Workflow
|
||||
|
||||
Implementation of the DBW has several characteristics that should be noted which could help understand certain behaviors of the book build and website deployment process. These points may be useful to consider if you are experiencing undesired behavior in your Actions builds and/or your actual book websites.
|
||||
|
||||
- Remember that the DBW action will only run if a commit is made that changes `requirements.txt` or contents of `book/`
|
||||
- When first creating a repository, the action may not run, or may run and fail; occasionally it is needed to make a new commit to get the workflow to run for the first time (remember to modify something in `book/`) or you may try to re-run the job from the Actions tab
|
||||
- when using multiple branches, only the branch that is edited will be updated
|
||||
- the website for each branch may be built with a different Python environments (different package versions)
|
||||
|
||||
Unlike the virtual environments (next subsection), caches of the book build do not influence subsequent builds of the book, as this artifact is replaced whenever a commit to a specific branch triggers a new build process. As described above, old cached build artifacts are used if the build process from a new commit fails, ensuring that the URL of a website does not return a 404 page.
|
||||
|
||||
### Effect of Caching on Virtual Environment
|
||||
|
||||
In particular, note that older branches may have been built with cached environments that are different than those in a newer branch, leading to (undesired) differences in book appearance or functionality---often without the author being aware! This occurs if a package in `requirements.txt` is updated in the time between the creation of environments on different branches, as `pip` will use the newest version when downloading a package (the first time a venv cache is created in the DBW), but it will not always automatically update a package if `pip install -r requirements.txt` is used on an existing environment (this happens every time an existing cache is used!). This means that, when compared to the venv on a newer branch, a frequently used branch (where the cache has not expired) may retain old and out of date packages long after an updated version is available; however, since the week number is included in the venv file hash, this will last for a maximum of 1 week. A best practice to avoid this situation is to pin version numbers explicitly (e.g., `teachbooks==0.2.0`) if you want book builds to remain consistent. In addition, a feature like dependabot can be used to automatically notify you when an update is made; this is [here](./update_env.md).
|
||||
|
|
@ -1,80 +0,0 @@
|
|||
````{margin}
|
||||
```{attributiongrey} Attribution
|
||||
:class: attribution
|
||||
This page reuses MIT licensed content from {cite:t}`sphinx-proof`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
|
||||
```
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 3-5.
|
||||
```
|
||||
+++
|
||||
{bdg-primary}`Sphinx Extension`
|
||||
{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>`
|
||||
{bdg-link-primary-line}`Included in TeachBooks Favourites <./favourites.html>`
|
||||
````
|
||||
|
||||
# Sphinx proof
|
||||
|
||||
This extensions provides an easy way to add proofs, theorem, axioms and much more to your book. It is created by the Executable Books team and is [documented here](https://sphinx-proof.readthedocs.io/en/latest/).
|
||||
|
||||
TeachBooks has made some small modifications to the original extension, such that it works well with translated books; this modified version is located in the repository [github.com/TeachBooks/sphinx-proof](https://github.com/TeachBooks/sphinx-proof).
|
||||
|
||||
## What does it do?
|
||||
|
||||
This extension defines proofs, theorems, axioms and other similar concepts as new admonition types:
|
||||
|
||||
````{prf:example}
|
||||
:label: my-example
|
||||
|
||||
Next, we shut down randomness in demand and assume that the demand shock
|
||||
$\nu_t$ follows a deterministic path:
|
||||
|
||||
|
||||
```{math}
|
||||
\nu_t = \alpha + \rho \nu_{t-1}
|
||||
```
|
||||
|
||||
Again, we’ll compute and display outcomes in some figures
|
||||
|
||||
```python
|
||||
ex2 = SmoothingExample(C2=[[0], [0]])
|
||||
|
||||
x0 = [0, 1, 0]
|
||||
ex2.simulate(x0)
|
||||
```
|
||||
````
|
||||
|
||||
More information can be found in the [official documentation](https://sphinx-proof.readthedocs.io/en/latest/index.html). It can be [configured in combination the TeachBooks extension to include examples with executable code and visuals](../_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.ipynb).
|
||||
|
||||
## Installation
|
||||
To use this extenstion, follow these steps:
|
||||
|
||||
**Step 1: Install the Package**
|
||||
|
||||
Install the TeachBooks' version of `sphinx-exercise` package using `pip`:
|
||||
```
|
||||
pip install sphinx-proof @ git+https://github.com/TeachBooks/sphinx-proof.git
|
||||
```
|
||||
|
||||
**Step 2: Add to `requirements.txt`**
|
||||
|
||||
Make sure that the package is included in your project's `requirements.txt` to track the dependency:
|
||||
```
|
||||
sphinx-proof @ git+https://github.com/TeachBooks/sphinx-proof.git
|
||||
```
|
||||
|
||||
**Step 3: Enable in `_config.yml`**
|
||||
|
||||
In your `_config.yml` file, add the extension to the list of Sphinx extra extensions (**important**: underscore, not dash this time):
|
||||
```
|
||||
sphinx:
|
||||
extra_extensions:
|
||||
.
|
||||
.
|
||||
.
|
||||
- sphinx_proof
|
||||
.
|
||||
.
|
||||
.
|
||||
```
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
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 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.
|
||||
|
|
@ -1,11 +0,0 @@
|
|||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 1-5.
|
||||
```
|
||||
````
|
||||
|
||||
# TeachBooks Student-view Features
|
||||
|
||||
|
||||
This chapter includes some TeachBooks features which aim to improve the way students can use TeachBooks. These tools are fully student-side, they don't influence the book website and the author doesn't have to setup anything. Nevertheless, the author could point the students to the availability of these tools and use it as part of the didactical approach. These tools could also be useful for other users.
|
||||
18
book/features/teachbooks.md
Normal file
18
book/features/teachbooks.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
(teachbooks-package)=
|
||||
# TeachBooks: Our Custom Python Package
|
||||
|
||||
TeachBooks has created a Python package and released it on PyPI. It can easily be used like this:
|
||||
```
|
||||
pip install teachbooks
|
||||
```
|
||||
|
||||
The source code is hosted in a repository on GitHub, [github.com/teachBooks/teachbooks](https://github.com/teachBooks/teachbooks), and is accompanied by a documentation website, [teachbooks.github.io/TeachBooks/](https://teachbooks.github.io/TeachBooks/).
|
||||
|
||||
The features and documentation will increase with time; until then, note there are two important reasons to use the teachbooks package:
|
||||
1. Use the `REMOVE-FROM-PUBLISH` feature to more easily maintain draft and published versions of your TeachBook (see {ref}`this page <remove-from-publish>` for more details).
|
||||
2. Easily start and stop a local Python server to better test your book while writing (e.g., the interactive Python features require a local server to properly check certain TeachBooks features)
|
||||
|
||||
For case 1, the `teachbooks` package is meant to be used instead of `jupyter book build book` to build your book (it executes `jupyter book build book` for you).
|
||||
|
||||
Case 2 is meant to be used independently, for example, once you have successfully built a book, simply run `teachbooks serve` and open the resulting URL that is printed in the terminal. To stop the server use `teachbooks serve stop`; see {ref}`this page <setup-local-server>` for additional explanation for how to use this feature and why it is needed.
|
||||
|
||||
|
|
@ -1,50 +0,0 @@
|
|||
|
||||
````{margin}
|
||||
|
||||
```{note}
|
||||
|
||||
{bdg-link-secondary}`Python Package: TeachBooks`
|
||||
|
||||
{bdg-link-light}`Included in TeachBooks Template <../external/template/README.html>`
|
||||
|
||||
```
|
||||
|
||||
```{tip}
|
||||
This section is useful for user type 4-5.
|
||||
|
||||
```
|
||||
|
||||
```{seealso}
|
||||
|
||||
[{octicon}`mark-github` Repository](https://github.com/teachbooks/teachbooks)
|
||||
|
||||
[{octicon}`book` Documentation](https://teachbooks.readthedocs.io/)
|
||||
|
||||
```
|
||||
|
||||
````
|
||||
|
||||
(teachbooks_package)=
|
||||
# TeachBooks Python Package
|
||||
|
||||
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` 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:
|
||||
|
||||
```
|
||||
teachbooks build book
|
||||
```
|
||||
|
||||
This Manual describes the main features and usage of the package. For those who wish to understand more of hte technical details, note that the implementation the API is is documented at [teachbooks.readthedocs.io/](https://teachbooks.readthedocs.io/).
|
||||
|
||||
## List of Features
|
||||
|
||||
Items in the list here are currently implemented in the TeachBooks package and described on other pages of this manual:
|
||||
- [Draft-Release Workflow](./draft-release.md)
|
||||
- [External Contents](./external_toc.md)
|
||||
- [Local Server](./local_server.md)
|
||||
|
||||
The package is also set up to handle [APA references](./apa) when using the Draft-Release Workflow (the `_ext` subdirectory and its contents are manually copied during the pre-build phase). This will not be necessary once the APA Reference feature is turned into a proper Sphinx extension or Pybtext plugin.
|
||||
|
|
@ -1,65 +0,0 @@
|
|||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 4-5.
|
||||
```
|
||||
|
||||
{bdg-dark}`Git Workflow`
|
||||
````
|
||||
|
||||
# Auto-updating packages
|
||||
|
||||
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.
|
||||
|
||||
For the case of specified versions, you can use GitHub's Dependabot to notify you that a new version is available _and_ to automatically set up a Pull Request to update your book with the new version.
|
||||
|
||||
## Notifications updated packages with Dependabot
|
||||
|
||||
Dependabot checks the specified version of packages in your `requirements.txt` file and, if a new version is found, will create a new branch, update the `requirements.txt` file and open a Pull Request whenever there's an update available for that package. Note that packages without a fixed version are ignored by Dependabot.
|
||||
|
||||
To activate this feature:
|
||||
1. Specify version for all packages you want to be notified on in your `requirements.txt` file. See [`requirements.txt`](https://github.com/TeachBooks/manual/blob/release/requirements.txt) of this manual as an example
|
||||
1. In the `.github/` directory, add a file named `dependabot.yml` with the following content (note that sphinx-thebe (used in [python live coding](./live_code.ipynb)) and docutils (using in [APA referencing](./apa.md)) are ignored because these require a very specific version to work):
|
||||
|
||||
```yaml
|
||||
version: 2
|
||||
updates:
|
||||
- package-ecosystem: "pip"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "sunday"
|
||||
time: "22:59"
|
||||
ignore:
|
||||
- dependency-name: "sphinx-thebe"
|
||||
- dependency-name: "docutils"
|
||||
```
|
||||
|
||||
This check will run every Sunday around midnight (UTC) whether any of the fixed-version packages are updated. If so, several things will happen:
|
||||
1. A new branch is created with a name that begins with `dependabot...` in the repository
|
||||
1. A commit is made updating `requirements.txt` (e.g., `jupyterbook_patches==1.4.2` is changed to `jupyterbook_patches==1.4.4`)
|
||||
1. A _pull request_ will be created to merge the new branch into the _default_ branch. This pull request must be manually reviewed and merged. Afterwards the _dependabot_ branch can be deleted (automatically).
|
||||
|
||||
Note that these activities will occur automatically and may trigger other workflows in your repository (for example, the building of a book on another branch). If the workflow `call-deploy-book` is used, and you don't want the _dependabot_ branches to be built and deployed (and all other branches you do want), you can achieve this by adding the following text to the file `call-deploy-book.yml`:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- '**'
|
||||
- '!dependabot**'
|
||||
```
|
||||
|
||||
If you want another scheduled workflow, see [Dependabot options reference](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference#schedule-) for the options.
|
||||
|
||||
If you want to manually trigger the Dependabot workflow, you can do this by doing the next steps:
|
||||
|
||||
1. Go to your repository on [Github](https://github.com/).
|
||||
1. Choose **Insights**.
|
||||
1. Choose **Dependency graph**.
|
||||
1. Choose **Dependabot**.
|
||||
1. Choose **Recent update jobs** next to <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="none" role="img" aria-labelledby="a5ltiumrgcrur1ds9f7gmugoditp5omm" class="octicon" width="16" height="16"><title id="a5ltiumrgcrur1ds9f7gmugoditp5omm">pip</title><path d="M7.932.036c-4.052 0-3.799 1.757-3.799 1.757l.005 1.82h3.867v.547H2.602S.009 3.866.009 7.954c0 4.089 2.263 3.944 2.263 3.944h1.35V10S3.55 7.738 5.85 7.738h3.835s2.155.034 2.155-2.083v-3.5s.327-2.12-3.908-2.12zM5.8 1.26a.695.695 0 11.001 1.39.695.695 0 010-1.39z" fill="#387EB8"></path><path d="M8.047 15.914c4.052 0 3.8-1.757 3.8-1.757l-.005-1.82H7.975v-.547h5.403s2.592.294 2.592-3.795c0-4.088-2.263-3.943-2.263-3.943h-1.35v1.897s.073 2.263-2.227 2.263H6.295S4.14 8.177 4.14 10.295v3.5s-.327 2.12 3.907 2.12zm2.132-1.224a.695.695 0 110-1.39.695.695 0 010 1.39z" fill="#FFE052"></path></svg> `requirements.txt`.
|
||||
1. Choose **Check for updates**.
|
||||
|
|
@ -1,43 +0,0 @@
|
|||
````{margin}
|
||||
```{attributiongrey} Attribution
|
||||
:class: attribution
|
||||
This page reuses adapted CC BY 3.0 content from {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.<external_resources>````
|
||||
````
|
||||
|
||||
# TeachBooks Versioning
|
||||
|
||||
Inspired by versioning systems in software management (i.e. semantic and CalVer versioning) TeachBooks suggests a versioning guideline in which the version number tells the reader about the impact of the change. This might more suitable for your online books than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. We recommend TeachBooks versioning, which comes in two flavors:
|
||||
|
||||
1. `academic_year.additions.errata` versioning for books tailed-made for courses in which content is added / adapted during the course and might be restructured extensively every year while remaining to be available in the original form.
|
||||
2. `major.errata` versioning for books which are more stable over years, in which big changes are covered only by the version number.
|
||||
|
||||
We have come up with guidelines how to use the two TeachBooks-versioning options (adapted from {cite:p}`semver`):
|
||||
|
||||
`````{tab-set}
|
||||
````{tab-item} academic_year.additions.errata
|
||||
1. A normal version number MUST take the form `academic_year.additions.errata` where `academic_year` is the academic year in which the book is used, and `additions`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 2025.9.0 -> 2025.10.0 -> 2025.11.0
|
||||
2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.
|
||||
3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next errata or additions version.
|
||||
4. Additions version MUST be incremented if an addition is made to the book. It MUST be communicated in both the source code and in the book itself. It MAY include errata level changes. The errata version MUST be reset to 0 when the addition version is incremented.
|
||||
5. Academic year version MUST be incremented if a fresh book is started for which additions will follow later. It MUST be communicated in both the source code and in the book itself. Additions and errata versions MUST be reset to 0 when academic version is incremented.
|
||||
6. A pre-release version MAY be denoted by appending `.pre-release`. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is not complete.
|
||||
7. Precedence refers to how versions are compared to each other when ordered.
|
||||
1. Precedence MUST be calculated by separating the version into academic year, additions and errata identifiers in that order.
|
||||
2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Academic year, additions and errata versions are always compared numerically. Example: 2024.0.0 < 2025.0.0 < 2025.1.0 < 2025.1.1.
|
||||
8. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself.
|
||||
|
||||
An example can be seen in [the source repository of the Engineering Systems Optimization book](https://github.com/TUDelft-books/CME4501/tags) showing tags for different versions.
|
||||
````
|
||||
````{tab-item} major.errata
|
||||
1. A normal version number MUST take the form `major.errata` where `major`, and `errata` are non-negative integers, and MUST NOT contain leading zeroes. Each element MUST increase numerically. For instance: 9.0 -> 10.0 -> 11.0
|
||||
2. Once a versioned book has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version.
|
||||
3. Errata versions MUST be incremented if a small change is made which should be communicated to the reader in both the source code and in the book itself. If the small change is not crucial (like a simple typo), you might consider not defining it as a new version but combining it with other changes in the next major version.
|
||||
5. Major versions MUST be incremented if a substantial restructure or additions is made. It MUST be communicated in both the source code and in the book itself. Errata versions MUST be reset to 0 when the major version is incremented.
|
||||
6. Precedence refers to how versions are compared to each other when ordered.
|
||||
1. Precedence MUST be calculated by separating the version into major and errata identifiers in that order.
|
||||
2. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: major and errata versions are always compared numerically. Example: 1.0 < 2.0 < 2.1.
|
||||
7. The way in which the version number is incremented after the initial release should be explained in the README of the source code and in the book itself.
|
||||
````
|
||||
`````
|
||||
|
||||
Read [](../installation-and-setup/versioning_changelog.md) on how to combine this with a changelog, tags and releases!
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 1-5.
|
||||
```
|
||||
````
|
||||
|
||||
# Book styling
|
||||
|
||||
TeachBooks developed a few improvements of the book which improve the visual book styling.
|
||||
|
|
@ -6,7 +6,7 @@
|
|||
"source": [
|
||||
"# Ipywidgets\n",
|
||||
"\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",
|
||||
"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](interactive_element).\n",
|
||||
"\n",
|
||||
"## `matplotlib` widgets\n",
|
||||
"When you'd like to use `ipywidgets` in combinations with a `matplotlib` figure, import the following packages:\n",
|
||||
|
|
@ -40,24 +40,7 @@
|
|||
"```python\n",
|
||||
"input_slider = widgets.FloatSlider(value=0, min=0, max=10, step=1, description='Input variable:') # Defines a widget, more options than just FloatSlider\n",
|
||||
"widgets.interact(update_plot, input_variable_from_widget = input_slider);\n",
|
||||
"```\n",
|
||||
"\n",
|
||||
"Finally, When using `%matplotlib widget`, there's the following toolbar:\n",
|
||||
"\n",
|
||||
"\n",
|
||||
"\n",
|
||||
"Which only shows up when you hoover above. If you want to disable the toolbar you can use:\n",
|
||||
"```python\n",
|
||||
"fig = plt.gcf()\n",
|
||||
"fig.canvas.toolbar_visible = False\n",
|
||||
"```\n",
|
||||
"\n",
|
||||
"If you want it to be visible even if you don't hoover above it, use:\n",
|
||||
"\n",
|
||||
"```python\n",
|
||||
"fig = plt.gcf()\n",
|
||||
"fig.canvas.toolbar_visible = True\n",
|
||||
"```"
|
||||
"```\n"
|
||||
]
|
||||
},
|
||||
{
|
||||
|
|
@ -221,7 +204,7 @@
|
|||
"metadata": {
|
||||
"celltoolbar": "Tags",
|
||||
"kernelspec": {
|
||||
"display_name": "base",
|
||||
"display_name": "Python 3 (ipykernel)",
|
||||
"language": "python",
|
||||
"name": "python3"
|
||||
},
|
||||
|
|
@ -235,7 +218,7 @@
|
|||
"name": "python",
|
||||
"nbconvert_exporter": "python",
|
||||
"pygments_lexer": "ipython3",
|
||||
"version": "3.12.11"
|
||||
"version": "3.11.5"
|
||||
}
|
||||
},
|
||||
"nbformat": 4,
|
||||
|
|
|
|||
|
|
@ -1,82 +0,0 @@
|
|||
````{margin}
|
||||
|
||||
```{note}
|
||||
|
||||
{bdg-link-light}`Uses Deploy Book workflow <../external/deploy-book-workflow/README.html>`
|
||||
|
||||
{bdg-link-light}`Uses TeachBooks Template <../external/template/README.html>`
|
||||
|
||||
```
|
||||
|
||||
```{tip}
|
||||
This section is useful for user type 3-5.
|
||||
```
|
||||
|
||||
```{seealso}
|
||||
|
||||
[{octicon}`mark-github` Repository deploy book workflow](https://github.com/TeachBooks/deploy-book-workflow)
|
||||
|
||||
[{octicon}`mark-github` Repository template](https://github.com/TeachBooks/template)
|
||||
|
||||
[{octicon}`book` Collaborative book-editing](../workflows/collaboration.md)
|
||||
|
||||
{octicon}`pencil` Exercises:
|
||||
- [First file edit](https://teachbooks.io/template/exercises/001.html)
|
||||
- [Add a new file to the table of contents](https://teachbooks.io/template/exercises/002.html)
|
||||
- [Change book configuration](https://teachbooks.io/template/exercises/003.html)
|
||||
- [Syntax exercises](https://teachbooks.io/template/syntax_exercises.html)
|
||||
```
|
||||
|
||||
````
|
||||
|
||||
|
||||
# Write book fully in GitHub interface
|
||||
|
||||
Using the GitHub tooling in combination with TeachBook's software, users are able to write their book fully online, without the need to install any software locally. This is especially useful for users that are not familiar with Git and GitHub, or do not have the rights to install software on their computer. To make this possible, users can start with the [TeachBooks Template](../external/template/README.md) after which they make use of the [Deploy Book Workflow](../external/deploy-book-workflow/README.md) to automatically build and release their book online.
|
||||
|
||||
## How to do this
|
||||
|
||||
New users can start writing their book by following the steps shown in the [TeachBooks Template repository](https://github.com/TeachBooks/template).
|
||||
|
||||
Users who already have a TeachBook repository can add the Deploy Book Workflow as explained [here](./release_book_online.md).
|
||||
|
||||
After that, users can start writing and editing their book fully online in the GitHub interface. This is supported with:
|
||||
- Automatic book builds for all version. See [](./release_book_online.md) for more information
|
||||
- A summary describing where the TeachBook is released, errors in the build process per branch and how the release step is configured
|
||||
|
||||
## Example of summary
|
||||
|
||||
Whenever the workflow is triggered, its progress and a summary can be seen under the <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-play UnderlineNav-octicon d-none d-sm-inline"> <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path></svg>`Actions`- `All workflows` - `call-deploy-book` in GitHub! It shows you a descriptive summary. This summary includes, among others, the errors in the build process per branch and where the book is released online.
|
||||
|
||||
Here's an example for a summary for the template book:
|
||||
|
||||
> ### Branches deployed
|
||||
> | Branch 🎋 | Link 🔗 | Build status ☑️ |
|
||||
> | :--- | :--- | :--- |
|
||||
> | main | [https://teachbooks.github.io/template/main](https://teachbooks.github.io/template/main) | ✅ `Released` |
|
||||
> | version2 | [https://teachbooks.github.io/template/version2](https://teachbooks.github.io/template/version2) | 🔴 `Build failed [1]` |
|
||||
> | version3 | [https://teachbooks.github.io/template/version3](https://teachbooks.github.io/template/version3) | ⭕ `Build failed [2]` |
|
||||
>
|
||||
> #### Legend for build status
|
||||
> ✅ `Released` - build success, new version released.
|
||||
>
|
||||
> 🔴 `Build failed [1]` - build failure, previous version of the book reused.
|
||||
>
|
||||
> ⭕ `Build failed [2]` - build failure, no previous version reused.
|
||||
>
|
||||
> ### Preview of build errors & warnings
|
||||
> For more details please see the corresponding `build-books` jobs in the left pane.
|
||||
>
|
||||
> On branch `version2`:
|
||||
> ```
|
||||
> <20>[91m/home/runner/work/template/template/book/some_content/overview.md:5: WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]<5D>[39;49;00m
|
||||
> ```
|
||||
>
|
||||
> On branch `version3`:
|
||||
> ```
|
||||
> /home/runner/work/_temp/ff8c8325-8d8b-4c0b-a2b2-32d2169c55bc.sh: line 8: teachbooks: command not found
|
||||
> ```
|
||||
>
|
||||
|
||||
## Exercise
|
||||
Check out [the exercises](https://teachbooks.io/template/exercises.html) in the TeachBooks template to see for yourself how you can write and edit your book fully online in GitHub!
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
(tex_md_converter)=
|
||||
# Convert LaTeX to Markdown
|
||||
|
||||
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).
|
||||
|
||||
Depending on the number of custom LaTeX commands used in your book, you may need to adjust the script to handle them.
|
||||
|
||||
Additional information about the script, along with the source code itself which is distributed under a [BSD 3-clause license](https://opensource.org/license/BSD-3-Clause), is available at the following link on TU Delft GitLab: [gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion](https://gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion).
|
||||
|
|
@ -1,8 +1,7 @@
|
|||
# Scripts for automating workflow
|
||||
|
||||
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 TeachBook compatible markdown.
|
||||
This chapter contains a few scripts which can be useful in the book-editing process:
|
||||
- [LaTeX to markdown conversion](../external/latex-to-markdown-conversion/README.md) to convert a LaTeX file into jupyter-book 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
|
||||
|
|
|
|||
|
|
@ -1,3 +0,0 @@
|
|||
# Move images to separate hosting
|
||||
|
||||
Storing big binary files like images in your git repository and book is not good practice: diffs on binary files don't make sense and blow up the size of your repository. Furthermore, the size of your book website blows up too. Therefore, you can consider hosting your binary files on a different server, as explained [here in an example for the MUDE-book](https://tudelft-mude.github.io/teacher/FTP.html). To take all the images of your existing book and update the relative links, [a Python script](./parse_images.py) has been developed. This script processes Markdown (`.md`) and Jupyter Notebook (`.ipynb`) files listed in a `_toc.yml` file. It identifies local image references (including MyST `figure` syntax) in these files, copies the images to a specified folder (`new_images`), and replaces the local image paths with a public URL (e.g., `https://files.mude.citg.tudelft.nl/<image_name>`).
|
||||
|
|
@ -1,207 +0,0 @@
|
|||
"""
|
||||
Script: parse_images.py
|
||||
|
||||
Description:
|
||||
This script processes Markdown (.md) and Jupyter Notebook (.ipynb) files listed in a `_toc.yml` file.
|
||||
It identifies local image references (including MyST `figure` syntax) in these files, copies the images
|
||||
to a specified folder (`new_images`), and replaces the local image paths with a public URL
|
||||
(e.g., `https://files.mude.citg.tudelft.nl/<image_name>`).
|
||||
|
||||
Key Features:
|
||||
- Parses `_toc.yml` to extract all Markdown and Notebook files.
|
||||
- Detects image references in Markdown files (e.g., ``).
|
||||
- Detects MyST `figure` syntax (e.g., `{figure} /path/to/image.png`).
|
||||
- Resolves image paths relative to the file or project root.
|
||||
- Handles image paths with optional titles (e.g., `"title"`) in Markdown and Notebook files.
|
||||
- Skips processing images that are already converted to the public URL.
|
||||
- Copies images to the `new_images` folder.
|
||||
- Updates the files to replace local image paths with public URLs.
|
||||
|
||||
How to Use:
|
||||
1. Place this script in the root directory of your project (where `_toc.yml` is located).
|
||||
2. Ensure `_toc.yml` contains the list of files to process.
|
||||
3. Run the script using Python: python parse_images.py
|
||||
4. The script will:
|
||||
- Copy referenced images to the `new_images` folder.
|
||||
- Update the Markdown and Notebook files with the new image URLs.
|
||||
|
||||
Dependencies:
|
||||
- Python 3.x
|
||||
- PyYAML (install using `pip install pyyaml`)
|
||||
|
||||
Notes:
|
||||
- Ensure the script is run from the project root directory.
|
||||
- The `base_url` variable should be updated to match your desired public URL prefix.
|
||||
- The script handles image paths in the following formats:
|
||||
- Relative paths (e.g., `image.png`, `./image.png`).
|
||||
- Absolute paths (e.g., `/path/to/image.png`).
|
||||
- Paths with optional titles (e.g., ``).
|
||||
"""
|
||||
|
||||
import os
|
||||
import re
|
||||
import shutil
|
||||
import yaml
|
||||
import json
|
||||
|
||||
# Define the folder where images will be copied
|
||||
output_folder = "new_images"
|
||||
base_url = "https://files.mude.citg.tudelft.nl/"
|
||||
|
||||
# Ensure the output folder exists
|
||||
os.makedirs(output_folder, exist_ok=True)
|
||||
|
||||
# Function to parse the _toc.yml file and extract all Markdown and Notebook files
|
||||
def get_files_from_toc(toc_file):
|
||||
files = []
|
||||
with open(toc_file, "r", encoding="utf-8") as f:
|
||||
toc = yaml.safe_load(f)
|
||||
|
||||
# Recursive function to extract file paths
|
||||
def extract_files(item):
|
||||
if isinstance(item, dict):
|
||||
if "file" in item:
|
||||
# Add the file with the appropriate extension
|
||||
file_path = item["file"]
|
||||
if not file_path.endswith((".md", ".ipynb")):
|
||||
if os.path.isfile(file_path + ".md"):
|
||||
file_path += ".md"
|
||||
elif os.path.isfile(file_path + ".ipynb"):
|
||||
file_path += ".ipynb"
|
||||
files.append(file_path)
|
||||
if "sections" in item:
|
||||
for section in item["sections"]:
|
||||
extract_files(section)
|
||||
if "chapters" in item:
|
||||
for chapter in item["chapters"]:
|
||||
extract_files(chapter)
|
||||
elif isinstance(item, list):
|
||||
for sub_item in item:
|
||||
extract_files(sub_item)
|
||||
|
||||
# Start extracting files from the "parts" section
|
||||
extract_files(toc.get("parts", []))
|
||||
return files
|
||||
|
||||
# Function to normalize image paths
|
||||
def normalize_image_path(file_dir, image_path):
|
||||
# Check if the path starts with a `/` (absolute path relative to the project root)
|
||||
if image_path.startswith("/"):
|
||||
# Resolve the path relative to the project root
|
||||
project_root = os.getcwd() # Assuming the script is run from the project root
|
||||
resolved_path = os.path.join(project_root, image_path.lstrip("/"))
|
||||
else:
|
||||
# Resolve the path relative to the file's directory
|
||||
resolved_path = os.path.normpath(os.path.join(file_dir, image_path))
|
||||
return resolved_path
|
||||
|
||||
# Function to find and replace local image references
|
||||
def process_file(file_path):
|
||||
if file_path.endswith(".md"):
|
||||
process_markdown(file_path)
|
||||
elif file_path.endswith(".ipynb"):
|
||||
process_notebook(file_path)
|
||||
|
||||
# Process Markdown files
|
||||
def process_markdown(file_path):
|
||||
file_dir = os.path.dirname(file_path) # Get the directory of the file
|
||||
with open(file_path, "r", encoding="utf-8") as f:
|
||||
content = f.read()
|
||||
|
||||
# Find all standard Markdown image references (e.g., )
|
||||
matches = re.findall(r"!\[.*?\]\((.*?)(?:\s+\".*?\")?\)", content)
|
||||
# Find all MyST figure syntax references (e.g., {figure} path)
|
||||
# Handles cases where the `---` block is missing or caption follows directly
|
||||
myst_matches = re.findall(r"\{figure\}\s+(.*?)\s*(?:\n|$)", content)
|
||||
matches.extend(myst_matches)
|
||||
|
||||
for match in matches:
|
||||
# Skip if the image path is already converted to the public URL
|
||||
if match.startswith(base_url):
|
||||
continue
|
||||
|
||||
# Normalize and resolve the image path
|
||||
image_path = normalize_image_path(file_dir, match)
|
||||
|
||||
if os.path.isfile(image_path):
|
||||
print(f"Image found: {image_path}") # Debugging output
|
||||
# Copy the image to the output folder
|
||||
image_name = os.path.basename(image_path)
|
||||
new_path = os.path.join(output_folder, image_name)
|
||||
shutil.copy(image_path, new_path)
|
||||
|
||||
# Replace the local URL with the new URL
|
||||
new_url = base_url + image_name
|
||||
content = content.replace(match, new_url)
|
||||
else:
|
||||
print(f"Warning: Image not found: {image_path}") # Debugging output
|
||||
|
||||
# Write the updated content back to the file
|
||||
with open(file_path, "w", encoding="utf-8") as f:
|
||||
f.write(content)
|
||||
|
||||
# Process Jupyter Notebook files
|
||||
def process_notebook(file_path):
|
||||
file_dir = os.path.dirname(file_path) # Get the directory of the file
|
||||
with open(file_path, "r", encoding="utf-8") as f:
|
||||
notebook = json.load(f)
|
||||
|
||||
updated = False
|
||||
for cell in notebook.get("cells", []):
|
||||
if cell.get("cell_type") == "markdown":
|
||||
# Join all lines in the cell into a single string
|
||||
cell_content = "".join(cell.get("source", []))
|
||||
|
||||
# Find all standard Markdown image references (e.g., )
|
||||
matches = re.findall(r"!\[.*?\]\((.*?)(?:\s+\".*?\")?\)", cell_content)
|
||||
# Find all MyST figure syntax references (e.g., {figure} path)
|
||||
myst_matches = re.findall(r"\{figure\}\s+(.*?)\s*(?:\n|$)", cell_content)
|
||||
matches.extend(myst_matches)
|
||||
|
||||
for match in matches:
|
||||
# Skip if the image path is already converted to the public URL
|
||||
if match.startswith(base_url):
|
||||
continue
|
||||
|
||||
# Normalize and resolve the image path
|
||||
image_path = normalize_image_path(file_dir, match)
|
||||
|
||||
if os.path.isfile(image_path):
|
||||
print(f"Image found: {image_path}") # Debugging output
|
||||
# Copy the image to the output folder
|
||||
image_name = os.path.basename(image_path)
|
||||
new_path = os.path.join(output_folder, image_name)
|
||||
shutil.copy(image_path, new_path)
|
||||
|
||||
# Replace the local URL with the new URL
|
||||
new_url = base_url + image_name
|
||||
cell_content = cell_content.replace(match, new_url)
|
||||
updated = True
|
||||
else:
|
||||
print(f"Warning: Image not found: {image_path}") # Debugging output
|
||||
|
||||
# Split the updated content back into lines and update the cell
|
||||
cell["source"] = cell_content.splitlines(keepends=True)
|
||||
|
||||
# Write the updated notebook back to the file if changes were made
|
||||
if updated:
|
||||
with open(file_path, "w", encoding="utf-8") as f:
|
||||
json.dump(notebook, f, indent=2)
|
||||
|
||||
# Main function
|
||||
def main():
|
||||
toc_file = "_toc.yml" # Replace with the path to your _toc.yml file
|
||||
files = get_files_from_toc(toc_file)
|
||||
|
||||
print("Files extracted from TOC:", files) # Debugging output
|
||||
|
||||
for file_path in files:
|
||||
# Ensure the file has the correct extension and exists
|
||||
if os.path.isfile(file_path):
|
||||
print(f"Processing file: {file_path}") # Debugging output
|
||||
process_file(file_path)
|
||||
else:
|
||||
print(f"Warning: File {file_path} not found or unsupported.")
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 544 KiB After Width: | Height: | Size: 975 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 158 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 368 KiB |
Some files were not shown because too many files have changed in this diff Show more
Loading…
Add table
Add a link
Reference in a new issue