mirror of
https://github.com/TeachBooks/manual.git
synced 2026-11-12 22:35:51 +00:00
Compare commits
No commits in common. "release" and "v1.1.1" have entirely different histories.
138 changed files with 1854 additions and 5191 deletions
2
.github/workflows/call-deploy-book.yml
vendored
2
.github/workflows/call-deploy-book.yml
vendored
|
|
@ -5,7 +5,7 @@ on:
|
|||
branches:
|
||||
- '**'
|
||||
# - '!dependabot**'
|
||||
# If your git repository has the 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.
|
||||
#
|
||||
|
|
|
|||
5
.gitignore
vendored
5
.gitignore
vendored
|
|
@ -137,7 +137,4 @@ _output/
|
|||
book/.jupyterlite.doit.db
|
||||
|
||||
# TeachBooks
|
||||
**.teachbooks/
|
||||
book/_toc_with_local_paths.yml
|
||||
book/_git/
|
||||
book/conf.py
|
||||
**.teachbooks/
|
||||
16
.gitmodules
vendored
16
.gitmodules
vendored
|
|
@ -18,6 +18,10 @@
|
|||
path = book/external/Sphinx-Image-Inverter
|
||||
url = https://github.com/TeachBooks/Sphinx-Image-Inverter.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
|
||||
|
|
@ -46,15 +50,3 @@
|
|||
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
|
||||
|
|
|
|||
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
|
||||
|
|
@ -1,16 +1,15 @@
|
|||
# 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.io/](https://teachbooks.io/).
|
||||
|
||||
## Contact
|
||||
If you encounter any issues and you have a TU Delft account, report it by clicking the github icon and lightbulb on the top right corner of this page. Or contribute directly by creating a merge request in the [repository](https://github.com/Teachbooks/manual).
|
||||
If you encounter any issues and you have a TU Delft account, report it by clicking the gitlab icon and lightbulb on the top right corner of this page. Or contribute directly by creating a merge request in the [repository](https://github.com/Teachbooks/manual).
|
||||
|
||||
If you have questions, contact the TeachBooks Development Team at info@teackbooks.io, also for non-TU Delft account holders. You can also contact us in our [GitHub discussions](https://github.com/orgs/TeachBooks/discussions)
|
||||
|
||||
We really value your feedback on this manual. This helps us improving it. Please keep using the manual as you build your own 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.
|
||||
|
|
@ -20,4 +19,3 @@ The released book can be found on on https://teachbooks.io/manual. This page sho
|
|||
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`
|
||||
|
||||
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,8 +1,8 @@
|
|||
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, 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>
|
||||
|
||||
execute:
|
||||
execute_notebooks: 'auto'
|
||||
execute_notebooks: 'off'
|
||||
|
||||
only_build_toc_files: true
|
||||
|
||||
|
|
@ -14,11 +14,14 @@ sphinx:
|
|||
extra_extensions:
|
||||
- sphinx_inline_tabs
|
||||
- sphinx.ext.imgconverter
|
||||
- teachbooks_favourites
|
||||
- download_link_replacer
|
||||
- jupyterbook_patches
|
||||
- teachbooks_sphinx_grasple
|
||||
- sphinx_apa_references
|
||||
- sphinx_image_inverter
|
||||
- sphinx_exercise
|
||||
- sphinx_proof
|
||||
- sphinx_named_colors
|
||||
config:
|
||||
language: en
|
||||
html_js_files:
|
||||
- https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js
|
||||
thebe_config:
|
||||
|
|
@ -40,23 +43,17 @@ sphinx:
|
|||
html_show_copyright: false
|
||||
html_last_updated_fmt: '%B %-d, %Y'
|
||||
html_static_path: ["images"]
|
||||
bibtex_default_style: myapastyle
|
||||
bibtex_reference_style: author_year_round
|
||||
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
|
||||
named_colors_custom_colors: {'onlylight':[165,21,160],'lightanddark':[45,180,117,204,158,110],'hyphen-color':[45,180,117,165,21,160]}
|
||||
local_extensions:
|
||||
apastyle: _ext/
|
||||
bracket_citation_style: _ext/
|
||||
|
||||
teachbooks:
|
||||
attribution_location: margin
|
||||
attribution_color: attributiongrey
|
||||
|
||||
bibtex_bibfiles:
|
||||
- references.bib
|
||||
|
|
|
|||
17
book/_ext/apastyle.py
Normal file
17
book/_ext/apastyle.py
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
|
||||
# from pybtex.style.formatting.unsrt import Style
|
||||
from pybtexapastyle.formatting.apa import APAStyle
|
||||
from pybtexapastyle.labels.apa import LabelStyle as APALabelStyle
|
||||
from pybtex.plugin import register_plugin
|
||||
# from pybtex.style.template import names, sentence
|
||||
|
||||
class MyAPALabelStyle(APALabelStyle):
|
||||
def format_label(self, entry):
|
||||
return APALabelStyle.format_label(self, entry)
|
||||
|
||||
class MyAPAStyle(APAStyle):
|
||||
default_label_style = 'myapa'
|
||||
|
||||
def setup(app):
|
||||
register_plugin('pybtex.style.labels', 'myapa', MyAPALabelStyle)
|
||||
register_plugin('pybtex.style.formatting', 'myapastyle', MyAPAStyle)
|
||||
27
book/_ext/bracket_citation_style.py
Normal file
27
book/_ext/bracket_citation_style.py
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
from dataclasses import dataclass, field
|
||||
import sphinxcontrib.bibtex.plugin
|
||||
|
||||
from sphinxcontrib.bibtex.style.referencing import BracketStyle
|
||||
from sphinxcontrib.bibtex.style.referencing.author_year import AuthorYearReferenceStyle
|
||||
|
||||
|
||||
def bracket_style() -> BracketStyle:
|
||||
return BracketStyle(
|
||||
left='(',
|
||||
right=')',
|
||||
)
|
||||
|
||||
|
||||
@dataclass
|
||||
class MyReferenceStyle(AuthorYearReferenceStyle):
|
||||
bracket_parenthetical: BracketStyle = field(default_factory=bracket_style)
|
||||
bracket_textual: BracketStyle = field(default_factory=bracket_style)
|
||||
bracket_author: BracketStyle = field(default_factory=bracket_style)
|
||||
bracket_label: BracketStyle = field(default_factory=bracket_style)
|
||||
bracket_year: BracketStyle = field(default_factory=bracket_style)
|
||||
|
||||
|
||||
def setup(app):
|
||||
sphinxcontrib.bibtex.plugin.register_plugin(
|
||||
'sphinxcontrib.bibtex.style.referencing',
|
||||
'author_year_round', MyReferenceStyle)
|
||||
21
book/_ext/pybtexapastyle/LICENSE
Normal file
21
book/_ext/pybtexapastyle/LICENSE
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
MIT License
|
||||
|
||||
Copyright (c) 2018 Naeka
|
||||
|
||||
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.
|
||||
0
book/_ext/pybtexapastyle/formatting/__init__.py
Normal file
0
book/_ext/pybtexapastyle/formatting/__init__.py
Normal file
486
book/_ext/pybtexapastyle/formatting/apa.py
Normal file
486
book/_ext/pybtexapastyle/formatting/apa.py
Normal file
|
|
@ -0,0 +1,486 @@
|
|||
# -*- coding:Utf-8 -*-
|
||||
from __future__ import unicode_literals
|
||||
|
||||
import re
|
||||
import six
|
||||
|
||||
from pybtex.plugin import find_plugin
|
||||
from pybtex.style.formatting import BaseStyle, toplevel
|
||||
from pybtex.style.template import (
|
||||
field, first_of, href, join, optional, optional_field, sentence, tag,
|
||||
together, words, node, FieldIsMissing
|
||||
)
|
||||
|
||||
from pybtex.richtext import Text, Symbol
|
||||
|
||||
|
||||
firstlast = find_plugin('pybtex.style.names', 'lastfirst')()
|
||||
|
||||
if six.PY2:
|
||||
def format_pages(text):
|
||||
dash_re = re.compile(r'-+')
|
||||
pages = Text(Symbol('ndash')).join(
|
||||
re.split(dash_re, six.text_type(text)))
|
||||
if re.search('[-‒–—―]', six.text_type(text)):
|
||||
return Text("pp.", Symbol('nbsp'), pages)
|
||||
return Text("p.", Symbol('nbsp'), pages)
|
||||
else:
|
||||
def format_pages(text):
|
||||
dash_re = re.compile(r'-+')
|
||||
pages = Text(Symbol('ndash')).join(text.split(dash_re))
|
||||
if re.search('[-‒–—―]', str(text)):
|
||||
return Text("pp.", Symbol('nbsp'), pages)
|
||||
return Text("p.", Symbol('nbsp'), pages)
|
||||
|
||||
|
||||
pages = field('pages', apply_func=format_pages)
|
||||
date = words[field('year'), optional[", ", field('month')]]
|
||||
|
||||
|
||||
@node
|
||||
def apa_names(children, context, role, **kwargs):
|
||||
"""
|
||||
Returns formatted names as an APA compliant reference list citation.
|
||||
"""
|
||||
assert not children
|
||||
|
||||
try:
|
||||
persons = context['entry'].persons[role]
|
||||
except KeyError:
|
||||
raise FieldIsMissing(role, context['entry'])
|
||||
|
||||
style = context['style']
|
||||
|
||||
if len(persons) > 7:
|
||||
persons = persons[:6] + persons[-1:]
|
||||
formatted_names = [style.format_name(
|
||||
person, style.abbreviate_names) for person in persons]
|
||||
return join(sep=', ', last_sep=', … ')[
|
||||
formatted_names].format_data(context)
|
||||
else:
|
||||
formatted_names = [style.format_name(
|
||||
person, style.abbreviate_names) for person in persons]
|
||||
return join(sep=', ', sep2=', & ', last_sep=', & ')[
|
||||
formatted_names].format_data(context)
|
||||
|
||||
|
||||
@node
|
||||
def editor_names(children, context, with_suffix=True, **kwargs):
|
||||
"""
|
||||
Returns formatted editor names for inbook.
|
||||
"""
|
||||
assert not children
|
||||
|
||||
try:
|
||||
editors = context['entry'].persons['editor']
|
||||
except KeyError:
|
||||
raise FieldIsMissing('editor', context['entry'])
|
||||
|
||||
formatted_names = [
|
||||
firstlast.format(editor, True) for editor in editors]
|
||||
|
||||
if with_suffix:
|
||||
return words[
|
||||
join(sep=', ', sep2=', & ', last_sep=', & ')[formatted_names],
|
||||
"(Eds.)" if len(editors) > 1 else "(Ed.)"
|
||||
].format_data(context)
|
||||
|
||||
return join(sep=', ', sep2=', & ', last_sep=', & ')[
|
||||
formatted_names
|
||||
].format_data(context)
|
||||
|
||||
|
||||
class APAStyle(BaseStyle):
|
||||
name = 'apa'
|
||||
default_name_style = 'lastfirst'
|
||||
default_sorting_style = 'author_year_title'
|
||||
default_label_style = 'apa'
|
||||
|
||||
def __init__(self, *args, **kwargs):
|
||||
super(APAStyle, self).__init__(*args, **kwargs)
|
||||
self.abbreviate_names = True
|
||||
|
||||
def format_names(self, role, as_sentence=True):
|
||||
formatted_names = apa_names(role)
|
||||
if as_sentence:
|
||||
return sentence(capfirst=False)[formatted_names]
|
||||
else:
|
||||
return formatted_names
|
||||
|
||||
def format_author_or_editor_and_date(self, e):
|
||||
if 'author' in e.persons and 'editor' in e.persons:
|
||||
return sentence(sep=' ')[
|
||||
self.format_names('author'), join["(", date, ")."],
|
||||
self.format_editor(e, as_sentence=False)]
|
||||
elif 'author' in e.persons:
|
||||
return sentence(sep=' ')[
|
||||
self.format_names('author'), join["(", date, ")"]]
|
||||
else:
|
||||
return sentence(sep=' ')[
|
||||
self.format_editor(e, as_sentence=False),
|
||||
join["(", date, ")"]]
|
||||
|
||||
def format_editor(self, e, as_sentence=True):
|
||||
editors = self.format_names('editor', as_sentence=False)
|
||||
if 'editor' not in e.persons:
|
||||
# when parsing the template, a FieldIsMissing exception
|
||||
# will be thrown anyway; no need to do anything now,
|
||||
# just return the template that will throw the exception
|
||||
return editors
|
||||
if len(e.persons['editor']) > 1:
|
||||
word = '(Eds.)'
|
||||
else:
|
||||
word = '(Ed.)'
|
||||
result = join(sep=' ')[editors, word]
|
||||
if as_sentence:
|
||||
return sentence[result]
|
||||
else:
|
||||
return result
|
||||
|
||||
def format_volume(self, e, for_article=False):
|
||||
prefix = "Vol."
|
||||
if for_article:
|
||||
return join[
|
||||
tag('em')[field('volume')],
|
||||
optional['(', field('number'), ')'],
|
||||
]
|
||||
else:
|
||||
return optional[together[prefix, field('volume')]]
|
||||
|
||||
def format_title(self, e, which_field, as_sentence=True):
|
||||
formatted_title = field(
|
||||
which_field, apply_func=lambda text: text.capitalize()
|
||||
)
|
||||
if as_sentence:
|
||||
return sentence[formatted_title]
|
||||
else:
|
||||
return formatted_title
|
||||
|
||||
def format_btitle(self, e, which_field, as_sentence=True):
|
||||
formatted_title = tag('em')[field(which_field)]
|
||||
if as_sentence:
|
||||
return sentence[formatted_title]
|
||||
else:
|
||||
return formatted_title
|
||||
|
||||
def format_web_refs(self, e):
|
||||
# Based on urlbst output.web.refs
|
||||
return sentence(add_period=False)[
|
||||
optional[self.format_url(e)],
|
||||
optional[self.format_eprint(e)],
|
||||
optional[self.format_pubmed(e)],
|
||||
optional[self.format_doi(e)],
|
||||
]
|
||||
|
||||
def format_url(self, e):
|
||||
# Based on urlbst format.url
|
||||
return words[
|
||||
'URL:',
|
||||
href[
|
||||
field('url', raw=True),
|
||||
field('url', raw=True)
|
||||
]
|
||||
]
|
||||
|
||||
def format_pubmed(self, e):
|
||||
# Based on urlbst format.pubmed
|
||||
return href[
|
||||
join[
|
||||
'https://www.ncbi.nlm.nih.gov/pubmed/',
|
||||
field('pubmed', raw=True)
|
||||
],
|
||||
join[
|
||||
'PMID:',
|
||||
field('pubmed', raw=True)
|
||||
]
|
||||
]
|
||||
|
||||
def format_doi(self, e):
|
||||
# Based on urlbst format.doi
|
||||
return href[
|
||||
join[
|
||||
'https://doi.org/',
|
||||
field('doi', raw=True)
|
||||
],
|
||||
join[
|
||||
'doi:',
|
||||
field('doi', raw=True)
|
||||
]
|
||||
]
|
||||
|
||||
def format_eprint(self, e):
|
||||
# Based on urlbst format.eprint
|
||||
return href[
|
||||
join[
|
||||
'https://arxiv.org/abs/',
|
||||
field('eprint', raw=True)
|
||||
],
|
||||
join[
|
||||
'arXiv:',
|
||||
field('eprint', raw=True)
|
||||
]
|
||||
]
|
||||
|
||||
def get_article_template(self, e):
|
||||
# Required fields: author, title, journal, year
|
||||
# Optional fields: volume, number, pages, month, note, key
|
||||
volume_and_pages = first_of[
|
||||
# Volume and pages, with optional issue number
|
||||
optional[
|
||||
join[
|
||||
self.format_volume(e, for_article=True),
|
||||
optional[', ', field('pages')]
|
||||
],
|
||||
],
|
||||
# Pages only
|
||||
pages,
|
||||
]
|
||||
template = toplevel[
|
||||
self.format_names('author'),
|
||||
sentence[
|
||||
join["(", date, ")"]
|
||||
],
|
||||
self.format_title(e, 'title'),
|
||||
sentence[
|
||||
tag('em')[field('journal')],
|
||||
optional[volume_and_pages],
|
||||
],
|
||||
sentence[optional_field('note')],
|
||||
self.format_web_refs(e),
|
||||
]
|
||||
return template
|
||||
|
||||
def get_book_template(self, e):
|
||||
# Required fields: author/editor, title, publisher, year
|
||||
# Optional fields: volume, series, address, edition, month, note, key,
|
||||
# isbn
|
||||
return toplevel[
|
||||
self.format_author_or_editor_and_date(e),
|
||||
sentence(sep=' ')[
|
||||
self.format_btitle(e, 'title'),
|
||||
optional[
|
||||
sentence[
|
||||
optional[field('edition'), ' ed.'],
|
||||
self.format_volume(e),
|
||||
]
|
||||
]
|
||||
],
|
||||
sentence(sep=': ')[
|
||||
optional_field('address'),
|
||||
field('publisher'),
|
||||
],
|
||||
sentence[optional_field('note')],
|
||||
]
|
||||
|
||||
def get_booklet_template(self, e):
|
||||
# Required fields: title
|
||||
# Optional fields: author, howpublished, address, month, year, note,
|
||||
# key
|
||||
return toplevel[
|
||||
sentence(sep=' ')[
|
||||
first_of[
|
||||
optional[self.format_names(
|
||||
'author', as_sentence=False)],
|
||||
"None to claim their bones"
|
||||
],
|
||||
join["(", first_of[optional[date], "n.d."], ")"]
|
||||
],
|
||||
self.format_title(e, 'title'),
|
||||
sentence[optional_field('address')],
|
||||
sentence[optional_field('note')],
|
||||
]
|
||||
|
||||
def get_inbook_template(self, e):
|
||||
# Required fields: author/editor, title, chapter/pages, publisher, year
|
||||
# Optional fields: volume, series, address, edition, month, note, key
|
||||
return toplevel[
|
||||
sentence(sep=' ')[
|
||||
self.format_names('author'),
|
||||
join["(", date, ")"]
|
||||
],
|
||||
self.format_title(e, 'title'),
|
||||
sentence(sep=' ')[
|
||||
optional[
|
||||
"In ",
|
||||
editor_names(),
|
||||
","
|
||||
],
|
||||
self.format_btitle(e, 'booktitle', as_sentence=False),
|
||||
optional[
|
||||
join[
|
||||
"(",
|
||||
sentence(add_period=False)[
|
||||
optional[field('edition'), ' ed.'],
|
||||
self.format_volume(e),
|
||||
pages,
|
||||
],
|
||||
")"
|
||||
]
|
||||
]
|
||||
],
|
||||
sentence(sep=': ')[
|
||||
optional_field('address'),
|
||||
field('publisher'),
|
||||
],
|
||||
sentence[optional_field('note')],
|
||||
]
|
||||
|
||||
def get_incollection_template(self, e):
|
||||
# Required fields: author, title, booktitle, year
|
||||
# Optional fields: editor, pages, organization, publisher, address,
|
||||
# month, note, key
|
||||
return toplevel[
|
||||
self.format_author_or_editor_and_date(e),
|
||||
self.format_title(e, 'title'),
|
||||
sentence(sep=' ')[
|
||||
self.format_btitle(e, 'booktitle', as_sentence=False),
|
||||
optional["(", pages, ")"]
|
||||
],
|
||||
sentence(sep=': ')[
|
||||
optional_field('address'),
|
||||
optional_field('publisher'),
|
||||
],
|
||||
sentence[optional_field('note')],
|
||||
]
|
||||
|
||||
def get_inproceedings_template(self, e):
|
||||
# Required fields: author, title, booktitle, year
|
||||
# Optional fields: editor, pages, organization, publisher, address,
|
||||
# month, note, key
|
||||
return toplevel[
|
||||
self.format_author_or_editor_and_date(e),
|
||||
self.format_title(e, 'title'),
|
||||
sentence(sep=' ')[
|
||||
self.format_btitle(e, 'booktitle', as_sentence=False),
|
||||
optional["(", pages, ")"]
|
||||
],
|
||||
sentence(sep=': ')[
|
||||
optional_field('address'),
|
||||
optional_field('publisher'),
|
||||
],
|
||||
sentence[optional_field('note')],
|
||||
self.format_web_refs(e)
|
||||
]
|
||||
|
||||
def get_manual_template(self, e):
|
||||
# Required fields: title
|
||||
# Optional fields: author, organization, address, edition, month, year,
|
||||
# note, key
|
||||
return toplevel[
|
||||
sentence(sep=' ')[
|
||||
first_of[
|
||||
optional[self.format_names('author', as_sentence=False)],
|
||||
optional_field('organization'),
|
||||
"None to claim their bones"
|
||||
],
|
||||
join["(", first_of[optional[date], "n.d."], ")"]
|
||||
],
|
||||
self.format_btitle(e, 'title'),
|
||||
sentence[optional_field('address')],
|
||||
sentence[optional_field('note')],
|
||||
self.format_web_refs(e)
|
||||
]
|
||||
|
||||
def get_mastersthesis_template(self, e):
|
||||
# Required fields: author, title, school, year
|
||||
# Optional fields: address, month, note, key
|
||||
return toplevel[
|
||||
sentence(sep=' ')[
|
||||
self.format_names('author'),
|
||||
join["(", date, ")"]
|
||||
],
|
||||
sentence(sep=' ')[
|
||||
self.format_btitle(e, 'title', as_sentence=False),
|
||||
"(Master's thesis)"
|
||||
],
|
||||
sentence[
|
||||
field('school'),
|
||||
optional_field('address'),
|
||||
],
|
||||
sentence[optional_field('note')],
|
||||
]
|
||||
|
||||
def get_misc_template(self, e):
|
||||
# Required fields: aucun
|
||||
# Optional fields: author, title, howpublished, month, year, note, key,
|
||||
# type
|
||||
template = toplevel[
|
||||
sentence(sep=' ')[
|
||||
first_of[
|
||||
optional[self.format_names('author', as_sentence=False)],
|
||||
optional_field('publisher'),
|
||||
"None to claim their bones"
|
||||
],
|
||||
join["(", first_of[optional[date], "n.d."], ")"]
|
||||
],
|
||||
optional[self.format_title(e, 'title')],
|
||||
sentence[optional_field('note')],
|
||||
self.format_web_refs(e)
|
||||
]
|
||||
return template
|
||||
|
||||
def get_phdthesis_template(self, e):
|
||||
# Required fields: author, title, school, year
|
||||
# Optional fields: address, month, note, key
|
||||
return toplevel[
|
||||
sentence(sep=' ')[
|
||||
self.format_names('author'),
|
||||
join["(", date, ")"]
|
||||
],
|
||||
sentence(sep=' ')[
|
||||
self.format_btitle(e, 'title', as_sentence=False),
|
||||
"(Doctoral dissertation)"
|
||||
],
|
||||
sentence[
|
||||
field('school'),
|
||||
optional_field('address'),
|
||||
],
|
||||
sentence[optional_field('note')],
|
||||
]
|
||||
|
||||
def get_proceedings_template(self, e):
|
||||
# Required fields: title, year
|
||||
# Optional fields: editor, publisher, organization, address, month,
|
||||
# note, key
|
||||
return toplevel[
|
||||
sentence(sep=' ')[
|
||||
first_of[
|
||||
optional[self.format_editor(e, as_sentence=False)],
|
||||
optional_field('organization'),
|
||||
"None to claim their bones"
|
||||
],
|
||||
join["(", first_of[optional[date], "n.d."], ")"]
|
||||
],
|
||||
self.format_btitle(e, 'title'),
|
||||
sentence(sep=': ')[
|
||||
optional_field('address'),
|
||||
optional_field('publisher'),
|
||||
],
|
||||
sentence[optional_field('note')],
|
||||
]
|
||||
|
||||
def get_techreport_template(self, e):
|
||||
# Required fields: author, title, institution, year
|
||||
# Optional fields: type, number, address, month, note, key
|
||||
return toplevel[
|
||||
sentence(sep=' ')[
|
||||
self.format_names('author', as_sentence=False),
|
||||
join["(", date, ")"]
|
||||
],
|
||||
self.format_btitle(e, 'title'),
|
||||
sentence[field('institution')],
|
||||
sentence[optional_field('note')],
|
||||
]
|
||||
|
||||
def get_unpublished_template(self, e):
|
||||
# Required fields: author, title, note
|
||||
# Optional fields: month, year, key
|
||||
template = toplevel[
|
||||
sentence(sep=' ')[
|
||||
self.format_names('author', as_sentence=False),
|
||||
join["(", first_of[optional[date], "n.d."], ")"]
|
||||
],
|
||||
self.format_btitle(e, 'title'),
|
||||
sentence[field('note')],
|
||||
]
|
||||
return template
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
from __future__ import unicode_literals
|
||||
|
||||
from pybtex.style import FormattedEntry, FormattedBibliography
|
||||
from pybtex.style.template import node, join
|
||||
from pybtex.richtext import Symbol
|
||||
from pybtex.plugin import Plugin, find_plugin
|
||||
|
||||
|
||||
@node
|
||||
def toplevel(children, data):
|
||||
return join(sep=Symbol('newblock')) [children].format_data(data)
|
||||
|
||||
|
||||
class BaseStyle(Plugin):
|
||||
"""
|
||||
The base class for pythonic formatting styles.
|
||||
"""
|
||||
|
||||
default_name_style = None
|
||||
default_label_style = None
|
||||
default_sorting_style = None
|
||||
|
||||
def __init__(self, label_style=None, name_style=None, sorting_style=None, abbreviate_names=False, min_crossrefs=2, **kwargs):
|
||||
self.name_style = find_plugin('pybtex.style.names', name_style or self.default_name_style)()
|
||||
self.label_style = find_plugin('pybtex.style.labels', label_style or self.default_label_style)()
|
||||
self.sorting_style = find_plugin('pybtex.style.sorting', sorting_style or self.default_sorting_style)()
|
||||
self.format_name = self.name_style.format
|
||||
self.format_labels = self.label_style.format_labels
|
||||
self.sort = self.sorting_style.sort
|
||||
self.abbreviate_names = abbreviate_names
|
||||
self.min_crossrefs = min_crossrefs
|
||||
|
||||
def format_entries(self, entries, bib_data=None):
|
||||
sorted_entries = self.sort(entries)
|
||||
labels = self.format_labels(sorted_entries)
|
||||
for label, entry in zip(labels, sorted_entries):
|
||||
yield self.format_entry(label, entry, bib_data=bib_data)
|
||||
|
||||
def format_entry(self, label, entry, bib_data=None):
|
||||
context = {
|
||||
'entry': entry,
|
||||
'style': self,
|
||||
'bib_data': bib_data,
|
||||
}
|
||||
try:
|
||||
get_template = getattr(self, 'get_{}_template'.format(entry.type))
|
||||
except AttributeError:
|
||||
format_method = getattr(self, "format_" + entry.type)
|
||||
text = format_method(context)
|
||||
else:
|
||||
text = get_template(entry).format_data(context)
|
||||
return FormattedEntry(entry.key, text, label)
|
||||
|
||||
def format_bibliography(self, bib_data, citations=None):
|
||||
"""
|
||||
Format bibliography entries with the given keys and return a
|
||||
``FormattedBibliography`` object.
|
||||
|
||||
:param bib_data: A :py:class:`pybtex.database.BibliographyData` object.
|
||||
:param citations: A list of citation keys.
|
||||
"""
|
||||
|
||||
if citations is None:
|
||||
citations = list(bib_data.entries.keys())
|
||||
citations = bib_data.add_extra_citations(citations, self.min_crossrefs)
|
||||
entries = [bib_data.entries[key] for key in citations]
|
||||
formatted_entries = self.format_entries(entries)
|
||||
formatted_bibliography = FormattedBibliography(formatted_entries, style=self, preamble=bib_data.preamble)
|
||||
return formatted_bibliography
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
from __future__ import unicode_literals
|
||||
|
||||
|
||||
from pybtex.plugin import Plugin
|
||||
|
||||
|
||||
class BaseSortingStyle(Plugin):
|
||||
def sorting_key(self, entry):
|
||||
raise NotImplementedError
|
||||
|
||||
def sort(self, entries):
|
||||
return sorted(entries, key=self.sorting_key)
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
from __future__ import unicode_literals
|
||||
|
||||
from pybtex.style.sorting import BaseSortingStyle
|
||||
|
||||
class SortingStyle(BaseSortingStyle):
|
||||
|
||||
def sorting_key(self, entry):
|
||||
if entry.type in ('book', 'inbook'):
|
||||
author_key = self.author_editor_key(entry)
|
||||
elif 'author' in entry.persons:
|
||||
author_key = self.persons_key(entry.persons['author'])
|
||||
else:
|
||||
author_key = ''
|
||||
return (author_key, entry.fields.get('year', ''), entry.fields.get('title', ''))
|
||||
|
||||
def persons_key(self, persons):
|
||||
return ' '.join(self.person_key(person) for person in persons)
|
||||
|
||||
def person_key(self, person):
|
||||
if person.prelast_names[0] != '{' and person.last_names[0] != '{' and person.first_names[0] != '{':
|
||||
return ' '.join((
|
||||
' '.join(person.prelast_names + person.last_names),
|
||||
' '.join(person.first_names + person.middle_names),
|
||||
' '.join(person.lineage_names),
|
||||
)).lower()
|
||||
else:
|
||||
return ' '.join((
|
||||
' '.join(person.first_names + person.middle_names),
|
||||
' '.join(person.prelast_names + person.last_names),
|
||||
' '.join(person.lineage_names),
|
||||
)).lower()
|
||||
|
||||
def author_editor_key(self, entry):
|
||||
if entry.persons.get('author'):
|
||||
return self.persons_key(entry.persons['author'])
|
||||
elif entry.persons.get('editor'):
|
||||
return self.persons_key(entry.persons['editor'])
|
||||
else:
|
||||
return ''
|
||||
0
book/_ext/pybtexapastyle/labels/__init__.py
Normal file
0
book/_ext/pybtexapastyle/labels/__init__.py
Normal file
67
book/_ext/pybtexapastyle/labels/apa.py
Normal file
67
book/_ext/pybtexapastyle/labels/apa.py
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
# -*- coding:Utf-8 -*-
|
||||
from __future__ import unicode_literals
|
||||
|
||||
from collections import Counter
|
||||
import re
|
||||
import unicodedata
|
||||
|
||||
from pybtex.style.labels import BaseLabelStyle
|
||||
|
||||
|
||||
_nonalnum_pattern = re.compile('[^A-Za-z0-9 \-]+', re.UNICODE)
|
||||
|
||||
|
||||
def _strip_accents(s):
|
||||
return "".join(
|
||||
(c for c in unicodedata.normalize('NFD', s)
|
||||
if not unicodedata.combining(c)))
|
||||
|
||||
|
||||
def _strip_nonalnum(parts):
|
||||
"""Strip all non-alphanumerical characters from a list of strings.
|
||||
|
||||
>>> print(_strip_nonalnum([u"ÅA. B. Testing 12+}[.@~_", u" 3%"]))
|
||||
AABTesting123
|
||||
"""
|
||||
s = "".join(parts)
|
||||
return _nonalnum_pattern.sub("", _strip_accents(s))
|
||||
|
||||
|
||||
class LabelStyle(BaseLabelStyle):
|
||||
def format_labels(self, sorted_entries):
|
||||
labels = [self.format_label(entry) for entry in sorted_entries]
|
||||
count = Counter(labels)
|
||||
counted = Counter()
|
||||
for label in labels:
|
||||
if count[label] == 1:
|
||||
yield label
|
||||
else:
|
||||
yield label # + chr(ord('a') + counted[label])
|
||||
# counted.update([label])
|
||||
|
||||
def format_label(self, entry):
|
||||
label = "Anonymous"
|
||||
if 'author' in entry.persons:
|
||||
label = self.format_author_or_editor_names(entry.persons['author'])
|
||||
elif 'editor' in entry.persons:
|
||||
label = self.format_author_or_editor_names(entry.persons['editor'])
|
||||
elif 'organization' in entry.fields:
|
||||
label = entry.fields['organization']
|
||||
if label.startswith("The "):
|
||||
label = label[4:]
|
||||
return ''
|
||||
# if 'year' in entry.fields:
|
||||
# return "{}, {}".format(label, entry.fields['year'])
|
||||
# else:
|
||||
# return "{}, n.d.".format(label)
|
||||
|
||||
def format_author_or_editor_names(self, persons):
|
||||
if len(persons)==1:
|
||||
return _strip_nonalnum(persons[0].last_names)
|
||||
elif len(persons)==2:
|
||||
return "{} & {}".format(
|
||||
_strip_nonalnum(persons[0].last_names),
|
||||
_strip_nonalnum(persons[1].last_names))
|
||||
else:
|
||||
return "{} et al.".format(
|
||||
_strip_nonalnum(persons[0].last_names))
|
||||
0
book/_ext/pybtexapastyle/names/__init__.py
Normal file
0
book/_ext/pybtexapastyle/names/__init__.py
Normal file
39
book/_ext/pybtexapastyle/names/firstlast.py
Normal file
39
book/_ext/pybtexapastyle/names/firstlast.py
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
# -*- coding:Utf-8 -*-
|
||||
from __future__ import unicode_literals
|
||||
|
||||
from pybtex.style.names import BaseNameStyle, name_part
|
||||
from pybtex.style.template import join
|
||||
|
||||
|
||||
class NameStyle(BaseNameStyle):
|
||||
|
||||
def format(self, person, abbr=False):
|
||||
r"""
|
||||
Format names similarly to {vv~}{ll}{, jj}{, f.} in BibTeX.
|
||||
|
||||
>>> from pybtex.database import Person
|
||||
>>> name = Person(string=r"Charles Louis Xavier Joseph de la Vall{\'e}e Poussin")
|
||||
>>> firstlast = NameStyle().format
|
||||
|
||||
>>> print(firstlast(name).format().render_as('latex'))
|
||||
Charles Louis Xavier~Joseph de~la Vall{é}e~Poussin
|
||||
>>> print(firstlast(name).format().render_as('html'))
|
||||
Charles Louis Xavier Joseph de la Vall<span class="bibtex-protected">é</span>e Poussin
|
||||
|
||||
>>> print(firstlast(name, abbr=True).format().render_as('latex'))
|
||||
C.~L. X.~J. de~la Vall{é}e~Poussin
|
||||
>>> print(firstlast(name, abbr=True).format().render_as('html'))
|
||||
C. L. X. J. de la Vall<span class="bibtex-protected">é</span>e Poussin
|
||||
|
||||
>>> name = Person(first='First', last='Last', middle='Middle')
|
||||
>>> print(firstlast(name).format().render_as('latex'))
|
||||
First~Middle Last
|
||||
>>> print(firstlast(name, abbr=True).format().render_as('latex'))
|
||||
F.~M. Last
|
||||
|
||||
"""
|
||||
return join[
|
||||
name_part(abbr=abbr)[person.rich_first_names + person.rich_middle_names],
|
||||
name_part(before=' ')[person.rich_prelast_names],
|
||||
name_part(before=' ')[person.rich_last_names],
|
||||
]
|
||||
27
book/_ext/pybtexapastyle/setup.py
Normal file
27
book/_ext/pybtexapastyle/setup.py
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
import setuptools
|
||||
|
||||
|
||||
setuptools.setup(
|
||||
name='pybtex-apa-style',
|
||||
version='1.3',
|
||||
author='Naeka',
|
||||
author_email='contact@naeka.fr',
|
||||
description='Pybtex APA-like style',
|
||||
url='https://github.com/naeka/pybtex-apa-style',
|
||||
py_modules=['formatting.apa', 'labels.apa', 'names.firstlast'],
|
||||
entry_points={
|
||||
'pybtex.style.formatting': 'apa = formatting.apa:APAStyle',
|
||||
'pybtex.style.labels': 'apa = labels.apa:LabelStyle',
|
||||
'pybtex.style.names': 'firstlast = names.firstlast:NameStyle',
|
||||
},
|
||||
classifiers=(
|
||||
'Operating System :: OS Independent',
|
||||
'Programming Language :: Python',
|
||||
'Programming Language :: Python :: 2.7',
|
||||
'Programming Language :: Python :: 3',
|
||||
'License :: OSI Approved :: MIT License',
|
||||
'Operating System :: OS Independent',
|
||||
'Topic :: Text Processing :: Markup',
|
||||
'Topic :: Utilities',
|
||||
),
|
||||
)
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
/* Attribution */
|
||||
div.attribution > .admonition-title::after {
|
||||
content: "\f10d";
|
||||
}
|
||||
|
|
@ -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;
|
||||
}
|
||||
134
book/_toc.yml
134
book/_toc.yml
|
|
@ -12,8 +12,6 @@ parts:
|
|||
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
|
||||
|
|
@ -29,11 +27,7 @@ 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/tools
|
||||
- file: installation-and-setup/copyright.md
|
||||
sections:
|
||||
- file: installation-and-setup/copyright/considerations
|
||||
|
|
@ -42,73 +36,6 @@ parts:
|
|||
- 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
|
||||
sections:
|
||||
- file: basic-features/jupyterbook.md
|
||||
|
|
@ -121,17 +48,55 @@ parts:
|
|||
- file: basic-features/badges.md
|
||||
- file: basic-features/banner
|
||||
title: Banner or Announcement
|
||||
- file: features/easy-editing.md
|
||||
sections:
|
||||
- file: external/template/README.md
|
||||
- file: features/teachbooks
|
||||
- file: external/deploy-book-workflow/README.md
|
||||
- file: features/local_server
|
||||
- file: external/Nested-Books/README.md
|
||||
- file: features/update_env
|
||||
- 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/interactive_element.ipynb
|
||||
sections:
|
||||
- file: external/Sphinx-Grasple-public/README.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
|
||||
- file: features/visuals.md
|
||||
sections:
|
||||
- file: external/Sphinx-Image-Inverter/README.md
|
||||
- file: external/JupyterBook-Patches/README.md
|
||||
- file: external/Sphinx-TUDelft-theme/README.md
|
||||
- file: external/teachbooks-sphinx-tippy/README.md
|
||||
- file: features/apa
|
||||
- file: external/Sphinx-Named-Colors/README.md
|
||||
- file: features/students
|
||||
sections:
|
||||
- file: external/annotater/README.md
|
||||
- file: basic-features/hypothesis.md
|
||||
|
||||
- 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
|
||||
chapters:
|
||||
|
|
@ -139,14 +104,13 @@ parts:
|
|||
- file: helper_code/intro.md
|
||||
sections:
|
||||
- file: helper_code/converter.md
|
||||
- file: helper_code/move_images.md
|
||||
- file: external/Useful_python_code/snippit.ipynb
|
||||
- file: external/Useful_python_code/extensionfildownloadreturn.ipynb
|
||||
- file: external/Useful_python_code/figshrinker.ipynb
|
||||
|
||||
- caption: Miscellaneous
|
||||
- caption: Miscallaneous
|
||||
chapters:
|
||||
- file: references.md
|
||||
- file: credits
|
||||
- file: changelog
|
||||
- file: contact
|
||||
- file: contact
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# Badges, Buttons & Icons
|
||||
|
||||
<a href="https://jupyterbook.org/v1/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book 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.
|
||||
<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> provides a range of features which are visually appealing and functional. These elements can enhance the interactivity and visual design of your book, offering additional information or links in a compact and visually engaging way. The badges, buttons and icons are made available through Sphinx and they themselves wrote a [documentation](https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html) about it.
|
||||
|
||||
(my_ref)=
|
||||
## Badges
|
||||
|
|
@ -36,7 +36,7 @@ Here's an overview of all the available colours:
|
|||
|
||||
## Buttons
|
||||
|
||||
Buttons provide a way to create clickable elements that are more attractive than links, for example, to link to key sections of your book such as downloads or external resources. Jupyter-Book 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.
|
||||
Buttons provide a way to create clickable elements that are more attractive than links, for example, to link to key sections of your book such as downloads or external resources. Jupyter-Book supports buttons using Markdown making them highly customizable. It is possible to link to external websites as well as chapters within your book. To link to an external page, use `{button-link}`. `{button-ref}` must be used when linking to a part within your book.
|
||||
|
||||
The basic code syntax for creating a button is as follows:
|
||||
|
||||
|
|
@ -49,13 +49,13 @@ The basic code syntax for creating a button is as follows:
|
|||
:color: primary
|
||||
```
|
||||
```
|
||||
[](../features/overview.md)
|
||||
```{button-ref} feature_overview
|
||||
|
||||
```{button-ref} ../features/overview.md
|
||||
:color: secondary
|
||||
```
|
||||
|
||||
```
|
||||
```{button-ref} feature_overview
|
||||
```{button-ref} ../features/overview.md
|
||||
:color: secondary
|
||||
```
|
||||
```
|
||||
|
|
@ -119,12 +119,12 @@ To add an icon, use the following syntax:
|
|||
|
||||
**1. Image Icons**
|
||||
|
||||
Let's have a look at the first sentence of this chapter again: <a href="https://jupyterbook.org/v1/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book v1"></a> provides a range of features which are visually appealing and functional.
|
||||
Let's have a look at the first sentence of this chapter again: <a href="https://jupyterbook.org/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book"></a> provides a range of features which are visually appealing and functional.
|
||||
|
||||
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.
|
||||
<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> provides a range of features which are visually appealing and functional.
|
||||
```
|
||||
|
||||
**2. SVG Icons**
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Banners and Announcements
|
||||
|
||||
A banner can be added to the top of a 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
|
||||
|
||||
---
|
||||
example 2:including figclass: margin
|
||||
```
|
||||
````
|
||||
```{figure} demo97/demo97_figure1.jpg
|
||||
---
|
||||
figclass: margin
|
||||
width: 50%
|
||||
name: demoexample2
|
||||
|
||||
---
|
||||
example 2:including figclass: margin
|
||||
```
|
||||
````
|
||||
|
||||
<br>
|
||||
|
|
|
|||
|
|
@ -1,13 +1,11 @@
|
|||
````{margin}
|
||||
# Making comments on the website: Hypothesis
|
||||
|
||||
```{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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
# Original Jupyter Book and Sphinx Features
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for [user type 3-5](../installation-and-setup/user_types.md).
|
||||
```
|
||||
````
|
||||
|
||||
# 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. Additionally, this page includes also best-practices.
|
||||
|
|
|
|||
|
|
@ -1,13 +1,11 @@
|
|||
````{margin}
|
||||
# Discussions in your book: Utterances
|
||||
|
||||
```{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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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]
|
||||
|
|
|
|||
|
|
@ -5,13 +5,11 @@ 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:
|
||||
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 after Spring 2025. 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>`]).
|
||||
> `<Primary Author>` (2024), `<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._
|
||||
|
||||
|
|
@ -56,15 +54,13 @@ The following pages are included directly from an external resource and is not e
|
|||
- 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
|
||||
|
||||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
2
book/external/Download-Link-Replacer
vendored
2
book/external/Download-Link-Replacer
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 03feccf6efa55d14da78cf4259cedb8a7585ad91
|
||||
Subproject commit f69e970a8da7d85e5473c7e5f58299a2ee3cf331
|
||||
2
book/external/JupyterBook-Patches
vendored
2
book/external/JupyterBook-Patches
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 99aeda40ae0cfa06eb290ba5c3a6b9b81eb3992d
|
||||
Subproject commit 287fb3f9a198848edd2063792c528c0d3d2a3a75
|
||||
2
book/external/Nested-Books
vendored
2
book/external/Nested-Books
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit c365e770730fb5abb3426b06062e69a3a325b336
|
||||
Subproject commit 365291d0d1ba29c9d032c8ba2ec399b03e5d1176
|
||||
2
book/external/Sphinx-Grasple-public
vendored
2
book/external/Sphinx-Grasple-public
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 0dc28b45ef6184e67b8219bd4494c6f54ad8ccd0
|
||||
Subproject commit f4eff8d1565eaf127898f2fe216cf5208684fb27
|
||||
2
book/external/Sphinx-Image-Inverter
vendored
2
book/external/Sphinx-Image-Inverter
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit ca1280ccadfc17f611b6f411dddb77329710dd85
|
||||
Subproject commit 250103c723aa782bcec785ae3d241cb1ffebd3d0
|
||||
2
book/external/Sphinx-Named-Colors
vendored
2
book/external/Sphinx-Named-Colors
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 1307f44c8d64fb98ce4649f585805666e90ec3aa
|
||||
Subproject commit 2ae6342aa7d1b341d046db10de5b713cdeff4ecb
|
||||
1
book/external/Sphinx-PRIME-applets
vendored
1
book/external/Sphinx-PRIME-applets
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit cf8849136e1303e1a2fa2a8ed7296cde6b3b2d68
|
||||
2
book/external/Sphinx-TUDelft-theme
vendored
2
book/external/Sphinx-TUDelft-theme
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 3815645c5cfef3ebbdc8070e649e4c7331b680e3
|
||||
Subproject commit e4b71f810a66e302243377876f39e1dc4c4a8a6b
|
||||
2
book/external/Sphinx-launch-buttons
vendored
2
book/external/Sphinx-launch-buttons
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 9e70fbca8fb7bacb3e6d9c58349f04d6245082dc
|
||||
Subproject commit 8cfd0ba7ae24c17e51ac0b1924473a908d4062ac
|
||||
2
book/external/Useful_python_code
vendored
2
book/external/Useful_python_code
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit c80863d19f7fde7a452200baa4b4fafe12debc95
|
||||
Subproject commit 7fbdbbf720c27112fb58bcf7826225197e39357b
|
||||
2
book/external/annotater
vendored
2
book/external/annotater
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit d1f41f93ffe87a305956de405dac47daaad3bc69
|
||||
Subproject commit 9340b4e2856b6f2de331c31d2b74bd9dc286d276
|
||||
2
book/external/deploy-book-workflow
vendored
2
book/external/deploy-book-workflow
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit da54eb463cd0bac2a3e78dcce7067b2a81a8c3d1
|
||||
Subproject commit 317a9cc8607f74f29957b28a86450eccba6a4e2c
|
||||
1
book/external/sphinx-iframes
vendored
1
book/external/sphinx-iframes
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit 2bc21b6174b8e7dbd15c862c219bd506e06f9d13
|
||||
2
book/external/teachbooks-sphinx-tippy
vendored
2
book/external/teachbooks-sphinx-tippy
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 6122c67f86a7c9b95f349c80316571e277f0a66b
|
||||
Subproject commit 338ad14d39115c620c57476931ce8fa177cf20d8
|
||||
2
book/external/template
vendored
2
book/external/template
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 1ab90c5092b69aa8e1421e598ff43433bd97a9d8
|
||||
Subproject commit a8958fe48c839729226e1d1765dbf26617cf6c59
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
````{margin}
|
||||
# Interactive HTML/JavaScript elements
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
|
|
@ -6,27 +6,15 @@ 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>
|
||||
BIN
book/features/_ext.zip
Normal file
BIN
book/features/_ext.zip
Normal file
Binary file not shown.
|
|
@ -1,30 +1,16 @@
|
|||
````{margin}
|
||||
{bdg-danger}`iframe`
|
||||
````
|
||||
|
||||
# Adding interactive HTML/JavaScript elements
|
||||
|
||||
{bdg-danger}`iframe`
|
||||
|
||||
In this section, we will discuss how to embed interactive elements created in HTML/JavaScript in a TeachBook. If you are interested in learning how to create these elements yourself, we will discuss an example in the [next article](creating_basic_HTML_elements.md). As an example, let us discuss how to embed an interactive 3D model of a subsurface environment I created:
|
||||
|
||||
```{iframe} ../_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>
|
||||
|
|
|
|||
|
|
@ -1,133 +1,100 @@
|
|||
````{margin}
|
||||
(apa)=
|
||||
# APA References
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 4 and 5.
|
||||
```
|
||||
|
||||
{bdg-primary}`Sphinx Extension`
|
||||
{bdg-primary}`(To be converted into) Sphinx Extension`
|
||||
|
||||
````
|
||||
```{note}
|
||||
This feature is stable but because it relies on a local extension that is part of your book files and _not_ managed as part of a computing environment (e.g., `pip` or `conda`), unknown issues may arise. We would like to convert this feature into an independent Sphinx extension and/or Pybtext plugin. Visit the [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17) to learn more.
|
||||
|
||||
(apa)=
|
||||
# APA References
|
||||
The instructions provided here will work under conventional usage with Jupyter Book (e.g., `jupyter book build book`).
|
||||
|
||||
A temporary fix has also been implemented in the TeachBooks package for use with the Deploy Book Workflow (release mode) (see [release notes from v0.1.0](https://github.com/TeachBooks/TeachBooks/releases/tag/v0.1.0)).
|
||||
```
|
||||
|
||||
## 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?
|
||||
Do you include references in your book, but you're tired of the default options available in Jupyter Book? For example, the square-bracket style of citation and reference, where the first three letters of the name year are combined in a way that seems designed to minimize transparency?
|
||||
|
||||
There is a solution! This extension allows you to have APA formatting in your book.
|
||||
|
||||
## Installation
|
||||
To use APA-references, a set of Python files need to be manually loaded into your book
|
||||
|
||||
To use APA-references, install the [Sphinx-APA-References extension](https://github.com/TeachBooks/Sphinx-APA-References) by following these two steps:
|
||||
**Step 1: files to root directory of your book**
|
||||
|
||||
**Step 1: Install the Package**
|
||||
Download this zip-file [`_ext.zip`](_ext.zip), which contains the necessary files, unzip it and place the contents in the root of your book directory so that it looks like the schematic here:
|
||||
|
||||
Install the module `sphinx-apa-references` package using `pip`:
|
||||
```
|
||||
pip install sphinx-apa-references
|
||||
book
|
||||
├── _ext/
|
||||
│ ├── pybtexapastyle/
|
||||
│ ├── apastyle.py
|
||||
│ ├── bracket_citation_style.py
|
||||
├── _config.yml
|
||||
├── _toc.yml
|
||||
├── requirements.txt
|
||||
├── <book files>
|
||||
```
|
||||
|
||||
|
||||
**Step 2: Add to `requirements.txt`**
|
||||
|
||||
Make sure that the package is included in your project's `requirements.txt` to track the dependency:
|
||||
Add a specific version of `docutils` to your requirements file:
|
||||
```
|
||||
sphinx-apa-references
|
||||
docutils==0.17.1
|
||||
```
|
||||
|
||||
**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):
|
||||
In your `_config.yml` file, add a `bibtex_default_style`, `bybtex_reference_style` and the local extensions `apastyle` and `bracket_citation_style.py`
|
||||
```
|
||||
sphinx:
|
||||
extra_extensions:
|
||||
.
|
||||
.
|
||||
.
|
||||
- sphinx_apa_references
|
||||
.
|
||||
.
|
||||
.
|
||||
bibtex_bibfiles: "<path_to_bib_file>/references.bib"
|
||||
sphinx:
|
||||
config:
|
||||
...
|
||||
bibtex_default_style: myapastyle
|
||||
bibtex_reference_style: author_year_round
|
||||
local_extensions:
|
||||
apastyle: _ext/
|
||||
bracket_citation_style: _ext/
|
||||
...
|
||||
```
|
||||
|
||||
## 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:
|
||||
All references are now made in APA-style. See for example this reference: {cite:t}`jason_moore` which shows up on the [references page](../references.md) too. The form of the citation looks like this:
|
||||
|
||||
```
|
||||
<filename>:<lineno>: WARNING: duplicate label "<authors>, <year>" for keys "<key1>" and "<key2>"
|
||||
{cite:t}`jason_moore`
|
||||
```
|
||||
|
||||
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:
|
||||
Here are three examples for making citations:
|
||||
|
||||
```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.},
|
||||
}
|
||||
| Syntax | Result |
|
||||
| :---: | :---: |
|
||||
|`{cite:t}` | {cite:t}`jason_moore` |
|
||||
|`{cite:p}`| {cite:p}`jason_moore` |
|
||||
|`{cite}`| {cite}`jason_moore` |
|
||||
|
||||
@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.},
|
||||
}
|
||||
For more options on the in-line citation style, see https://jupyterbook.org/en/stable/content/citations.html#change-the-in-line-citation-style.
|
||||
|
||||
```
|
||||
### Known Issues
|
||||
|
||||
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.
|
||||
Two issues are known:
|
||||
- During the build, warning will be raised with `... WARNING: duplicate label for keys ...`. In most cases, these warnings can be ignored. As noted above, the book will not build references properly
|
||||
- In case you have both an `.ipynb` and `.md` version of a file, the `.md` version will always be used whenever this extension is used. This reomved the possibility to show code outputs.
|
||||
|
||||
## 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).
|
||||
Although some customization is possible with the standard Jupyter Book features, [as described here](https://jupyterbook.org/en/stable/content/citations.html#change-the-in-line-citation-style), this extension implements the complete APA style, as well as enforcing round brackets (like this).
|
||||
|
||||
### Previous implementation
|
||||
The need to enforce `docutils==0.17.1` version is the only known solution to the issue where empty brackets `[]` are left on the references page.
|
||||
|
||||
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:
|
||||
## Contribute
|
||||
|
||||
```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
|
||||
```
|
||||
This tool needs to be developed further to make it into a proper sphinx-extension (and/or an independent `pybtext` plugin). The process is described in this [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17). If you've ideas or questions, please reach out to us at info@teachbooks.io!
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -853,4 +850,4 @@ Here is the code for the element above in full:
|
|||
</html>
|
||||
|
||||
|
||||
```
|
||||
```
|
||||
|
|
@ -1,14 +1,12 @@
|
|||
````{margin}
|
||||
# Multilingual book
|
||||
|
||||
```{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.
|
||||
The custom launch button extension allows you to create a customizable button in the top right of your jupyter book.
|
||||
This may have many applications, one of them being that you can create different language versions of the book available for the user.
|
||||
|
||||
This section will explain how to create a "Languages" or " <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" class="bi bi-globe" viewBox="0 0 16 16">
|
||||
|
|
|
|||
|
|
@ -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 +1,8 @@
|
|||
````{margin}
|
||||
# Easy Editing Process
|
||||
|
||||
```{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: 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
|
|
@ -1,27 +1,17 @@
|
|||
````{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 +21,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>
|
||||
|
|
@ -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,16 @@
|
|||
"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 +33,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 +40,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",
|
||||
|
|
@ -90,12 +71,12 @@
|
|||
"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",
|
||||
"sphinx:\n",
|
||||
|
|
@ -119,7 +100,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",
|
||||
|
|
@ -176,19 +157,9 @@
|
|||
"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.io/learn-python/main/Python_Toolbox.html."
|
||||
]
|
||||
}
|
||||
],
|
||||
|
|
|
|||
|
|
@ -1,14 +1,12 @@
|
|||
````{margin}
|
||||
(setup-local-server)=
|
||||
# Local Server to view interactive elements locally
|
||||
|
||||
```{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
|
||||
{bdg-secondary}`Python Package`
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -17,7 +15,7 @@ Technically what is needed to facilitate this during the editing and checking of
|
|||
```{admonition} Why do you need a local server?
|
||||
:class: tip
|
||||
|
||||
A 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.
|
||||
A Jupyter Book is really just a _static website._ This means that all book content _and interactivity_ is available via the (static) files that are provided to you by a webserver when you visit a specific URL. After this initial request, all required files are available in your web browser, however, some features require the request and response protocol to work properly.
|
||||
```
|
||||
|
||||
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>`.
|
||||
|
|
@ -30,7 +28,6 @@ Remember that the browser is serving static files provided by the local server a
|
|||
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:
|
||||
|
|
@ -41,51 +38,6 @@ 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.
|
||||
|
|
@ -140,4 +92,4 @@ A Windows-specific command for the CMD prompt or Powershell is:
|
|||
|
||||
```
|
||||
TASKKILL /IM python.exe /F
|
||||
```
|
||||
```
|
||||
|
|
@ -1,30 +1,25 @@
|
|||
(feature_overview)=
|
||||
# Overview
|
||||
|
||||
As TeachBooks, we collect a suite of existing open-source software so you don't have to! Some of the software is developed with our TA's to improve the learning experience of our students and ease the book-development process for our teachers. As the open-source software landscape changes rapidly, it is essential to keep in contact and share resources amongst ourselves to minimize maintenance and downtime for our book websites and focus on what really matters: teaching!
|
||||
|
||||
Since the list of TeachBook features is getting quite long, we have grouped them in categories:
|
||||
- [Original Jupyter Book 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)
|
||||
- Original Jupyter Book and Sphinx features
|
||||
- Easy editing process
|
||||
- Additional functionality
|
||||
- Book styling
|
||||
- TeachBooks student-view features
|
||||
|
||||
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:
|
||||
Additionally, not all features are built using the same type of sourcecode. For transparency, tags will help differentiate between the different backgrounds of the features:
|
||||
- {bdg-warning}`Javascript overlay`
|
||||
- {bdg-success}`Chrome Extension`
|
||||
- {bdg-white}`GitHub App and Javascript script`
|
||||
- {bdg-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-secondary}`Python Package`
|
||||
- {bdg-light}`GitHub Reusable Action`
|
||||
- {bdg-light}`GitHub Template`
|
||||
- {bdg-dark}`Git Workflow`
|
||||
- {bdg-primary}`Sphinx Extension`
|
||||
- {bdg-link-primary-line}`TeachBooks Favourites <./favourites.html>`
|
||||
- {bdg-danger}`iframe`
|
||||
- {bdg-success}`WebApp`
|
||||
|
||||
For each feature, the purpose, installation process and usage is elaborated in the respective sub-sections.
|
||||
Finally, the purpose, installation process and usage of each features is elaborated on 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.
|
||||
To see examples for these features, go to the [Examples chapter](../examples/overview.md).
|
||||
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 +1,8 @@
|
|||
````{margin}
|
||||
# Additional functionality
|
||||
|
||||
```{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.
|
||||
This sections includes the features developed by TeachBooks which add functionality to the book. Most of them are implemented as sphinx extensions, which are plugins developed for the Sphinx documentation ecosystem (which Jupyter Book is built upon). They extend or modify Sphinx’s capabilities. Since Sphinx extensions are not an integral part of jupyter-book, as opposed to original jupyter-book features, they must be installed and configured explicitly, for example in the `_config.yml` file.
|
||||
|
|
@ -1,11 +1,8 @@
|
|||
````{margin}
|
||||
# TeachBooks Student-view Features
|
||||
|
||||
```{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.
|
||||
|
|
|
|||
144
book/features/teachbooks.md
Normal file
144
book/features/teachbooks.md
Normal file
|
|
@ -0,0 +1,144 @@
|
|||
(teachbooks-package)=
|
||||
# Pre- and postprocessing book
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for all users to understand how the book building process works and can be influenced, although the implementation is likely going to be carried out by User Types 3, 4 or 5.
|
||||
```
|
||||
|
||||
{bdg-secondary}`Python Package`
|
||||
|
||||
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.
|
||||
|
||||
## Primary Features
|
||||
|
||||
Key features (described in the sections below) include:
|
||||
- pre- and post-processing steps for the Jupyter Book package
|
||||
- Draft-Release Workflow (`teachbooks build --release book`)
|
||||
- Start and stop a local server to check your book (`teachbooks serve`)
|
||||
|
||||
This list will be updated periodically as features are added. Check the [Release Notes](https://github.com/TeachBooks/TeachBooks/releases) in the GitHub repository for the most up-to-date information.
|
||||
|
||||
## Installation
|
||||
|
||||
The package is currently only [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.
|
||||
|
||||
## Contribute
|
||||
|
||||
This tool's repository is stored on [GitHub](https://github.com/TeachBooks/TeachBooks). The `README.md` of the repository describes how you can contribute---don't hesitate to make an issue if you would like to request new features!
|
||||
|
||||
## Description of Features
|
||||
|
||||
(teachbooks-pre-post)=
|
||||
### Jupyter Book Pre- and Post-Processing
|
||||
|
||||
Using the teachbooks CLI in the book building process generally invokes Jupyter Book. Many of the features in this package are then invoked in the stages before and after this command. The process generally includes the following steps:
|
||||
|
||||
1. Edit source code and prepare to build a book
|
||||
2. Execute `teachbooks [OPTIONS] COMMAND [ARGS]`
|
||||
3. Pre-processing step: carried out by `teachbooks`
|
||||
4. Build step: book is built using `jupyter book [OPTIONS] COMMAND [ARGS]`
|
||||
5. Post-processing step: carried out by `teachbooks`
|
||||
|
||||
Additional options like those used in jupyterbook (`--all` for example) can be used with `teachbooks` in an identical usage as with the `jupyter-book` command.
|
||||
|
||||
```{note}
|
||||
The pre- and post-processing steps have not yet bet formally defined; they only exist implicitly in the source code for the `build` CLI command. If you are interested in suggesting a feature or contributing to the package, please visit the [GitHub repository](https://github.com/teachbooks/teachbooks) and take a look at the Discussions and Issues. For example, [this one](https://github.com/orgs/TeachBooks/discussions/28).
|
||||
```
|
||||
|
||||
(teachbooks-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:
|
||||
|
||||
```
|
||||
format: jb-book
|
||||
root: intro
|
||||
|
||||
parts:
|
||||
- caption: ...
|
||||
chapters:
|
||||
- file: ...
|
||||
...
|
||||
# START REMOVE-FROM-PUBLISH
|
||||
- file: files_to_remove
|
||||
# END REMOVE-FROM-PUBLISH
|
||||
```
|
||||
|
||||
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 --publish book
|
||||
```
|
||||
|
||||
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'
|
||||
```
|
||||
|
||||
(teachbooks-serve)=
|
||||
### Local Python server
|
||||
|
||||
```{tip}
|
||||
Visit the {ref}`Local Server page <setup-local-server>` for an explanation of why you need a local server.
|
||||
```
|
||||
|
||||
The TeachBooks Python package includes a command line interface (CLI) that can be used to start a local server:
|
||||
|
||||
```bash
|
||||
teachbooks serve
|
||||
```
|
||||
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).
|
||||
|
|
@ -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,29 +1,19 @@
|
|||
````{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.
|
||||
{bdg-dark}`Git Workflow`
|
||||
|
||||
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.
|
||||
When building your book, your making use of packages: the teachbooks and jupyterbook packages themselves, but also packages for extensions. These are regularly updated, while those updates are not necessarily taken into your book. This is all defined in the `requirements.txt` file, which is provided as part of the [template](../external/template/README.md). There are three options:
|
||||
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 new version come out, although new version are in general 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. In this case you can also use GitHub's Dependabot.
|
||||
|
||||
## 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.
|
||||
Dependabot checks the specified version of packages in your `requirements.txt` file and opens a branch and pull requests whenever there's an update available for that package. Note that package 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:
|
||||
|
|
@ -38,12 +28,11 @@ updates:
|
|||
- 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).
|
||||
This will check every sunday around midnight (UTC) whether any of the fixed-version packages are updated. If so, several things will happen:
|
||||
1. A new branch starting with _dependabot_ will be created in the repository and any relevant workflows will be triggered.
|
||||
1. A _pull request_ will be created to pull 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`:
|
||||
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 next to the file `call-deploy-book.yml`:
|
||||
|
||||
```yaml
|
||||
on:
|
||||
|
|
|
|||
|
|
@ -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 +1,8 @@
|
|||
````{margin}
|
||||
# Book styling
|
||||
|
||||
```{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,7 +1,7 @@
|
|||
(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`.
|
||||
A script is to convert LaTeX files to Markdown for use in Jupyter Books {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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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](tex_md_converter) 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()
|
||||
|
|
@ -1 +0,0 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"></svg>
|
||||
|
Before Width: | Height: | Size: 67 B |
|
|
@ -1,4 +0,0 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 7">
|
||||
<path d="M8.12 3.27c.45-.32 1.06-.46 1.78-.73l-.31-.7c-1.28.23-2.43-.53-3.68-.7C4 .75 2.24 1.9.36 2.04v.76c1.87.41 3.64 1.26 5.6 1.02-1.21 1.21-2.84 2.64-4.69 2.07C.63 5.77.35 4.87.96 4.6c.27 1.04 1.57.3 1-.52C1.57 3.6.54 3.82.24 4.3c-.87 1.65.84 2.56 2.31 2.32 1.86-.25 3.29-1.71 4.53-3.02-.02.61.18 1.96-.41 2.5l.01.9c.43-.34.8-1.07.92-1.56.16-.63.04-1.02.1-1.53.05-.23.1-.41.42-.64zM1.9 2.39c.77-.23 1.58-.58 2.39-.66-.42 1.38 1.81 1.54 1.56 0 .64.16 1 .3 1.94.7-2.06 1.02-4.05.56-5.89-.04z"/>
|
||||
<path d="M.36 1.81v-.8c.23 0 .84-.18 1.44-.35C2.8.36 4.05 0 4.95 0c1 0 2.05.34 2.82.58l.91.25c.62.07.98-.08.98-.08l.34.73c-.06.02-.56.24-1.41.15-.27-.03-.62-.14-1.06-.29C6.77 1.1 5.82.8 4.95.8c-.79 0-1.97.35-2.92.63-.74.21-1.32.38-1.67.38z"/>
|
||||
</svg>
|
||||
|
Before Width: | Height: | Size: 807 B |
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