mirror of
https://github.com/TeachBooks/template.git
synced 2026-11-12 22:25:52 +00:00
merge from main
This commit is contained in:
Tom van Woudenberg
commit
1064963a93
29 changed files with 1048 additions and 99 deletions
2
.github/workflows/call-deploy-book.yml
vendored
2
.github/workflows/call-deploy-book.yml
vendored
|
|
@ -16,7 +16,7 @@ on:
|
|||
|
||||
jobs:
|
||||
call-workflow:
|
||||
uses: TeachBooks/deploy-book-workflow/.github/workflows/deploy-book.yml@main
|
||||
uses: TeachBooks/deploy-book-workflow/.github/workflows/deploy-book.yml@v1
|
||||
secrets: inherit
|
||||
permissions:
|
||||
contents: read
|
||||
|
|
|
|||
23
.gitignore
vendored
23
.gitignore
vendored
|
|
@ -3,29 +3,8 @@ __pycache__/
|
|||
*.py[cod]
|
||||
*$py.class
|
||||
|
||||
# C extensions
|
||||
*.so
|
||||
|
||||
# Distribution / packaging
|
||||
# Python
|
||||
.Python
|
||||
build/
|
||||
develop-eggs/
|
||||
dist/
|
||||
downloads/
|
||||
eggs/
|
||||
.eggs/
|
||||
lib/
|
||||
lib64/
|
||||
parts/
|
||||
sdist/
|
||||
var/
|
||||
wheels/
|
||||
pip-wheel-metadata/
|
||||
share/python-wheels/
|
||||
*.egg-info/
|
||||
.installed.cfg
|
||||
*.egg
|
||||
MANIFEST
|
||||
.vscode/
|
||||
|
||||
# PyInstaller
|
||||
|
|
|
|||
2
CODEOWNERS
Normal file
2
CODEOWNERS
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
# All files in the repo
|
||||
* @Tom-van-Woudenberg
|
||||
22
CODE_OF_CONDUCT.md
Normal file
22
CODE_OF_CONDUCT.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
# Contributor Code of Conduct
|
||||
|
||||
As contributors and maintainers of this book, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, updating content, submitting pull requests or patches, and other activities.
|
||||
|
||||
We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.
|
||||
|
||||
Examples of unacceptable behavior by participants include:
|
||||
|
||||
- The use of sexualized language or imagery
|
||||
- Personal attacks
|
||||
- Trolling or insulting/derogatory comments
|
||||
- Public or private harassment
|
||||
- Publishing other’s private information, such as physical or electronic addresses, without explicit permission
|
||||
- Other unethical or unprofessional conduct
|
||||
|
||||
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, issues, and other contributions that are not aligned to this Code of Conduct. By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.
|
||||
|
||||
This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 1.2.0, available at [https://www.contributor-covenant.org/version/1/2/0/code-of-conduct.html](https://www.contributor-covenant.org/version/1/2/0/code-of-conduct.html)
|
||||
|
|
@ -66,7 +66,7 @@ Demonstration for a public repository, video available [here](https://youtu.be/n
|
|||
:name: activate_pages
|
||||
```
|
||||
|
||||
5. Make an edit to the TeachBook by editing and committing changes to one of the files in the `book/` subdirectory (available under {octicon}`code;1em` `Code`). Now checkout the progress of the publishing workflow under {octicon}`play;1em``Actions` - `All workflows` - `call-deploy-book` -`<the most recent workflow run>`. Remember, the first commit which is there has failed because GitHub Pages wasn't activated at the time of `Initial commit`, you could also re-run that job if you don't want to make an edit. You can do so by running the workflow from {octicon}`play;1em``Actions` - `All workflows` - `call-deploy-book` - {octicon}`x-circle-fill;1em` `Initial commit` - {octicon}`sync;1em` `Re-run all jobs` - `Re-run jobs`:
|
||||
5. Now checkout the progress of the publishing workflow under {octicon}`play;1em``Actions` - `All workflows` - `call-deploy-book` -`<the most recent workflow run>`. Thee first commit which is there has failed because GitHub Pages wasn't activated at the time of `Initial commit`. Re-run that job from {octicon}`play;1em``Actions` - `All workflows` - `call-deploy-book` - {octicon}`x-circle-fill;1em` `Initial commit` - {octicon}`sync;1em` `Re-run all jobs` - `Re-run jobs`:
|
||||
|
||||
```{figure} https://github.com/TeachBooks/template_figures/blob/main/action_re-run.jpeg?raw=true
|
||||
:name: action
|
||||
|
|
|
|||
129
book/_config.yml
129
book/_config.yml
|
|
@ -1,52 +1,111 @@
|
|||
title: TeachBooks template # Replace this with your own book title
|
||||
# This config includes all the recommended (default) configuration options of the TeachBooks software, and a TeachBooks' selection of configuration options as provided by Jupyter Book for Jupyter Book software and Sphinx.
|
||||
|
||||
author: TeachBooks Team, 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>
|
||||
# Replace TeachBooks Teams with your own name in the line above
|
||||
|
||||
# Replace TeachBooks Teams with your own name in the line above, configuratin part of JupyterBook: https://jupyterbook.org/en/stable/customize/config.html
|
||||
execute:
|
||||
execute_notebooks: "off" # Replace this if you want don't have notebooks with output and you want to add notebook output during build
|
||||
|
||||
only_build_toc_files: true # Replace this with false if you want to build all files in the book, allowing you to refer to pages which are not included in the table of contents
|
||||
|
||||
execute_notebooks: "off" # Replace this if you want don't have notebooks with output and you want to add notebook output during build, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html)
|
||||
cache: "_build/.jupyter_cache/" # Default value (line can be removed), sets path to the jupyter cache that will be used to store execution artifacts, doesn't work in GitHub workflow, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html)
|
||||
exclude_patterns: [] # Default value (line can be removed), sets a list of patterns to *skip* in execution, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html), can overwritten by Sphinx-NB-Execution-Patterns (https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html)
|
||||
timeout: 30 # Default value (line can be removed), sets he maximum time (in seconds) each notebook cell is allowed to run, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html)
|
||||
run_in_temp: false # Default value (line can be removed), disables a temporary directory was the command working directory (cwd), configuration part Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html)
|
||||
allow_errors: false # Default value (line can be removed), all cells are always run, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html)
|
||||
stderr_output: show # Default value (line can be removed), shows stderr output, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html)
|
||||
|
||||
html:
|
||||
favicon : "figures/TB_favicon.ico" # Replace this with your own favicon
|
||||
baseurl : "https://<user/org>.io/<repo>" # Replace this with your own URL
|
||||
use_multitoc_numbering : true # Default value (line can be removed), sets continuous numbering across parts/chapters, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html). Same functionality per section can be defined with sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html)
|
||||
extra_footer : "" # Default value (line can be removed), sets text to be displayed underneath the footer, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html)
|
||||
|
||||
sphinx: # Options passed on to the underlying sphinx-parser
|
||||
extra_extensions: # Sets a list of extensions to load by sphinx, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html)
|
||||
- teachbooks_favourites # Gives you a starter package of extensions to use in your book, replace with individual extensions if you prefer some extensions not to be included (https://github.com/TeachBooks/TeachBooks-Favourites)
|
||||
local_extension: null # Sets a a list of local extensions to load by sphinx, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html)
|
||||
config:
|
||||
language: en # Defines language (English) of everything except the content itself. For Dutch: replace with `nl`, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html)
|
||||
html_js_files:
|
||||
- https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js # Required for live code: https://teachbooks.io/manual/features/live_code.html
|
||||
- https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js # Required for live code, part of TeachBooks-Sphinx-Thebe (https://teachbooks.io/manual/features/live_code.html)
|
||||
thebe_config:
|
||||
use_thebe_lite: true # Required for live code: https://teachbooks.io/manual/features/live_code.html
|
||||
exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"] #exclude files which should not be accessible for live code: https://teachbooks.io/manual/features/live_code.html
|
||||
use_thebe_lite: true # Required for live code, part of TeachBooks-Sphinx-Thebe (https://teachbooks.io/manual/features/live_code.html)
|
||||
exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"] #exclude files which should not be accessible for live code, configuration part of TeachBooks-Sphinx-Thebe (https://teachbooks.io/manual/features/live_code.html)
|
||||
html_favicon: "figures/TB_favicon.ico" # Replace this with your own favicon, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html)
|
||||
html_baseurl: "https://<user/org>.io/<repo>" # Replace this with your own URL, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html)
|
||||
html_theme_options:
|
||||
logo:
|
||||
text: Template # Replace this with your own book title
|
||||
image_light: TeachBooks_logo.svg # Put your logo for the light mode here (can be the same as image_dark)
|
||||
image_dark: TeachBooks_logo_inverted.svg # Put your logo for the dark mode here (can be the same as image_light)
|
||||
repository_url: "https://github.com/user/repo" # Add your own repo URL here
|
||||
path_to_docs: "book" # Required for edit_page_button, should be book if you're using TeachBooks package (https://github.com/TeachBooks/TeachBooks) or the TeachBooks deploy book workflow (https://teachbooks.io/manual/external/deploy-book-workflow/README.html)
|
||||
repository_branch: "main" # Replace when you change the name of your published branch (required for edit_page_button)
|
||||
use_edit_page_button: true # Replace with false if you don't want the edit page button (i.e. if you don't user to propose changes themselves or have a private repo)
|
||||
use_repository_button: true # Replace with false if you don't want the repository button (i.e. if you have a private repo)
|
||||
use_issues_button : true # Replace with false if you don't want the issues button (i.e. if you don't want to use GitHub issues or have a private repo)
|
||||
text: Template # Replace this with your own book title, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html)
|
||||
image_light: TeachBooks_logo.svg # Put your logo for the light mode here (can be the same as image_dark), configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html)
|
||||
image_dark: TeachBooks_logo_inverted.svg # Put your logo for the dark mode here (can be the same as image_light), configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html)
|
||||
repository_url: "https://github.com/user/repo" # Add your own repo URL here, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html)
|
||||
path_to_docs: "book" # Required for edit_page_button, should be book if you're using TeachBooks package (https://github.com/TeachBooks/TeachBooks) or the TeachBooks deploy book workflow (https://teachbooks.io/manual/external/deploy-book-workflow/README.html), configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html)
|
||||
repository_branch: "main" # Replace when you change the name of your published branch (required for edit_page_button), configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html)
|
||||
use_edit_page_button: true # Replace with false if you don't want the edit page button (i.e. if you don't user to propose changes themselves or have a private repo), configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html)
|
||||
use_repository_button: true # Replace with false if you don't want the repository button (i.e. if you have a private repo), configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html)
|
||||
use_issues_button : true # Replace with false if you don't want the issues button (i.e. if you don't want to use GitHub issues or have a private repo), configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html)
|
||||
launch_buttons:
|
||||
thebe: true # Required for live code: https://teachbooks.io/manual/features/live_code.html
|
||||
html_show_copyright: false # As the copyright is included in the author field
|
||||
html_last_updated_fmt: '%B %-d, %Y' # Adds the date of the last update to the footer
|
||||
html_static_path: ["figures"] # Add folder that contain files that need to be included, such as the location of the logo(s)
|
||||
thebe: true # Required for live code, part of TeachBooks-Sphinx-Thebe (https://teachbooks.io/manual/features/live_code.html)
|
||||
announcement: "" # Default value (line can be removed), sets a banner announcement at the top of the site, configuration part of Jupyter Book (https://jupyterbook.org/en/stable/customize/config.html)
|
||||
html_show_copyright: false # As the copyright is included in the author field, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html)
|
||||
html_last_updated_fmt: '%B %-d, %Y' # Adds the date of the last update to the footer, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html)
|
||||
html_static_path: ["figures"] # Add folder that contain files that need to be included, such as the location of the logo(s), configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html)
|
||||
mathjax3_config:
|
||||
chtml: {
|
||||
mtextInheritFont: true # To typeset text within math prettier
|
||||
mtextInheritFont: true # To typeset text within math prettier, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html)
|
||||
}
|
||||
extra_extensions: # Gives you a starter package of extensions to use in your book
|
||||
- jupyterbook_patches # Patches by TeachBooks https://github.com/TeachBooks/JupyterBook-Patches
|
||||
- download_link_replacer # Allows you to replace and add downloadable files to a page header https://teachbooks.io/manual/external/Download-Link-Replacer/README.html
|
||||
- sphinx_image_inverter # Inverts images for dark mode https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html
|
||||
- sphinx_iframes # Eases the embedding of iframes https://teachbooks.io/manual/external/sphinx-iframes/README.html
|
||||
- sphinx_exercise # Allows you to add exercise boxes to your book https://ebp-sphinx-exercise.readthedocs.io/en/latest/
|
||||
- teachbooks_sphinx_tippy # Enables hoover over tips https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html
|
||||
- sphinx_named_colors # Allows you to use custom colors in your book https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html
|
||||
keep_warnings: false # Default value (line can be removed), disables showing warnings in the book, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-keep_warnings)
|
||||
external_toc_exclude_missing: true # Replace this with false if you want to build all files in the book, allowing you to refer to pages which are not included in the table of contents, configuration part of jupyterbook, configuration part of sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html)
|
||||
external_toc_path: "_toc.yml" # Default value (line can be removed), sets path to the table of contents file, configuration part of sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html)
|
||||
patch_config:
|
||||
disabled-patches: [] # Default value (line can be removed), disables specific patches, configuration part of JupyterBook-Patches (https://teachbooks.io/manual/external/JupyterBook-Patches/README.html)
|
||||
inverter_all: true # Default value (line can be removed), inverts all figures, configuration part of Sphinx-Image-Inverter (https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html)
|
||||
inverter_saturation: 1.5 # Default value (line can be removed), sets saturation of figures in dark mode to 1.5, configuration part of Sphinx-Image-Inverter (https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html)
|
||||
iframe_blend: true # Default value (line can be removed), blends all iframes with the background and in dark-mode also inverted., configuration part of Sphinx-Iframes (https://teachbooks.io/manual/external/sphinx-iframes/README.html)
|
||||
iframe_saturation: 1.5 # Default value (line can be removed), sets saturation of iframes in dark mode to 1.5, configuration part of Sphinx-Iframes (https://teachbooks.io/manual/external/sphinx-iframes/README.html)
|
||||
iframe_h5p_autoresize: true # Default value (line can be removed), automagically resized all h5p elements to fit the element in which the iframe is loadeds, configuration part of Sphinx-Iframes (https://teachbooks.io/manual/external/sphinx-iframes/README.html)
|
||||
iframe_background: "#ffffff" # Default value (line can be removed), sets the standard background color of non-blended iframes to white, configuration part of Sphinx-Iframes (https://teachbooks.io/manual/external/sphinx-iframes/README.html)
|
||||
iframe_width: calc(100% - 2.8rem) # Default value (line can be removed), sets the standard width of the iframe within the parent element, configuration part of Sphinx-Iframes (https://teachbooks.io/manual/external/sphinx-iframes/README.html)
|
||||
iframe_aspectratio: auto 2 / 1 # Default value (line can be removed), sets the standard aspect ration of the iframe within the parent element, configuration part of Sphinx-Iframes (https://teachbooks.io/manual/external/sphinx-iframes/README.html)
|
||||
hide_solutions: false # Default value (line can be removed), does not hide all solutions from exercises, configuration part of Sphinx-Exercise (https://ebp-sphinx-exercise.readthedocs.io/en/latest/syntax.html)
|
||||
named_colors_include_CSS: true # Default value (line can be removed), includes all CSS colours, configuration part of Sphinx-Named-Colors (https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html)
|
||||
named_colors_dark_and_light: true # Default value (line can be removed), creates dark mode colours for CSS and custom named colours, configuration part of Sphinx-Named-Colors (https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html)
|
||||
named_colors_saturation: 1.5 # Default value (line can be removed), sets saturation of CSS and custom named colours in dark mode to 1.5, configuration part of Sphinx-Named-Colors (https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html)
|
||||
named_colors_custom_colors: null # Default value (line can be removed), defines no custom named colours (include no colour for attribution admonition of external pages), configuration part of Sphinx-Named-Colors (https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html)
|
||||
proof_minimal_theme: false # Default value (line can be removed), uses default color scheme for admonitions part of sphinx-proof, configuration part of Sphinx-Proof (https://sphinx-proof.readthedocs.io/en/latest/options.html)
|
||||
sphinx_codex_name: "" # Default value (line can be removed), uses default 'Code example' as title for codex directives, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html)
|
||||
sphinx_codex_style_from_proof: true # Default value (line can be removed), the CSS color style of the codex directive will be taken from the prf:example directive from the sphinx-proof extension, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html)
|
||||
sphinx_codex_icon_from_proof: false # Default value (line can be removed), the icon of the codex directive will not be taken from the prf:example directive from the sphinx-proof extension, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html)
|
||||
sphinx_codex_merge_with_proof: false # Default value (line can be removed), the codex directive will not be merged with the prf:example directive from the sphinx-proof extension, configuration part of Sphinx-Code-Examples (https://teachbooks.io/manual/_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.html)
|
||||
#togglebutton_hint: "Click to show" # Displayed when the toggle is closed, overrides translated hint, configuration part of Sphinx-Togglebutton (https://sphinx-togglebutton.readthedocs.io/en/latest/use.html)
|
||||
#togglebutton_hint_hide: "Click to hide" # Displayed when the toggle is opened, overrides translated hint, configuration part of Sphinx-Togglebutton (https://sphinx-togglebutton.readthedocs.io/en/latest/use.html)
|
||||
togglebutton_open_on_print: true # Default value (line can be removed), opens all toggle-able content when you print, configuration part of Sphinx-Togglebutton (https://sphinx-togglebutton.readthedocs.io/en/latest/use.html)
|
||||
nb_execution_includepatterns: [] # Default value (line can be removed), sets a a list of glob patterns to indicate notebooks that must be included for execution, configuration part of Sphinx-NB-Execution-Patterns (https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html)
|
||||
nb_execution_patterns_method: "only_include" # Default value (line can be removed), sets the method used when both include and exclude patterns are provided, configuration part of Sphinx-NB-Execution-Patterns (https://teachbooks.io/manual/_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.html)
|
||||
tippy_props: {"placement": "auto-start", "maxWidth": 500, "interactive": True, "boundary": "document.body", "appendTo": "document.body"} # Default value (line can be removed), sets tippy properties, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html)
|
||||
#tippy_add_class # Default value not shown (line can be removed), adds a class name to all elements with tips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html)
|
||||
#tippy_skip_urls # Default value not shown (line can be removed), a list of URL regexes to skip, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html)
|
||||
tippy_tip_selector: "figure, table, img, p, aside, div.admonition, div.literal-block-wrapper" # Default value (line can be removed), defines what elements tips are created for, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html)
|
||||
#tippy_skip_anchor_classes # Default value not shown (line can be removed), skips showing tooltips for anchors with these classes, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html)
|
||||
#tippy_anchor_parent_selector # Default value not shown (line can be removed), only show tool tips for anchors within this select, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html)
|
||||
tippy_enable_wikitips: true # Default value (line can be removed), enables tooltips for wikipedia links, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html)
|
||||
tippy_enable_doitips: true # Default value (line can be removed), enables tooltips for DOI links, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html)
|
||||
tippy_doi_api: "https://api.crossref.org/works/" # Default value (line can be removed), sets the API to use for DOI tooltips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html)
|
||||
#tippy_doi_template # Default value not shown (line can be removed), sets the jinja template to use for formatting DOI data to tooltips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html)
|
||||
#tippy_custom_tips # Default value not shown (line can be removed), creates custom tips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html)
|
||||
tippy_enable_mathjax: true # Default value (line can be removed), enables tooltips for math equations, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html)
|
||||
#tippy_js # Default value not shown (line can be removed), sets the Javascript required to enable tooltips, configuration part of TeachBooks-Sphinx-Tippy (https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html)
|
||||
|
||||
|
||||
teachbooks:
|
||||
attribution_location: top # Default value (line can be removed), sets location of attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html)
|
||||
attribution_color: null # Default value (line can be removed), uses blue colour for attribution admonition of external pages, configuration part of TeachBooks package (https://teachbooks.io/manual/features/external_toc.html)
|
||||
|
||||
bibtex_bibfiles:
|
||||
- references.bib # Required for references
|
||||
- references.bib # Required for references, configuration part of Sphinx (https://www.sphinx-doc.org/en/master/index.html)
|
||||
|
||||
# Parse and render settings
|
||||
parse:
|
||||
myst_enable_extensions: # Default values (lines can be removed), sets extensions to enable in the myst parser, configuration part of MyST parser (https://myst-parser.readthedocs.io/en/latest/syntax/optional.html)
|
||||
- colon_fence
|
||||
- dollarmath
|
||||
- linkify
|
||||
- substitution
|
||||
- tasklist
|
||||
myst_url_schemes: [mailto, http, https] # Default value (lines can be removed), sets URI schemes that will be recognised as external URLs in Markdown links, configuration part of MyST parser (https://myst-parser.readthedocs.io/en/latest/syntax/optional.html)
|
||||
myst_dmath_double_inline: true # Default value (lines can be removed), allows display math ($$) within an inline context, configuration part of MyST parser (https://myst-parser.readthedocs.io/en/latest/syntax/optional.html)
|
||||
|
|
|
|||
|
|
@ -1,12 +1,19 @@
|
|||
# Configuration of _toc.yml file is explained in detail here: https://jupyterbook.org/en/stable/structure/toc.html and https://sphinx-external-toc.readthedocs.io/en/latest/user_guide/sphinx.html
|
||||
|
||||
format: jb-book
|
||||
root: intro.md
|
||||
|
||||
parts:
|
||||
- caption: Contents
|
||||
- caption: Part with some content # A title for the whole the subtree, e.g. shown above the subtree in ToCs, configuration part of sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html)
|
||||
numbered: false # Default value (line can be removed), whether to number the chapters/sections in this part, configuration part of sphinx-external-toc (https://sphinx-external-toc.readthedocs.io/en/latest/intro.html)
|
||||
style: numerical # Default value (line can be removed), style of numbering for this part, configuration part of TeachBooks' version of sphinx-external-toc (https://github.com/TeachBooks/sphinx-external-toc?tab=readme-ov-file#toc-tree-options)
|
||||
restart_numbering: false # Default value (line can be removed), whether to restart numbering for this part, configuration part of TeachBooks' version of sphinx-external-toc (https://github.com/TeachBooks/sphinx-external-toc?tab=readme-ov-file#toc-tree-options)
|
||||
chapters:
|
||||
- file: some_content/overview.md
|
||||
sections:
|
||||
- file: some_content/text_and_code.ipynb
|
||||
- caption: Exercises
|
||||
chapters:
|
||||
- file: exercises.md
|
||||
sections:
|
||||
- file: exercises/001.md
|
||||
|
|
@ -14,6 +21,7 @@ parts:
|
|||
- file: exercises/003.md
|
||||
- file: exercises/004.md
|
||||
- file: exercises/005.md
|
||||
- file: exercises/005a.md
|
||||
- file: exercises/006.md
|
||||
- file: exercises/summary
|
||||
- file: syntax_exercises.md
|
||||
|
|
@ -24,6 +32,16 @@ parts:
|
|||
- file: syntax_exercises/010.md
|
||||
- file: syntax_exercises/011.md
|
||||
- file: syntax_exercises/012.md
|
||||
- file: syntax_exercises/013.md
|
||||
- file: extensions.md
|
||||
sections:
|
||||
- file: exercises/007.md
|
||||
- file: extension_exercises/017.md
|
||||
- file: extension_exercises/014.md
|
||||
- file: extension_exercises/015.md
|
||||
- file: extension_exercises/016.md
|
||||
- caption: Miscellaneous
|
||||
chapters:
|
||||
- file: references.md
|
||||
- file: changelog.md
|
||||
- file: credits.md
|
||||
|
|
|
|||
|
|
@ -9,7 +9,8 @@ Maybe you're already comfortable with Git, GitHub and the concept of using softw
|
|||
3. Can you edit the repository url defined in the `_config.yml`, change the title shown below the logo and change the author as shown in the footer?
|
||||
4. Can you make a new branch of your book with an additional file `file_on_new_version.md` and view it online?
|
||||
5. Can you merge your branch into `main` with a pull request?
|
||||
6. Can you fork someone else's repo, and suggest a change in a pull request?
|
||||
6. Can you add read-only content from someone else without manually copying the source?
|
||||
7. Can you fork someone else's repo, and suggest a change in a pull request?
|
||||
|
||||
If something is not clear, dive into to the relevant exercise page.
|
||||
```
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ Can you add some content to the intro page?
|
|||
::::::
|
||||
|
||||
1. Go to the the file `book/intro.md` on your GitHub repository (`https://github.com/<your_username>/<your_repo_name>`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file`
|
||||
2. Add some text. Feeling brave? Have a look at the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html). Don't worry if that feels daunting, there will be exercises on this!
|
||||
2. Add some text. Feeling brave? Have a look at the [MyST cheat sheet](https://jupyterbook.org/v1/reference/cheatsheet.html). Don't worry if that feels daunting, there will be exercises on this!
|
||||
3. Click `Commit changes`
|
||||
4. Add a message and description of your change. With this `commit` you save your changes to the git-timeline. Any commit can always be reverted. Therefore, it's useful to shortly explain what is included in your commit. Later on, you'll make commits which may contain changes to many different files. In that case, a descriptive commit message and description is even more useful!
|
||||
5. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one)
|
||||
|
|
|
|||
|
|
@ -12,13 +12,13 @@ Can you edit the repository url defined in the `_config.yml`, change the title s
|
|||
:class: tip, dropdown
|
||||
The first line of your `_config.yml` should look like
|
||||
```yaml
|
||||
author: <your_name>, built with <a href="https://teachbooks.io">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>
|
||||
author: <your_name>, built with <a href="https://teachbooks.io">TeachBooks</a> and <a href="https://jupyterbook.org/v1">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>
|
||||
```
|
||||
````
|
||||
3. In the `Edit` field, change the title of your homepage which will under the logo and above the table of contents
|
||||
````{admonition} Need some help?
|
||||
:class: tip, dropdown
|
||||
The 21st line of your `_config.yml` should look like
|
||||
The 35th line of your `_config.yml` should look like
|
||||
```yaml
|
||||
text: <your_title>
|
||||
```
|
||||
|
|
@ -26,7 +26,7 @@ The 21st line of your `_config.yml` should look like
|
|||
4. In the `Edit` field, change the repository url which will be used to allow other people to open your repository, suggest edits and open issues as shown in top right corner of the built book under {octicon}`mark-github;1em`.
|
||||
````{admonition} Need some help?
|
||||
:class: tip, dropdown
|
||||
The 24th line of your `_config.yml` should look like
|
||||
The 38th line of your `_config.yml` should look like
|
||||
```yaml
|
||||
repository_url: "https://github.com/<your_username>/<your_repository>"
|
||||
```
|
||||
|
|
@ -45,4 +45,4 @@ Before moving on to the next exercise, make sure you understand the following:
|
|||
- What is this special `_config.yml` file?
|
||||
- Changes in `_config.yml` can have effect on multiple pages in the book
|
||||
- The `_config.yml` is generally not used for adding content
|
||||
```
|
||||
```
|
||||
|
|
|
|||
85
book/exercises/005a.md
Normal file
85
book/exercises/005a.md
Normal file
|
|
@ -0,0 +1,85 @@
|
|||
# Exercise 6: Reuse content from another book
|
||||
|
||||
So far, you've been working inside your own book. But what if someone else has already written a page you’d like to reuse? Instead of copying it, you can **include it directly** into your own book using the `external:` feature in your `_toc.yml`.
|
||||
|
||||
You can find the link to reuse in one of two ways:
|
||||
|
||||
* Use the [TeachBooks Recombiner](https://teachbooks.io/recombiner/) to select and copy the link.
|
||||
* If the page isn't listed in the Recombiner, find the link manually in the GitHub repository.
|
||||
|
||||
::::::{topic} Exercise objective
|
||||
Can you include a page from someone else’s book into your own using `external:` in your `_toc.yml`?
|
||||
::::::
|
||||
|
||||
|
||||
1. Find the page you want to reuse:
|
||||
|
||||
* Option 1: Open the [TeachBooks Recombiner](https://teachbooks.io/recombiner/), select the book and chapter(s) you want to reuse, and click *Show how do it yourself instructions*. Copy the `external:` link provided.
|
||||
* Option 2: If the page isn’t in the Recombiner, find it manually:
|
||||
|
||||
* Go to the repository (e.g., [TeachBooks Manual on GitHub](https://github.com/TeachBooks/manual)).
|
||||
* Browse the files and find the `.md` page you want (e.g., `README.md`, `workflows/collaboration.md`).
|
||||
* Copy the raw link in this format:
|
||||
|
||||
```yaml
|
||||
- external: https://github.com/TeachBooks/manual/blob/release/book/examples/book_structure.md
|
||||
```
|
||||
|
||||
2. Add the `external:` link into `chapters:` section of your `_toc.yml` file.
|
||||
|
||||
3. Save the changes, commit, and push them.
|
||||
|
||||
|
||||
````{admonition} Example
|
||||
`_toc.yml` snippet:
|
||||
|
||||
```yaml
|
||||
format: jb-book
|
||||
root: intro
|
||||
|
||||
parts:
|
||||
- caption: Contents
|
||||
chapters:
|
||||
- file: 001
|
||||
- external: https://github.com/TeachBooks/manual/blob/release/book/examples/book_structure.md
|
||||
- file: 003
|
||||
```
|
||||
````
|
||||
|
||||
4. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
|
||||
|
||||
5. Add a commit message.
|
||||
|
||||
6. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting).
|
||||
|
||||
7. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. Open the reused page. At the top, you should see an **attribution box**. This confirms the external content is working correctly and shows where it was sourced from.
|
||||
|
||||
```{figure} https://github.com/TeachBooks/template_figures/blob/main/external_page_attribution.png?raw=true
|
||||
:name: external_page_attribution
|
||||
:width: 100%
|
||||
:alt: Example of attribution box shown at the top of an external page
|
||||
|
||||
Example of attribution box at the top of an external page.
|
||||
```
|
||||
|
||||
```{admonition} Check your understanding
|
||||
:class: note
|
||||
|
||||
Before moving on, make sure you understand:
|
||||
|
||||
* What is the benefit of linking to an external page instead of copying it?
|
||||
* How does using the Recombiner simplify adding external content?
|
||||
* What can you do if a page isn’t in the Recombiner?
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Exercise 6: Contribute to the book of somebody else
|
||||
# Exercise 7: Contribute to the book of somebody else
|
||||
|
||||
```{tip}
|
||||
For this exercise you will need a partner, as well as your own book. In the first part, each of you will make a change in the book of the other, then request the other to review and merge the change. In the second part, you will go back to your book and accept the change made by your partner.
|
||||
|
|
|
|||
78
book/exercises/007.md
Normal file
78
book/exercises/007.md
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
# Add extensions to your book
|
||||
|
||||
TeachBooks supports many useful extensions, but sometimes you may want more functionality. In this exercise, you'll learn how to add an external extension to your book that is not already built-in. We will use the [`Sphinx-Indexed-Definitions`](https://github.com/TeachBooks/Sphinx-Indexed-Definitions) extension as an example, which allows you to define glossary-style entries with indexed labels in an easy way.
|
||||
|
||||
::::::{topic} Exercise objective
|
||||
Can you install and use a new Sphinx extension like `Sphinx-Indexed-Definitions` in your TeachBooks book?
|
||||
::::::
|
||||
|
||||
1. In your book repository, open the `requirements.txt` file. This file lists the Python packages that will be installed to build your book.
|
||||
|
||||
2. Add the following line to the bottom of the `requirements.txt` file:
|
||||
|
||||
```
|
||||
sphinx-indexed-definitions
|
||||
```
|
||||
|
||||
This tells the build system to install the extension from PyPi, a repository which contains Python software
|
||||
|
||||
3. Next, open `_config.yml` and add the extension to your `sphinx` configuration block:
|
||||
|
||||
```yaml
|
||||
sphinx:
|
||||
extra_extensions:
|
||||
- indexed_definitions
|
||||
```
|
||||
|
||||
This ensures Sphinx loads the extension when building your book.
|
||||
|
||||
4. Now you can use the new directive provided by the extension. First, read the documentation to understand how to apply it. In most cases, the documentation can be found in the README of the source repository of the software. For our example that is here: https://github.com/TeachBooks/Sphinx-Indexed-Definitions
|
||||
|
||||
5. Try adding the following to one of your Markdown files in the `book/` directory:
|
||||
|
||||
`````md
|
||||
````{definition} Term
|
||||
:label: term-definition
|
||||
A word or phrase used to describe a concept or object.
|
||||
````
|
||||
`````
|
||||
|
||||
This will render a labelled, indexed definition that you can refer to from other parts of your book.
|
||||
|
||||
6. Try to reference the definition in another file using `{ref}` followed by the given label, as shown below:
|
||||
|
||||
|
||||
```md
|
||||
For more details, see the definition of {ref}`term-definition`.
|
||||
```
|
||||
|
||||
This will appear as a hyperlink that takes the reader directly to the definition.
|
||||
|
||||
|
||||
7. The extension can also automatically index terms based on text formatting. In another `.md` file, try writing:
|
||||
|
||||
```md
|
||||
This is a **strong term**, this is an *emphasised term*, and this is a `literal term`.
|
||||
```
|
||||
|
||||
When the book is built, these terms will be included in the generated index without needing to define them manually. You can view the index in the build output to confirm.
|
||||
|
||||
8. The same steps you followed here can be used to install any other extension of your choice. Simply add the extension to your `requirements.txt` (using either a GitHub link or PyPI package name), and list it under `extra_extensions` in `_config.yml`. Then use its features in your Markdown files according to the extension’s documentation. Check out the ever-growing list of TeachBooks extensions in the [TeachBooks manual](https://teachbooks.io/manual/features/overview.html)!
|
||||
|
||||
8. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
|
||||
|
||||
9. Add a commit message.
|
||||
|
||||
10. To see your changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting).
|
||||
11. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
|
||||
|
||||
|
||||
```{admonition} Check your understanding
|
||||
:class: note
|
||||
|
||||
Before moving on, make sure you understand:
|
||||
|
||||
* How do you add a new extension to a TeachBooks book?
|
||||
* What is the purpose of the `requirements.txt` and `_config.yml` files?
|
||||
* How can you confirm that your extension is working correctly?
|
||||
```
|
||||
|
|
@ -15,12 +15,12 @@ Here is how these exercises relate to the workflow.
|
|||
| :---: | :---: | :---: | :---: |
|
||||
| 1 | Get and idea | 4 | Create an issue |
|
||||
| 2 | Create _your_ version of the book | 4 | Create a branch |
|
||||
| 3 | Edit the book | 1, 2, 3| Editing `.md`-files, the `_toc.yml` and the `_config.yml` |
|
||||
| 4 | Check changes online | 1, 2, 3 | Workflows and Actions Summary |
|
||||
| 3 | Edit the book | 1, 2, 3, 6| Editing `.md`-files, the `_toc.yml` and the `_config.yml` |
|
||||
| 4 | Check changes online | 1, 2, 3, 6| Workflows and Actions Summary |
|
||||
| 5 | Repeat edit and checking | 1, 2, 3, 4, 5 | Keep on doing all the steps until it's ready|
|
||||
| 6 | Submit for review | 5, 6 | Open and merge a Pull Request, from a branch or forks |
|
||||
| 6 | Submit for review | 5, 7 | Open and merge a Pull Request, from a branch or forks |
|
||||
|
||||
## Keep practicing
|
||||
|
||||
For additional practice, there are more exercises relating to the capacities of each user type.
|
||||
Have a look in the [manual](https://teachbooks.io/manual/installation-and-setup/user_types.html) to see which user type you are!
|
||||
Have a look in the [manual](https://teachbooks.io/manual/installation-and-setup/user_types.html) to see which user type you are!
|
||||
|
|
|
|||
240
book/extension_exercises/014.md
Normal file
240
book/extension_exercises/014.md
Normal file
|
|
@ -0,0 +1,240 @@
|
|||
# Live code
|
||||
|
||||
With live coding you can make your pages more interactive by adding live, executable code cells. This extension is already part of your TeachBooks book if you started from the template. If not, you can follow instructions [in the manual](https://teachbooks.io/manual/features/live_code.html#setting-up-python-live-coding) to enable it. The template also includes a sample page with live code enabled, which you can find [here for the website of the original template](https://teachbooks.io/template/some_content/text_and_code.html)
|
||||
|
||||
With live code enabled, readers can run snippets directly in the browser, experiment with examples, and complete exercises in real time. This section will guide you through some of the main features available: additional cell tags have been developed that can be added to Python code cells in your book. These tags extend the [existing Jupyter Book tags](https://jupyterbook.org/en/stable/content/metadata.html) and allow you to control how cells behave when live execution is enabled.
|
||||
|
||||
::::::{topic} Exercise objective
|
||||
Can you apply custom cell tags to control the execution and visibility of code cells?
|
||||
::::::
|
||||
|
||||
## Available custom tags
|
||||
|
||||
- `disable-execution-cell` disables the ability to execute the cell when live code is activated. This is useful if your notebook includes interactivity for only part of the cells.
|
||||
- `disable-execution-page` disables the ability to execute the entire page. This can be helpful if Python code is used to build a page but is not meant to be run by readers.
|
||||
- `auto-execute-page` automatically starts live coding when the page is opened, useful if you are using widgets.
|
||||
- `thebe-init` runs this cell automatically as soon as live coding starts.
|
||||
- `thebe-remove-input-init` is similar to `thebe-init` but hides the input from students while still executing it. (The regular `remove-input` tag will not work here, since it deletes the entire cell.)
|
||||
|
||||
```{tip}
|
||||
Tags are case-sensitive. Use lowercase and match them exactly as shown above.
|
||||
````
|
||||
|
||||
## Creating a notebook
|
||||
|
||||
There are two ways you can try this exercise, depending on whether you have an IDE installed. If you don't know what an IDE is, or don't have one installed, follow Option 2 below.
|
||||
|
||||
```````{tab-set}
|
||||
``````{tab-item} Option 1: Using JupyterLab or VS Code (if installed)
|
||||
|
||||
1. In your repository, create a new notebook file in your book directory, e.g. `book/live_code_tags.ipynb`.
|
||||
2. To add a new code cell, use `python` and enter a simple code, for example:
|
||||
|
||||
````md
|
||||
```python
|
||||
print("Hello world!")
|
||||
```
|
||||
````
|
||||
|
||||
With this setup, tags can be added by opening the cell metadata (in JupyterLab or Jupyter Notebook: `View → Cell Toolbar → Tags`).
|
||||
|
||||
``````
|
||||
``````{tab-item} Option 2: Using Jupytext in Markdown
|
||||
|
||||
1. If you don’t have JupyterLab or VS Code installed, you can still add code in a markdown file. To make sure this is recognized as an interactive code cell, you need to add a Jupytext header. At the very top of your file (e.g. `book/live_code_tags.md`), add:
|
||||
|
||||
```yaml
|
||||
---
|
||||
jupytext:
|
||||
text_representation:
|
||||
extension: .md
|
||||
format_name: myst
|
||||
format_version: 0.13
|
||||
jupytext_version: 1.17.3
|
||||
kernelspec:
|
||||
display_name: base
|
||||
language: python
|
||||
name: python3
|
||||
---
|
||||
```
|
||||
|
||||
2. Now you can insert executable code cells like this:
|
||||
|
||||
````md
|
||||
```{code-cell} ipython3
|
||||
print("Hello world!")
|
||||
```
|
||||
````
|
||||
|
||||
With this setup, tags can be added directly into the code cell using `:tags:`, for example:
|
||||
|
||||
````md
|
||||
```{code-cell} ipython3
|
||||
:tags: ["hide-cell"]
|
||||
print("Hello world!")
|
||||
```
|
||||
````
|
||||
|
||||
``````
|
||||
```````
|
||||
|
||||
## Trying the custom tags
|
||||
|
||||
Now that you know how to create executable code cells, let’s explore the different custom tags available and see examples of how each one can control the behavior of your code when live execution is enabled.
|
||||
|
||||
|
||||
### `disable-execution-cell`
|
||||
|
||||
3. This tag is useful when you want a particular code cell to display content without being executed by readers. For example, let’s set up a new cell that prints the current date and time only once:
|
||||
|
||||
```````{tab-set}
|
||||
``````{tab-item} Option 1: Using JupyterLab or VS Code
|
||||
|
||||
```python
|
||||
import datetime
|
||||
|
||||
# This prints the current date and time once
|
||||
current_time = datetime.datetime.now()
|
||||
print("This notebook was last updated at:", current_time)
|
||||
```
|
||||
|
||||
*Remember to add the tag `disable-execution-cell` locally via the cell metadata (`View → Cell Toolbar → Tags`).*
|
||||
|
||||
``````
|
||||
``````{tab-item} Option 2: Using Jupytext in Markdown
|
||||
|
||||
````md
|
||||
```{code-cell} ipython3
|
||||
:tags: ["disable-execution-cell"]
|
||||
|
||||
import datetime
|
||||
|
||||
# This prints the current date and time once
|
||||
current_time = datetime.datetime.now()
|
||||
print("This notebook was last updated at:", current_time)
|
||||
```
|
||||
````
|
||||
|
||||
``````
|
||||
```````
|
||||
|
||||
4. Commit and rebuild your book and visit the page — notice that this particular cell can no longer be run when live code is activated.
|
||||
|
||||
### `disable-execution-page`
|
||||
|
||||
5. This tag is useful when you want all code cells on a page to be non-executable. This is handy if the code is used to build the page or provide context, but you don’t want readers to run it themselves. Add the tag `disable-execution-page` to any of the code cells in your file.
|
||||
|
||||
6. Commit and rebuild your book and visit the page — none of the cells should be executable now.
|
||||
|
||||
```{note}
|
||||
Remove this tag again before continuing, otherwise the next tags won’t have any effect.
|
||||
```
|
||||
|
||||
### `auto-execute-page`
|
||||
|
||||
7. This tag is useful when you want live code to start running automatically as soon as the page is opened. This is particularly helpful when using visualizations or interactive widgets that should initialize immediately. For example, let's set up a plot:
|
||||
|
||||
```````{tab-set}
|
||||
``````{tab-item} Option 1: Using JupyterLab or VS Code
|
||||
|
||||
```python
|
||||
import matplotlib.pyplot as plt
|
||||
import numpy as np
|
||||
|
||||
x = np.linspace(0, 10, 100)
|
||||
y = np.sin(x)
|
||||
|
||||
plt.plot(x, y)
|
||||
plt.title("Sine wave")
|
||||
plt.show()
|
||||
```
|
||||
|
||||
*Remember to add the tag `auto-execute-page` to one of the cells via the cell metadata (`View → Cell Toolbar → Tags`).*
|
||||
|
||||
``````
|
||||
``````{tab-item} Option 2: Using Jupytext in Markdown
|
||||
|
||||
````md
|
||||
```{code-cell} ipython3
|
||||
:tags: ["auto-execute-page"]
|
||||
|
||||
import matplotlib.pyplot as plt
|
||||
import numpy as np
|
||||
|
||||
x = np.linspace(0, 10, 100)
|
||||
y = np.sin(x)
|
||||
|
||||
plt.plot(x, y)
|
||||
plt.title("Sine wave")
|
||||
plt.show()
|
||||
```
|
||||
````
|
||||
|
||||
``````
|
||||
```````
|
||||
|
||||
8. Commit and rebuild your book and visit the page — the plot should appear automatically without needing to click the “launch” button.
|
||||
|
||||
|
||||
|
||||
### `thebe-init`
|
||||
|
||||
9. The `thebe-init` tag is useful when you want a specific cell to run automatically as soon as live coding starts. This is especially helpful for initializing variables that other cells depend on. For example, let's initialize a dataset of student names and their scores:
|
||||
|
||||
```````{tab-set}
|
||||
``````{tab-item} Option 1: Using JupyterLab or VS Code
|
||||
|
||||
```python
|
||||
# Initialize dataset
|
||||
students = ["Alice", "Bob", "Charlie", "Diana"]
|
||||
scores = [85, 92, 78, 90]
|
||||
|
||||
print("Initialized dataset with students and scores")
|
||||
```
|
||||
|
||||
*Remember to add the tag `thebe-init` locally via the cell metadata (`View → Cell Toolbar → Tags`).*
|
||||
|
||||
``````
|
||||
``````{tab-item} Option 2: Using Jupytext in Markdown
|
||||
|
||||
````md
|
||||
```{code-cell} ipython3
|
||||
:tags: ["thebe-init"]
|
||||
|
||||
# Initialize dataset
|
||||
students = ["Alice", "Bob", "Charlie", "Diana"]
|
||||
scores = [85, 92, 78, 90]
|
||||
|
||||
print("Initialized dataset with students and scores")
|
||||
```
|
||||
````
|
||||
|
||||
|
||||
``````
|
||||
```````
|
||||
|
||||
10. Commit and rebuild your book and visit the page — as soon as live code starts, this cell will run by itself.
|
||||
|
||||
### `thebe-remove-input-init`
|
||||
|
||||
11. This tag works similarly to `thebe-init`, but the input (code) is hidden from students, so they only see the output. This is useful when you want to initialize variables or datasets without showing implementation details. To try this, simply replace the previous tag `thebe-init` with `thebe-remove-input-init` in the same cell from the previous example.
|
||||
|
||||
12. Commit and rebuild your book and visit the page — the cell will run automatically, but students will only see the output, not the code.
|
||||
|
||||
13. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
|
||||
|
||||
14. Add a commit message.
|
||||
|
||||
15. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting).
|
||||
|
||||
16. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
|
||||
|
||||
```{admonition} Check your understanding
|
||||
:class: note
|
||||
|
||||
Before moving on, make sure you understand the following:
|
||||
- How do you add tags to a code cell in your book?
|
||||
- Which tag disables execution for a single cell? For the whole page?
|
||||
- Which tag makes a page auto-start live code when opened?
|
||||
- What is the difference between `thebe-init` and `thebe-remove-input-init`?
|
||||
```
|
||||
130
book/extension_exercises/015.md
Normal file
130
book/extension_exercises/015.md
Normal file
|
|
@ -0,0 +1,130 @@
|
|||
# Deploy Book Workflow
|
||||
|
||||
The **Deploy Book Workflow (DBW)** automatically builds and publishes your TeachBook whenever changes are pushed to your repository. If you started your book from the TeachBooks Template, this workflow is already included.
|
||||
|
||||
With this workflow, readers can see your latest book version online without manual intervention. This exercise will guide you through triggering the workflow, configuring branch-specific builds, and customising deployment options.
|
||||
|
||||
::::::{topic} Exercise objective
|
||||
Can you trigger, configure, and monitor the Deploy Book Workflow to publish your TeachBook automatically?
|
||||
::::::
|
||||
|
||||
|
||||
|
||||
## Trigger the workflow
|
||||
|
||||
1. Make a small edit in any page of your book (for example `book/intro.md`).
|
||||
2. Commit the change and push it to the `main` branch.
|
||||
3. Open the **Actions** tab of your repository. You should see a workflow called *Deploy Book* running.
|
||||
4. When it finishes, visit the URL:
|
||||
|
||||
````
|
||||
https://<username>.github.io/<repository-name>/
|
||||
````
|
||||
|
||||
to see the updated book.
|
||||
|
||||
|
||||
5. The workflow can also be triggered in a separate branch. Create a new branch, e.g., `draft-chapter`.
|
||||
6. Push a change to this branch.
|
||||
7. The DBW automatically builds a version of your book for that branch, available at:
|
||||
|
||||
````
|
||||
https://<username>.github.io/<repository-name>/draft-chapter/
|
||||
````
|
||||
|
||||
```{tip}
|
||||
Branch-specific builds are useful for previewing work in progress without affecting the main book.
|
||||
```
|
||||
|
||||
|
||||
## Customise the workflow
|
||||
|
||||
8. The behaviour of the Deploy Book Workflow can be adapted by defining **repository variables** in your GitHub repository, as explained [here](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository).
|
||||
|
||||
|
||||
```{admonition} Key repository variables
|
||||
| Variable | Default | Purpose |
|
||||
|-----------------------|-------------|-------------------------------------------------------------------------|
|
||||
| `PRIMARY_BRANCH` | `main` | Which branch appears at the root URL. |
|
||||
| `BEHAVIOR_PRIMARY` | `redirect` | How the root URL behaves: `redirect`, `copy`, or `move`. |
|
||||
| `BRANCH_ALIASES` | | Space-separated list of aliases (custom URLs) for branches. |
|
||||
| `BRANCHES_TO_DEPLOY` | `*` | Which branches are deployed (all by default). |
|
||||
| `BRANCHES_TO_PREPROCESS` | | Branches preprocessed with TeachBooks (e.g. remove draft-only content). |
|
||||
| `BRANCHES_ARCHIVED` | | Adds a banner to old versions marking them as archived. |
|
||||
```
|
||||
|
||||
```{note}
|
||||
You can also edit `.github/workflows/call-deploy-book.yml` to change which branches or folders trigger deployment.
|
||||
```
|
||||
|
||||
|
||||
## Common usage scenarios
|
||||
|
||||
### Scenario 1 — Academic years
|
||||
|
||||
```{admonition} Context
|
||||
Each year you release a new version of your book for students, but older cohorts still need access.
|
||||
```
|
||||
|
||||
9. Create a branch for each year (e.g. `2024`, `2025`).
|
||||
10. In repository variables, set:
|
||||
|
||||
- `PRIMARY_BRANCH = 2025`
|
||||
- `BEHAVIOR_PRIMARY = redirect` (so the root redirects to the current year).
|
||||
11. Push a change to the `2025` branch.
|
||||
12. Verify the URLs:
|
||||
|
||||
- `.../my_book/2025/` (this year)
|
||||
- `.../my_book/2024/` (last year)
|
||||
- `.../my_book/` (redirects to current year).
|
||||
|
||||
```{tip}
|
||||
If you want the root URL to always show a complete book instead of the in-progress year, set
|
||||
`PRIMARY_BRANCH = 2024` and `BEHAVIOR_PRIMARY = copy`, and mark `2025` as archived. However, we recommend
|
||||
using redirects as students might bookmark pages. If the URL changes the next academic year their bookmark
|
||||
becomes invalid or points to another page.
|
||||
```
|
||||
|
||||
|
||||
### Scenario 2 — Draft and release workflow
|
||||
|
||||
```{admonition} Context
|
||||
You want a public release branch, an internal draft branch, and multiple author branches for parallel work.
|
||||
```
|
||||
|
||||
13. Create branches: `release`, `draft`, `author_1`, `author_2`, etc.
|
||||
14. Set your GitHub default branch to `draft`.
|
||||
15. In repository variables, set:
|
||||
|
||||
* `PRIMARY_BRANCH = release`
|
||||
* `BEHAVIOR_PRIMARY = copy`.
|
||||
16. Push changes to each branch and check the URLs:
|
||||
|
||||
* `.../my_book/` (release version)
|
||||
* `.../my_book/draft/` (draft version)
|
||||
* `.../my_book/author_1/`, etc.
|
||||
|
||||
```{note}
|
||||
Making `draft` the default branch ensures pull requests are tested in draft first, avoiding accidental premature releases.
|
||||
```
|
||||
|
||||
|
||||
17. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
|
||||
|
||||
18. Add a commit message.
|
||||
|
||||
19. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting).
|
||||
|
||||
20. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
|
||||
|
||||
|
||||
|
||||
```{admonition} Check your understanding
|
||||
:class: note
|
||||
|
||||
|
||||
Before moving on, make sure you understand:
|
||||
- How can you trigger the Deploy Book Workflow?
|
||||
- What is the purpose of `PRIMARY_BRANCH` and `BEHAVIOR_PRIMARY`?
|
||||
- How would you set up the workflow so that both a release and a draft version of your book are available online?
|
||||
```
|
||||
80
book/extension_exercises/016.md
Normal file
80
book/extension_exercises/016.md
Normal file
|
|
@ -0,0 +1,80 @@
|
|||
# Image and Iframe Dark Mode Colour Inverter
|
||||
|
||||
The **Sphinx-Image-Inverter** extension automatically adapts figures, images, and iframes to dark mode by inverting their colours. Meanwhile, it makes sure that a colour is still recognizable, i.e. red stays red, blue stays blue, etc. This ensures that visuals remain readable and consistent across light and dark themes. In this exercise, you’ll install the extension, configure its options, and experiment with enabling and disabling inversion for specific images.
|
||||
|
||||
::::::{topic} Exercise objective
|
||||
Can you configure the Sphinx-Image-Inverter to control how images and iframes behave in dark mode?
|
||||
::::::
|
||||
|
||||
# Configure image inversion
|
||||
|
||||
You can control how and when images are inverted by adjusting parameters in `_config.yml`.
|
||||
|
||||
1. To disable inversion globally, set `inverter_all` to `false`. This disables automatic inversion for all images. This is especially useful if your images are photos which won't look good when inverted.
|
||||
|
||||
```yaml
|
||||
sphinx:
|
||||
config:
|
||||
inverter_all: false
|
||||
```
|
||||
|
||||
2. To enable inversion globally, set `inverter_all` to `true`. This enables automatic inversion for all images. This is useful if your images are mostly diagrams or plots which benefit from inversion.
|
||||
|
||||
```yaml
|
||||
sphinx:
|
||||
config:
|
||||
inverter_all: true
|
||||
```
|
||||
|
||||
3. If you would like to selectively include or exclude specific figures or iframes from inversion the `dark-light` class can be used. Locate the markdown file that contains the image you want to exclude from inversion and add the `:class: dark-light` attribute as follows:
|
||||
|
||||
````md
|
||||
```{figure} images/example_plot.png
|
||||
:class: dark-light
|
||||
:width: 400
|
||||
```
|
||||
````
|
||||
|
||||
```{note}
|
||||
When dark mode is toggled, this image will not be inverted if `inverter_all: true`.
|
||||
If `inverter_all: false`, only this image will be inverted.
|
||||
```
|
||||
|
||||
4. The saturation can also be adjusted. The default colour saturation is `1.5`. Let us reduce the contrast by changing this to `1.0`:
|
||||
|
||||
```yaml
|
||||
sphinx:
|
||||
config:
|
||||
inverter_saturation: 1.0
|
||||
```
|
||||
|
||||
```{tip}
|
||||
Try different saturation levels to see how they affect contrast in dark mode — between `1.0` (no change) and `2.0` (vivid colours) is recommended.
|
||||
```
|
||||
|
||||
5. It is also possible to choose to show or hide text depending on the selected theme. This is useful for adding hints or notes that depend on visibility. Try this out using the following classes:
|
||||
|
||||
```html
|
||||
<span class="only-light">This message is only visible in light mode.</span>
|
||||
|
||||
<span class="only-dark">This message appears only in dark mode.</span>
|
||||
```
|
||||
|
||||
6. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
|
||||
|
||||
7. Add a commit message.
|
||||
|
||||
8. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting).
|
||||
|
||||
9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
|
||||
|
||||
|
||||
```{admonition} Check your understanding
|
||||
:class: note
|
||||
|
||||
Before moving on, make sure you can answer:
|
||||
- What does the Sphinx-Image-Inverter extension do?
|
||||
- How do you disable automatic inversion for all images?
|
||||
- What is the effect of the `dark-light` class?
|
||||
- What happens when you change the `inverter_saturation` value?
|
||||
```
|
||||
64
book/extension_exercises/017.md
Normal file
64
book/extension_exercises/017.md
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
# TeachBooks Favourites
|
||||
|
||||
The **TeachBooks-Favourites** extension brings together TeachBooks’ most-used and most-loved features in one convenient package. It bundles several Sphinx extensions—developed both by TeachBooks and others—into a single install, making it easier to start a new TeachBook with all recommended functionality already enabled.
|
||||
|
||||
This exercise will guide you through installing the **TeachBooks-Favourites** extension, enabling it in your configuration, and exploring what it includes.
|
||||
|
||||
::::::{topic} Exercise objective
|
||||
Can you install and activate the TeachBooks-Favourites extension, and identify which tools it automatically enables?
|
||||
::::::
|
||||
|
||||
## Explore what’s included
|
||||
|
||||
The TeachBooks-Favourites bundle includes many extensions. For more information on each extension and how to use it, see the [TeachBooks manual](https://teachbooks.io/manual/features/favourites.html#)
|
||||
|
||||
```{note}
|
||||
If you cloned your book from the TeachBooks Template, the TeachBooks-Favourites extension is **already included and activated**.
|
||||
```
|
||||
|
||||
## Customising your favourites
|
||||
|
||||
1. The TeachBooks template contains all the configuration options for all of the extensions included in TeachBooks-Favourites. Open `_config.yml` and scroll to the `sphinx` section to see the options.
|
||||
|
||||
2. If you want to use only some of the included extensions, you can remove `teachbooks_favourites` from `_config.yml` and instead add the specific extensions you need. This gives you full control over which features are loaded. Try this out with the example below:
|
||||
|
||||
```yaml
|
||||
sphinx:
|
||||
extra_extensions:
|
||||
- sphinx_image_inverter
|
||||
- sphinx_iframes
|
||||
- teachbooks_sphinx_tippy
|
||||
```
|
||||
|
||||
```{tip}
|
||||
Start with `teachbooks_favourites` enabled — it’s a great default for beginners. As your project grows, you can refine which extensions stay active.
|
||||
```
|
||||
|
||||
3. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
|
||||
|
||||
4. Add a commit message.
|
||||
|
||||
5. To see your changes, go to {octicon}`play` **Actions** → select the most recent workflow run → wait for it to finish → click the link under *Branches deployed* and *Primary book at root*.
|
||||
|
||||
6. You should see that the accessibility button (from `sphinx_accessibility`) is now gone.
|
||||
|
||||
## Contribute your favourite
|
||||
|
||||
7. Think an extension deserves a place among the favourites? You can contribute by opening an issue on [GitHub](https://github.com/TeachBooks/TeachBooks-Favourites), or add it yourself by submitting a **pull request** that adds it to:
|
||||
|
||||
- `README.md`
|
||||
- `pyproject.toml`
|
||||
- `src/teachbooks_favourites/__init__.py`
|
||||
|
||||
```{note}
|
||||
Extensions must be stable, open-source, and enhance the TeachBooks authoring or learning experience.
|
||||
```
|
||||
|
||||
```{admonition} Check your understanding
|
||||
:class: note
|
||||
|
||||
Before moving on, make sure you can answer:
|
||||
- What is the TeachBooks-Favourites extension?
|
||||
- How do you enable it in `_config.yml`?
|
||||
- What should you do if you only want to load a few of the extensions?
|
||||
```
|
||||
3
book/extensions.md
Normal file
3
book/extensions.md
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
# Extension exercises
|
||||
|
||||
The previous exercises introduced you to the basics of writing content for your TeachBook, as well as getting started with the syntax used. Now let’s explore how you can add functionalities to your book using extensions. TeachBooks created a variety of Sphinx extensions to enhance your book: see [the manual](https://teachbooks.io/manual/features/overview.html) for a complete overview, including [TeachBooks Favourites](https://github.com/TeachBooks/TeachBooks-Favourites) which collects a collection of our favourite Sphinx extensions. The TeachBooks Favourites collection is already included in this template. Furthermore, you can also install third-party extensions to further customize your content.
|
||||
|
|
@ -9,6 +9,13 @@
|
|||
"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"(Click {fa}`rocket` --> {guilabel}`Live Code` to activate live code on this page.)"
|
||||
]
|
||||
},
|
||||
{
|
||||
"cell_type": "code",
|
||||
"execution_count": 1,
|
||||
|
|
|
|||
|
|
@ -4,4 +4,4 @@ The previous exercise guide you through making your own book following the Teach
|
|||
|
||||
As user type 3 you will work primarily in `.md` (Markdown) or `.ipynb`(Jupyter Notebook) files. In Jupyter Book, `.md` files contain text-based content with formatting, while `ipynb` files contain both text and executable code cells. `.md` files are much easier to edit online, so let's start with those!
|
||||
|
||||
The more you write, the more different types of content you'll want to use. [JupyterBook itself provides a cheatsheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) which will come in handy!
|
||||
The more you write, the more different types of content you'll want to use. [JupyterBook itself provides a cheatsheet](https://jupyterbook.org/v1/reference/cheatsheet.html) which will come in handy!
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Exercise 7: File structure by titles
|
||||
# File structure by titles
|
||||
|
||||
In this exercise you will learn how to structure your chapters.
|
||||
|
||||
|
|
@ -8,7 +8,7 @@ Can you structure your page with a title and (sub)sections?
|
|||
|
||||
```{tip}
|
||||
|
||||
More useful Markdown syntax is explained in the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html).
|
||||
More useful Markdown syntax is explained in the [MyST cheat sheet](https://jupyterbook.org/v1/reference/cheatsheet.html).
|
||||
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1,15 +1,18 @@
|
|||
# Exercise 8: Add visual media
|
||||
# Add visual media
|
||||
|
||||
To help you illustrate your content, it can be useful to add some type of visual media such as figures, gifs or videos. If you want to add a figure/gif to your book, you can refer to the URL to that image directly. This is quite handy but it does carry the risk that this figure file will no longer be visible if the location is changed, or if the website is down. Therefore, sometimes it can be better to add the source directly to the book (if done on small scale).
|
||||
|
||||
To help you illustrate your content, it can be useful to add some type of visual media such as figures or gifs. If you want to add a figure/gif to you book, you can refer to the URL to that image directly. This is quite handy but it does carry the risk that this figure file will no longer be visible if the location is changed, or if the website is down. Therefore, sometimes it can be better to add the source directly to the book (if done on small scale).
|
||||
|
||||
::::::{topic} Exercise objective
|
||||
Can you add figures to your page?
|
||||
Can you add figures and videos to your page?
|
||||
::::::
|
||||
|
||||
```{note}
|
||||
Unless you are using a file format like `*.svg`, the raw contents of a visual media file typically are not human-readable or have a binary file format. This is not an ideal file type to use with Git. When just beginning to learn about all the tools associated with a TeachBook, we recommend you keep things simple and do whatever is easiest for you. Note, however, that as your book grows, especially if you use a lot of non-svg images, you may want to find a different way to store them (guidance will be provided on this soon in the TeachBooks Manual---stay tuned!).
|
||||
```
|
||||
|
||||
## Adding figures
|
||||
|
||||
|
||||
1. You will first need to upload your media to the repository. Navigate to the folder called figures (`book/figures`) and make sure you are in the right branch. On the right top, click on `Add file` - {octicon}`upload;1em` `Upload new file`. Note that you can store your files in another folder within the book directory too. However it's good practice to store figures in a separate folder (eventually per chapter).
|
||||
|
||||
|
|
@ -19,7 +22,7 @@ Unless you are using a file format like `*.svg`, the raw contents of a visual me
|
|||
|
||||
4. Now let's add the figure to a chapter. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the same branch as where you've added your figure.
|
||||
|
||||
5. Copy this syntax and adjust the file name, width, alignment and caption (for more options see the [JupyterBook documentation](https://jupyterbook.org/en/stable/content/figures.html#figure-parameters)):
|
||||
5. Copy this syntax and adjust the file name, width, alignment and caption (for more options see the [JupyterBook documentation](https://jupyterbook.org/v1/content/figures.html#figure-parameters)):
|
||||
|
||||
````md
|
||||
```{figure} figures/<new_figure>.png
|
||||
|
|
@ -51,13 +54,25 @@ align: center
|
|||
```
|
||||
````
|
||||
|
||||
6. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
|
||||
|
||||
7. Add a commit message.
|
||||
## Adding videos
|
||||
|
||||
8. To see you changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting).
|
||||
7. You can also embed videos (e.g., from YouTube) into your book using the [`sphinx-iframes`](https://github.com/TeachBooks/sphinx-iframes) extension, which is already part of the TeachBooks template. Try the example below using the `video` directive with a regular YouTube URL:
|
||||
|
||||
|
||||
````md
|
||||
```{video} https://www.youtube.com/watch/B1J6Ou4q8vE
|
||||
```
|
||||
````
|
||||
|
||||
8. When you're ready, commit your changes to the repository by clicking the green `Commit changes` button.
|
||||
|
||||
9. Add a commit message.
|
||||
|
||||
10. To see your changes, go to {octicon}`play;1em` `Actions` – The most recent workflow run (`overview.md` / your commit message) – Wait for it to finish – In the summary, click on the link under `Branches deployed` and under `Primary book at root`.
|
||||
|
||||
11. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
|
||||
|
||||
9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
|
||||
|
||||
```{admonition} Check your understanding
|
||||
:class: note
|
||||
|
|
@ -67,5 +82,4 @@ Before moving on to the next exercise, make sure you understand the following:
|
|||
- What is the recommended practice for storing figures in the book directory?
|
||||
- What should you be cautious about when specifying the file extension of your figure?
|
||||
- How do you refer to a figure located in a different directory than your chapter?
|
||||
|
||||
```
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Exercise 9: Use equations
|
||||
# Use equations
|
||||
|
||||
In this exercise, you will learn how to write and format mathematical equations in your TeachBook, both inline and as standalone blocks.
|
||||
|
||||
|
|
@ -7,7 +7,7 @@ Can you write and format equations correctly in your book?
|
|||
::::::
|
||||
|
||||
```{tip}
|
||||
Using properly formatted equations makes mathematical expressions clearer and more professional. More details can be found in the [JupyterBook documentation](https://jupyterbook.org/en/stable/content/math.html).
|
||||
Using properly formatted equations makes mathematical expressions clearer and more professional. More details can be found in the [JupyterBook documentation](https://jupyterbook.org/v1/content/math.html).
|
||||
```
|
||||
|
||||
## Writing equations
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Exercise 10: Create tables
|
||||
# Create tables
|
||||
|
||||
In this exercise, we will explore how to create and format tables in your TeachBook using Markdown and reStructuredText.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Exercise 11: Cross-referencing content
|
||||
# Cross-referencing content
|
||||
|
||||
In this exercise, you will learn how to create references to other parts of your book, such as chapters, sections, equations, tables and figures, as well as links.
|
||||
|
||||
|
|
@ -7,7 +7,7 @@ Can you create internal references to other sections, equations, tables, figures
|
|||
::::::
|
||||
|
||||
```{tip}
|
||||
Referencing elements properly ensures that readers can navigate your book more easily. More details can be found in the [JupyterBook documentation](https://jupyterbook.org/en/stable/content/references.html).
|
||||
Referencing elements properly ensures that readers can navigate your book more easily. More details can be found in the [JupyterBook documentation](https://jupyterbook.org/v1/content/references.html).
|
||||
```
|
||||
|
||||
## Referencing a Chapter or Section
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Exercise 12: Use admonitions
|
||||
# Use admonitions
|
||||
|
||||
In this exercise, you will learn how to use admonitions to enhance the readability and structure of your TeachBook content. Admonitions are special highlighted blocks that are useful for tips, warnings, notes, and more.
|
||||
|
||||
|
|
|
|||
174
book/syntax_exercises/013.md
Normal file
174
book/syntax_exercises/013.md
Normal file
|
|
@ -0,0 +1,174 @@
|
|||
# Adding a Bibliography
|
||||
|
||||
In this exercise, you will learn how to cite sources using the shared bibliography provided in this template, and how to control the citation style and reference formatting using `{cite}` roles and the `{bibliography}` directive.
|
||||
|
||||
::::::{topic} Exercise objective
|
||||
Can you cite references using different in-line styles and customise the way your bibliography appears?
|
||||
::::::
|
||||
|
||||
```{tip}
|
||||
Citing references properly gives credit to original authors and improves your writing. See the [JupyterBook guide on citations](https://jupyterbook.org/en/stable/content/citations.html) for full details.
|
||||
````
|
||||
|
||||
## Adding an entry to the shared bibliography
|
||||
|
||||
1. The TeachBooks template already includes a shared bibliography file (`references.bib`). Locate and open the file. You will see the following example entry:
|
||||
|
||||
```
|
||||
@misc{jason_moore,
|
||||
title={Learn Multibody Dynamics, SymPy},
|
||||
author={Moore, Jason},
|
||||
howpublished={\url{https://moorepants.github.io/learn-multibody-dynamics/sympy.html}},
|
||||
year={2023}
|
||||
}
|
||||
```
|
||||
|
||||
2. Add a new reference of your own. You can use a DOI, book title, or URL.
|
||||
|
||||
```{tip}
|
||||
You can generate BibTeX entries using free tools like [ZoteroBib](https://zbib.org). Paste a source URL or title, click **Cite**, and export as **BibTeX** to copy into `references.bib`.
|
||||
```
|
||||
|
||||
## Citing sources using `{cite}`
|
||||
|
||||
3. To reference a source in-line, use one of the `{cite}` roles. Try the following:
|
||||
|
||||
```md
|
||||
{cite:p}`jason_moore`
|
||||
```
|
||||
|
||||
4. You can also use other variants of `{cite}` depending on the style you want. Try adding the following to your Markdown file and see how the output differs:
|
||||
|
||||
* `{cite:p}`
|
||||
* `{cite:t}`
|
||||
* `{cite:ps}`
|
||||
* `{cite:ts}`
|
||||
|
||||
```{admonition} What to expect when you render these
|
||||
:class: hint, dropdown
|
||||
Here’s how the citation will appear for the example in the shared bibliography:
|
||||
|
||||
- `{cite:p}` → **Parenthetical citation**
|
||||
→ [Moore, 2023]
|
||||
|
||||
- `{cite:t}` → **Textual citation**
|
||||
→ Moore [2023]
|
||||
|
||||
- `{cite:ps}` → **Parenthetical, full authors**
|
||||
→ [Moore, 2023]
|
||||
|
||||
- `{cite:ts}` → **Textual, full authors**
|
||||
→ Moore [2023]
|
||||
|
||||
```
|
||||
|
||||
## Displaying the bibliography
|
||||
|
||||
5. To show the list of cited references at the end of the page, use the `{bibliography}` directive. In this template, the bibliography is already added to the [page](../references.md):
|
||||
|
||||
````md
|
||||
```{bibliography}
|
||||
```
|
||||
````
|
||||
|
||||
`````{admonition} Avoiding duplicate citation warnings
|
||||
:class: warning
|
||||
|
||||
If you use `{bibliography}` in multiple files, you might see warnings about duplicate citations when building your book. To avoid this, restrict the bibliography to only show references cited in the current page by adding a `:filter:` option:
|
||||
|
||||
````md
|
||||
```{bibliography}
|
||||
:filter: docname in docnames
|
||||
```
|
||||
|
||||
````
|
||||
|
||||
This ensures only local references are shown, and avoids build-time warnings.
|
||||
`````
|
||||
|
||||
|
||||
## Customising citation styles
|
||||
|
||||
|
||||
6. You can change the **reference style** (how citations appear in your text) by editing the `_config.yml` file in your book folder. Add or modify the following section, and see how the referece style changes.
|
||||
|
||||
```yaml
|
||||
sphinx:
|
||||
config:
|
||||
bibtex_reference_style: author_year
|
||||
```
|
||||
|
||||
7. Try replacing `author_year` with the following and see how the citation outputs change:
|
||||
|
||||
* `author_year`
|
||||
* `label`
|
||||
* `super`
|
||||
* `number`
|
||||
|
||||
```{admonition} What each reference style will look like
|
||||
:class: hint, dropdown
|
||||
Heres's how each style will appear for the example in the shared bibliography:
|
||||
|
||||
- `author_year` → Moore (2023)
|
||||
- `label` → [jason_moore]
|
||||
- `super` → ¹
|
||||
- `number` → [1]
|
||||
|
||||
Feeling brave? You can also use APA references, although this is not a default option. More information on to set this up is available in the [TeachBooks manual](https://teachbooks.io/manual/features/apa.html)
|
||||
|
||||
```
|
||||
|
||||
8. You can also change the **bibliography style** (how the reference list is formatted) using the `:style:` option in the `{bibliography}` directive. Try replacing the style with the following, and see how the bibliography style changes.
|
||||
|
||||
````md
|
||||
```{bibliography}
|
||||
:style: unsrt
|
||||
```
|
||||
|
||||
````
|
||||
|
||||
9. Experiment with the following different styles, and see how the bibliography style changes:
|
||||
|
||||
- `alpha`
|
||||
- `plain`
|
||||
- `unsrt`
|
||||
- `unsrtalpha`
|
||||
|
||||
```{admonition} What each bibliography style looks like
|
||||
:class: hint, dropdown
|
||||
Heres's how each style will appear for the example in the shared bibliography:
|
||||
|
||||
- `alpha` → References labelled as [Knu84], sorted by author/year
|
||||
- `plain` → References numbered [1], sorted by author/year
|
||||
- `unsrt` → Numbered [1], in order of appearance in the text
|
||||
- `unsrtalpha` → Alphanumeric like [Knu84], but in order of appearance
|
||||
|
||||
```
|
||||
|
||||
|
||||
```{admonition} Bibliography style vs. Reference style
|
||||
:class: note
|
||||
|
||||
- **Reference style** controls how citations look in your text (e.g., [1] vs. (Author, Year)).
|
||||
- **Bibliography style** controls how the reference list is formatted (e.g., sorted, numbered, APA).
|
||||
```
|
||||
|
||||
10. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
|
||||
|
||||
11. Add a commit message.
|
||||
|
||||
12. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting).
|
||||
|
||||
13. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
|
||||
|
||||
|
||||
```{admonition} Check your understanding
|
||||
:class: note
|
||||
|
||||
Before moving on, make sure you understand:
|
||||
- How to add a new reference to the shared `references.bib` file.
|
||||
- How to use `{cite}` roles to control in-line citation appearance.
|
||||
- How to change the citation style in `_config.yml`.
|
||||
- How to display the bibliography with `{bibliography}`.
|
||||
```
|
||||
|
||||
|
|
@ -1,12 +1,5 @@
|
|||
# first list the packages you wish to download from PyPI
|
||||
teachbooks # depends on jupyter-book
|
||||
jupyterbook-patches
|
||||
sphinx-image-inverter
|
||||
download_link_replacer
|
||||
sphinx-exercise
|
||||
teachbooks-sphinx-tippy
|
||||
sphinx-iframes
|
||||
sphinx-named-colors
|
||||
|
||||
# Now list the packages you want to download directly from GitHub
|
||||
git+https://github.com/TeachBooks/Sphinx-Thebe
|
||||
# Our favourite Sphinx extensions in one line, replace with individual extensions if you prefer some extensions not to be included (https://github.com/TeachBooks/TeachBooks-Favourites)
|
||||
git+https://github.com/TeachBooks/TeachBooks-Favourites
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue