admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-12 22:35:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'release' into 30-add-section-on-icons

Browse source
This commit is contained in:
xjulie0x 2024-12-29 18:57:54 +01:00 • committed by GitHub
commit 80a0e443a6
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
82 changed files with 3829 additions and 489 deletions
Download patch file Download diff file Expand all files Collapse all files

3
.gitignore vendored
View file

@ -135,3 +135,6 @@ _contents/
# Jupyterlite
_output/
book/.jupyterlite.doit.db
# TeachBooks
**.teachbooks/

6
.gitmodules vendored
View file

@ -7,15 +7,9 @@
[submodule "book/external/deploy-book-workflow"]
path = book/external/deploy-book-workflow
url = https://github.com/TeachBooks/deploy-book-workflow.git
[submodule "book/external/latex-to-markdown-conversion"]
path = book/external/latex-to-markdown-conversion
url = https://gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion.git
[submodule "book/external/Useful_python_code"]
path = book/external/Useful_python_code
url = https://github.com/TeachBooks/Useful_python_code.git
[submodule "book/external/TeachBooks"]
path = book/external/TeachBooks
url = https://github.com/TeachBooks/TeachBooks.git
[submodule "book/external/Sphinx-Image-Inverter"]
path = book/external/Sphinx-Image-Inverter
url = https://github.com/TeachBooks/Sphinx-Image-Inverter.git

67
LICENSE
View file

@ -1,6 +1,6 @@
Attribution 4.0 International
The license of this manual itself is CC BY 4.0. The same license is used for [](external/Nested-Books) and [](external/template). The license of other included materials are provided below.:
=======================================================================
Attribution 4.0 International
Creative Commons Corporation ("Creative Commons") is not a law firm and
does not provide legal services or legal advice. Distribution of
@ -52,8 +52,6 @@ exhaustive, and do not form part of our licenses.
for the public:
wiki.creativecommons.org/Considerations_for_licensees
=======================================================================
Creative Commons Attribution 4.0 International Public License
By exercising the Licensed Rights (defined below), You accept and agree
@ -373,8 +371,6 @@ Section 8 -- Interpretation.
processes of any jurisdiction or authority.
=======================================================================
Creative Commons is not a party to its public
licenses. Notwithstanding, Creative Commons may elect to apply one of
its public licenses to material it publishes and in those instances
@ -393,3 +389,62 @@ the avoidance of doubt, this paragraph does not form part of the
public licenses.
Creative Commons may be contacted at creativecommons.org.
=======================================================================
[](external/annotater), [](external/deploy-book-workflow), [](external/Download-Link-Replacer), [](external/JupyterBook-Patches), [](external/Sphinx-Image-Inverter) and [](external/Useful_python_code) are licensed under BSD 3-Clause license:
BSD 3-Clause License
Copyright (c) 2024, TeachBooks
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
3. Neither the name of the copyright holder nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
=======================================================================
[](external/Sphinx-Grasple-public), [](external/Sphinx-TUDelft-theme) and [](external/teachbooks-sphinx-tippy) are licensed under MIT license:
MIT License
Copyright (c) 2024, TeachBooks
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

4
README.md
View file

@ -1,5 +1,7 @@
# TeachBooks Manual
[![call-deploy-book](https://github.com/TeachBooks/manual/actions/workflows/call-deploy-book.yml/badge.svg)](https://github.com/TeachBooks/manual/actions/workflows/call-deploy-book.yml)
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
@ -16,4 +18,4 @@ 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 boko including its submodules, clone using: `git clone --recurse-submodules git@github.com:TeachBooks/manual.git`
Happy book building!
Happy book building!

17
book/_config.yml
View file

@ -1,8 +1,6 @@
title: TeachBooks Manual
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>
logo: images/Logo_without_background.png
execute:
execute_notebooks: 'off'
@ -20,6 +18,7 @@ sphinx:
- jupyterbook_patches
- teachbooks_sphinx_grasple
- sphinx_image_inverter
- sphinx_exercise
config:
html_js_files:
- https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js
@ -27,6 +26,10 @@ sphinx:
use_thebe_lite: true
exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb","**/*.gif","**/*.txt","**/*.json",]
html_theme_options:
logo:
text: Manual
image_light: TeachBooks_logo.svg
image_dark: TeachBooks_logo_inverted.svg
repository_url: "https://github.com/TeachBooks/manual/"
path_to_docs: "book"
repository_branch: "release"
@ -37,3 +40,13 @@ sphinx:
thebe: true
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
local_extensions:
apastyle: _ext/
bracket_citation_style: _ext/
bibtex_bibfiles:
- references.bib

17
book/_ext/apastyle.py Normal file
View 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
View 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
View 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
View file

486
book/_ext/pybtexapastyle/formatting/apa.py Normal file
View 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

69
book/_ext/pybtexapastyle/formatting/pybtex/style/formatting/__init__.py Normal file
View file

@ -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

12
book/_ext/pybtexapastyle/formatting/pybtex/style/sorting/__init__.py Normal file
View file

@ -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)

39
book/_ext/pybtexapastyle/formatting/pybtex/style/sorting/author_year_title.py Normal file
View file

@ -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
View file

67
book/_ext/pybtexapastyle/labels/apa.py Normal file
View 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
View file

39
book/_ext/pybtexapastyle/names/firstlast.py Normal file
View 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&nbsp;Joseph de&nbsp;la Vall<span class="bibtex-protected">é</span>e&nbsp;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.&nbsp;L. X.&nbsp;J. de&nbsp;la Vall<span class="bibtex-protected">é</span>e&nbsp;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
View 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',
),
)

35
book/_toc.yml
View file

@ -2,7 +2,13 @@ format: jb-book
root: intro
parts:
- caption: Getting started!
- caption: Your First TeachBook!
chapters:
- file: intro/book.md
- file: intro/workflow.md
- file: intro/template.md
- file: intro/next.md
- caption: Getting Going!
chapters:
- file: installation-and-setup/user_types.md
- file: installation-and-setup/git.md
@ -13,7 +19,6 @@ parts:
- file: installation-and-setup/anaconda.md
- file: installation-and-setup/git_bash_conda_vs-code.md
- file: installation-and-setup/jupyter-book-setup.md
- file: external/template/README.md
- file: workflows/collaboration.md
sections:
- file: workflows/milestones_issues.md
@ -23,7 +28,11 @@ parts:
- file: workflows/merge_request.md
- file: installation-and-setup/collab
- file: installation-and-setup/tools
- file: installation-and-setup/creating_content.md
- file: installation-and-setup/copyright.md
sections:
- file: installation-and-setup/copyright/considerations
- file: installation-and-setup/copyright/licenses
- file: installation-and-setup/copyright/recommendations
- caption: Features
chapters:
- file: features/overview.md
@ -45,13 +54,16 @@ parts:
- file: basic-features/utterances.md
- file: features/easy-editing.md
sections:
- file: external/TeachBooks/README.md
- 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/sphinx_extensions.md
sections:
- file: external/Download-Link-Replacer/README.md
- file: features/custom-launch-button.md
- file: features/custom-launch-button.md
- file: basic-features/utterances.md
- file: features/interactive_element.ipynb
sections:
- file: external/Sphinx-Grasple-public/README.md
@ -70,9 +82,11 @@ parts:
- file: external/JupyterBook-Patches/README.md
- file: external/Sphinx-TUDelft-theme/README.md
- file: external/teachbooks-sphinx-tippy/README.md
- file: features/apa
- file: features/students
sections:
- file: external/annotater/README.md
- file: basic-features/hypothesis.md
- caption: Examples
chapters:
@ -86,13 +100,18 @@ parts:
- file: examples/coding_theory_widgets.ipynb
- file: examples/parametric_questions.ipynb
- caption: Editing tools
- caption: Editing Tools
chapters:
- file: tools/figmaker
- file: helper_code/intro.md
sections:
- file: external/latex-to-markdown-conversion/README.md
- file: helper_code/converter.md
- file: external/Useful_python_code/snippit.ipynb
- file: external/Useful_python_code/extensionfildownloadreturn.ipynb
- file: external/Useful_python_code/figshrinker.ipynb
- caption: Miscallaneous
chapters:
- file: references.md
- file: credits
- file: contact

8
book/basic-features/external-features.md
View file

@ -1,8 +0,0 @@
# Externally Developed Features
```{admonition} User types
:class: tip
This section is useful for user type 1-5.
```
This chapter includes features useful for books in the educational context, developed by various parties.

5
book/basic-features/hypothesis.md
View file

@ -1,5 +1,10 @@
# 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`
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.

19
book/basic-features/utterances.md
View file

@ -1,13 +1,22 @@
# 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`
[Utterances 🔮](https://utteranc.es/) is a lightweight open-source widget which allows you, your colleages and your students to discuss stuff in a blog post in your book. It is build on GitHub issues, so requires a GitHub repository, although the book can be hosted anywhere (so also on GitLab).
The [utterances website](https://utteranc.es/) clearly explains the required steps. One thing to take care of is how you want to do the issue-mapping with respect to multiple deployed versions (draft version, student version, archived versions):
- `Issue title contains page pathname`/`Issue title contains page URL` is useful if you want to isolate the comments on each of the branches.
- `Issue title contains page title` is useful if you want to show the all comments on all different branches.
The [utterances website](https://utteranc.es/) clearly explains the required steps. Three things to take care of are:
1. With the current setup of the [deploy book workflow on GitHub](../external/deploy-book-workflow/README.md), this widget only works on the primary branch.
2. The baseurl is the root url of your book (the part of the url that doesn't change when opening different pages of the book). It needs to be defined in the `_config.yml` so that utteranc.es knows where to redirect users while interacting with the widget:
```
html:
baseurl : "https://<user/organization>.github.io/<repo>" #Replace this with your own URL
```
3. It's advised to use `Issue title contains page pathname` as an option on utteranc.es, because that url is most stable.
The given script can be added anywhere in your book, just copy the html-script into your `.md`-file or a markdown cell in your `.ipynb`-file. The blogpost is not visible when you do a local build of the book, build it online or use a local python server as shown in {ref}`setup-local-server`.
@ -24,4 +33,4 @@ Below you see an example of this feature!
theme="github-light"
crossorigin="anonymous"
async>
</script>
</script>

15
book/contact.md Normal file
View file

@ -0,0 +1,15 @@
# Contact
## Contact
If you encounter any issues report it by clicking {octicon}`mark-github` on the top right corner of this page.
If you have questions, contact the editors at TeachBooks@tudelft.nl. TU Delft account holder can also contact us in the [MS Teams Open Interactive Textbooks Community](https://teams.microsoft.com/l/team/19%3Ah9-uRcP_yYauh-VuoPFozJVUvHVOB4a0mz1ZWvh4q4Q1%40thread.tacv2/conversations?groupId=3e88c1f3-4a4f-483a-a366-7e617de9ba99&tenantId=096e524d-6929-4030-8cd3-8ab42de0887b)
## Contribute
This book will continue to develop, so feel free to contribute https://github.com/TeachBooks/manual! You can do so directly by forking this repository and creating a pull request.
The released book can be found on on https://teachbooks.io/manual. This page shows the built book of the `release` branch. All branches will also be visible online, as pointed to in the actions summaries: https://github.com/TeachBooks/mirror_teachbook_manual/actions
Some parts of this book are taken from other sources in the form of submodules (linked in the folder [book/external](https://github.com/TeachBooks/manual/tree/release/book/external)). To contribute to those pages, contribute to the source repository directly with a fork and merge/pull request. If you intent to clone this book including its submodules, clone using: `git clone --recurse-submodules git@github.com:TeachBooks/manual.git`

63
book/credits.md Normal file
View file

@ -0,0 +1,63 @@
(credits)=
# Credits and License
You can refer to this book in its entirety as:
> van Woudenberg, T. and Lanzafame, R. (2024), _TeachBooks Manual_. https://github.com/TeachBooks/manual. Retreived [Month, Year]. CC BY 4.0.
The introduction, structure and decisions on content is done under direction of Tom van Woudenberg and Robert Lanzafame. 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 after Spring 2025. You can refer to individual chapters or pages within this book as:
> `<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._
## Acknowledgements
This book has many contributors, many of whom are also key members of the TeachBooks Team:
- Tom van Woudenberg
- Robert Lanzafame
- Freek Pols
- Julie Kirsch
- Caspar Jungbacker
All from Delft University of Technology.
This doesn't include small contributions from various people from within and outside Delft University of Technology.
A better way to see the contributions is to check the [Contributors Page](https://github.com/TeachBooks/manual/graphs/contributors) of the GitHub repository.
A big "thank you" is also due to the various colleagues and teaching assistants that have worked as part of the [TeachBooks](https://teachbooks.io/) Team for developing tools and providing support to improve this book, as well as the faculty of Civil Engineering and Geosciences and the Library at Delft University of Technology for significant financial support. The faculties of of Applied Sciences and Electrical Engineering, Mathematics and Computer Science have also provided support in the form of contributions from employees and student assistants..
## License
This manual is [CC BY 4.0 licensed](https://creativecommons.org/licenses/by/4.0/) allowing you to share and adapt the material, as long as the source is named. External resources that are reused in this manual are listed below.
(external_resources)=
### External resources
Parts of this book are taken from other external resources and reused in various ways. If an author is not listed on a particular page, it is by the Authors, except as follows:
The following pages are included directly from an external resource and is not edited by the TeachBooks Team:
- page [](./external/annotater/README.md). Original content licensed under BSD 3-Clause license.
- Page [](./external/deploy-book-workflow/README.md). Original content licensed under BSD 3-Clause license.
- Page [](./external/Download-Link-Replacer/README.md). Original content licensed under BSD 3-Clause license.
- Page [](./external/JupyterBook-Patches/README.md). Original content licensed under BSD 3-Clause license.
- Page [](./external/Nested-Books/README.md). Original content licensed under CC BY 4.0 license.
- Page [](./external/Sphinx-Grasple-public/README.md). Original content licensed under MIT license.
- Page [](./external/Sphinx-Image-Inverter/README.md). Original content licensed under BSD 3-Clause license.
- Page [](./external/Sphinx-TUDelft-theme/README.md). Original content licensed under MIT license.
- Page [](./external/teachbooks-sphinx-tippy/README.md). Original content licensed under MIT license.
- Page [](./external/template/README.md). Original content licensed under CC BY 4.0 license.
- 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.

2
book/external/Download-Link-Replacer vendored

@ -1 +1 @@
Subproject commit 66952b5f23af2f0106eb24e56f186d729b5a1ca8
Subproject commit f69e970a8da7d85e5473c7e5f58299a2ee3cf331

2
book/external/JupyterBook-Patches vendored

@ -1 +1 @@
Subproject commit 5c129f2447bb4b30100c136d94b5bee9e51e2921
Subproject commit f4d9638b197ad992d4e179295aa648b641925c6d

2
book/external/Nested-Books vendored

@ -1 +1 @@
Subproject commit ced5cdefa1b1b6c4fdba3fc42a94e812db4892f0
Subproject commit 3cf61525f3985916805a59361935764d78e460df

2
book/external/Sphinx-Grasple-public vendored

@ -1 +1 @@
Subproject commit c29b4a03351c88fa5cdd09475f99a1b486a0e247
Subproject commit f4eff8d1565eaf127898f2fe216cf5208684fb27

2
book/external/Sphinx-Image-Inverter vendored

@ -1 +1 @@
Subproject commit c9c9d2f6953b5a57ff4763976840ec3bb281dbcf
Subproject commit c497add7fea53bacdd24f1c7fa5ec7a850e5f9d0

2
book/external/Sphinx-TUDelft-theme vendored

@ -1 +1 @@
Subproject commit 0f4758586bebb1db4da0738b66d02d883ff7b54d
Subproject commit 35ecbddad78b567a0b2d1d4bdb513d8b95181348

1
book/external/TeachBooks vendored

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

2
book/external/Useful_python_code vendored

@ -1 +1 @@
Subproject commit e522976583a6c8cbc910531e972320a45f942737
Subproject commit 7fbdbbf720c27112fb58bcf7826225197e39357b

2
book/external/annotater vendored

@ -1 +1 @@
Subproject commit 7cd38dbba9ab50eebc5dbba6c61b9cb4f46d3cf0
Subproject commit 0da75c3592d2ddafbcec61fc7248cfb0e3c8cc1b

2
book/external/deploy-book-workflow vendored

@ -1 +1 @@
Subproject commit 71dd5f2f56c8540fa45ce713adf44cab9d85c36e
Subproject commit ed2cdc81be5036deb8da244814a946d17ece7708

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

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

2
book/external/teachbooks-sphinx-tippy vendored

@ -1 +1 @@
Subproject commit 5aec30ed8df7c6259faf7ac6cd178a0cf2887c17
Subproject commit a80e7645bc5a377b3c75befdf29eb67934bb9ab7

2
book/external/template vendored

@ -1 +1 @@
Subproject commit 5aadbc527ee1251a60cbd4877d109b0558e03aad
Subproject commit 1ea38abf8b30e9076fe315d258655ecf679e4bf2

BIN
book/features/_ext.zip Normal file
View file

Binary file not shown.

4
book/features/adding_HTML_elements.md
View file

@ -32,7 +32,7 @@ Let's take a closer look at the source. Since this project uses a local file str
- Finally, the string `"element_render_box.html"` selects the HTML file we want to embed. We are now in `book/_static/element_render_box.html`.
## Viewing result at local build
To view the final result locally, it's required to setup a [local python webserver](setup-local-server).
To view the final result locally, it's required to setup a {ref}`local Python webserver <setup-local-server>`.
## HTML code for the 3D render element
@ -196,4 +196,4 @@ To conclude, I provide the HTML/JavaScript code for the 3D render element above.
</html>
```
```

98
book/features/apa.md Normal file
View file

@ -0,0 +1,98 @@
(apa)=
# APA References
```{admonition} User types
:class: tip
This page is useful for user type 4 and 5.
```
{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.
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 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
**Step 1: files to root directory of your book**
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:
```
book
├── _ext/
│ ├── pybtexapastyle/
│ ├── apastyle.py
│ ├── bracket_citation_style.py
├── _config.yml
├── _toc.yml
├── requirements.txt
├── <book files>
```
**Step 2: Add to `requirements.txt`**
Add a specific version of `docutils` to your requirements file:
```
docutils==0.17.1
```
**Step 3: Enable in `_config.yml`**
In your `_config.yml` file, add a `bibtex_default_style`, `bybtex_reference_style` and the local extensions `apastyle` and `bracket_citation_style.py`
```
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. 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:
```
{cite:t}`jason_moore`
```
Here are three examples for making citations:
| Syntax | Result |
| :---: | :---: |
|`{cite:t}` | {cite:t}`jason_moore` |
|`{cite:p}`| {cite:p}`jason_moore` |
|`{cite}`| {cite}`jason_moore` |
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 Issue
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
## 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 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).
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.
## Contribute
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!

2
book/features/custom-launch-button.md
View file

@ -96,7 +96,7 @@ The code in the above cell is the `_launch_buttons.yml` file of a repository cal
```{figure} figures/language_button.PNG
---
width: 50%
name:language_button
name: language_button
---
Custom Button
```

9
book/features/live_code.ipynb
View file

@ -55,7 +55,7 @@
"\n",
"Afterwards, this sphinx extension needs to be enabled in your book. This can be done by adding the following lines to `_config.yml`:\n",
"\n",
"```\n",
"```yaml\n",
"launch_buttons:\n",
" thebe: true\n",
"\n",
@ -78,7 +78,7 @@
"\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",
"```\n",
"```yaml\n",
"sphinx:\n",
" config:\n",
" html_js_files:\n",
@ -147,7 +147,10 @@
"\n",
"```python\n",
"%pip install package_name\n",
"```"
"```\n",
"\n",
"### Import module from subdirectory\n",
"In case you've a module in a subdirectory you cannot do directly `import <module_name> as <local_module_name>`. To solve this, you first have to add that subdirectory to the path with `sys.path.insert(1, '/<module_name/subdirectory>')` (preferably in a hidden cell with `theme-remove-input-init`)"
]
},
{

95
book/features/local_server.md Normal file
View file

@ -0,0 +1,95 @@
(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-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.
Technically what is needed to facilitate this during the editing and checking of your book locally is a **static web server** that can serve the files in the `./book/_build/html` directory of your book (this subdirectory is created as a result of the command `build book`). We refer to this as a **local server** because it is running on your local machine.
```{admonition} Why do you need a local server?
:class: tip
A 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>`.
This page presents just a few additional examples that are used by TeachBooks collaborators. There are many more options available out there, for example, [this list illustrates many servers that can be activated with a single line of code!](https://gist.github.com/willurd/5720255).
```{tip}
Remember that the browser is serving static files provided by the local server and does not always keep track when they are updated.
You should reload the page if you are editing and rebuilding the book. You can try `CTRL+R` `ctrl`+`F5`. If this does not work, on Chrome try right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`.
```
## TeachBooks Server: `teachbooks serve`
If you have the TeachBooks Python package installed (`pip install teachbooks`), starting a server is as simple as:
```bash
teachbooks serve
```
See the {ref}`TeachBooks Package page <teachbooks-serve>` for additional guidance on using the CLI tool.
## Live Server: a VS Code Extension
A local server is easy to initialize directly in VS Code using the Live Server extension. Once installed, it can be activated with a "Go Live" button in the bottom right corner of VS Code. The extension will automatically serve index.html, so depending on your book build settings you may need to navigate to the correct directory/file manually using the URL address in the browser.
````{admonition} Install Live Serve Extension
:class: tip
You can install this extension by searching for `Live Server` (or even easier, extension ID `ritwickdey.LiveServer`)in the Visual Studio Code extensions marketplace.
```{figure} https://github.com/ritwickdey/live-server-web-extension/raw/master/img/icon.png
---
width: 10%
name: live-server-icon
```
````
## Python Server: `python -m http.server`
The Python standard library has a built-in server that can be activated from the command line. This is a simple way to serve a book locally
```
python -m http.server
```
If you don't mind typing a bit more, you can specify the port number and the directory to serve:
```
python -m http.server 8000 --directory book/_build/html
```
This is actually what the `teachbooks serve` command is using, but there we have added additional features to make the process more user-friendly for the book edit and check workflow.
### Stopping the Python Server
It can be challenging to stop the Python server, especially when using Windows OS. Even though you may force end the process (e.g., with `CMD+C`), the server may still be running in the background.
For Mac and Linux users (or for Windows if you have Git Bash installed or another Unix-type terminal), you can try this:
```bash
pid=$(ps aux | grep http.server | head -n 1 | awk '{ print $2 }')
kill -9 $pid
```
Or this:
```bash
tskill python
```
A Windows-specific command for the CMD prompt or Powershell is:
```
TASKKILL /IM python.exe /F
```

8
book/features/overview.md
View file

@ -1,8 +1,13 @@
# Overview
As TeachBooks, we collect a suite of existing open-source software and keep our books up-to-date so you don't have to! Some of the software is developed with our TA's to improve the learning experience of our students and ease the book-development process for our teachers. By deploying these tools from a central location we can prevent common problems before they arise, and fix them quickly when they do occur. As the open-source software landscape changes rapidly, it is essential to keep in contact and share resources amongst ourselves to minimize maintenance and downtime for our book websites and focus on what really matters: teaching!
As TeachBooks, we collect a suite of existing open-source software so you don't have to! Some of the software is developed with our TA's to improve the learning experience of our students and ease the book-development process for our teachers. As the open-source software landscape changes rapidly, it is essential to keep in contact and share resources amongst ourselves to minimize maintenance and downtime for our book websites and focus on what really matters: teaching!
Since the list of TeachBook features is getting quite long, we have grouped them in categories:
- Original Jupyter Book and Sphinx features
- Easy editing process
- Additional functionality
- Book styling
- TeachBooks student-view 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`
@ -10,6 +15,7 @@ Additionally, not all features are built using the same type of sourcecode. For
- {bdg-white}`GitHub App and Javascript script`
- {bdg-secondary}`Python Package`
- {bdg-light}`GitHub Reusable Action`
- {bdg-light}`GitHub Template`
- {bdg-dark}`Git Workflow`
- {bdg-primary}`Sphinx Extension`
- {bdg-danger}`iframe`

142
book/features/teachbooks.md
View file

@ -1,18 +1,144 @@
(teachbooks-package)=
# TeachBooks: Our Custom Python 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:
TeachBooks has created a Python package and released it on PyPI. It can easily be used like this:
```
pip install teachbooks
```
The source code is hosted in a repository on GitHub, [github.com/teachBooks/teachbooks](https://github.com/teachBooks/teachbooks), and is accompanied by a documentation website, [teachbooks.github.io/TeachBooks/](https://teachbooks.github.io/TeachBooks/).
The 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:
The features and documentation will increase with time; until then, note there are two important reasons to use the teachbooks package:
1. Use the `REMOVE-FROM-PUBLISH` feature to more easily maintain draft and published versions of your TeachBook (see {ref}`this page <remove-from-publish>` for more details).
2. Easily start and stop a local Python server to better test your book while writing (e.g., the interactive Python features require a local server to properly check certain TeachBooks features)
```bash
pip install --upgrade teachbooks
```
For case 1, the `teachbooks` package is meant to be used instead of `jupyter book build book` to build your book (it executes `jupyter book build book` for you).
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.
Case 2 is meant to be used independently, for example, once you have successfully built a book, simply run `teachbooks serve` and open the resulting URL that is printed in the terminal. To stop the server use `teachbooks serve stop`; see {ref}`this page <setup-local-server>` for additional explanation for how to use this feature and why it is needed.
## 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).

10
book/helper_code/converter.md Normal file
View file

@ -0,0 +1,10 @@
(tex_md_converter)=
# Convert LaTeX to Markdown
A script is to convert LaTeX files to Markdown for use in Jupyter Books {cite:p}`timon_latex`.
This script has been used successfully on at least one book in the TU Delft OPEN library: [Introduction to particle and continuum mechanics, by Timon Idema](https://textbooks.open.tudelft.nl/textbooks/catalog/book/81). The author is able to convert nearly everything in this book automatically, with only a few manual adjustments needed (e.g., a special character and a figure caption).
Depending on the number of custom LaTeX commands used in your book, you may need to adjust the script to handle them.
Additional information about the script, along with the source code itself which is distributed under a [BSD 3-clause license](https://opensource.org/license/BSD-3-Clause), is available at the following link on TU Delft GitLab: [gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion](https://gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion).

2
book/helper_code/intro.md
View file

@ -1,7 +1,7 @@
# Scripts for automating workflow
This chapter contains a few scripts which can be useful in the book-editing process:
- [LaTeX to markdown conversion](../external/latex-to-markdown-conversion/README.md) to convert a LaTeX file into jupyter-book compatible markdown.
- [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

80
book/images/TeachBooks_logo.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 158 KiB

81
book/images/TeachBooks_logo_inverted.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 368 KiB

14
book/installation-and-setup/anaconda.md
View file

@ -36,18 +36,18 @@ A python virtual environment is, like the name might suggest, a reserved space w
Now we will set up your first environment. The following steps will create an Anaconda environment and install Python 3.11. Even if you already have Python 3.11, it is still good practice to create a dedicated Anaconda environment for each of your major projects such as creating a jupyter book.
For simplicity we will call this environment `my_new_book`, but you can give it any name you like.
For simplicity we will call this environment `my_new_book_env`, but you can give it any name you like.
1. Open the commmand line interface (see above) or continue in the same session if it is still active
2. Execute: `conda create --name my_new_book pip` (this may take several minutes)
3. Activate: `conda activate my_new_book`
<br> Check: you should now see your new environment displayed somewhere in the prompt between parenthesis, like this: `(my_new_book)`
2. Execute: `conda create --name my_new_book_env pip` (this may take several minutes)
3. Activate: `conda activate my_new_book_env`
<br> Check: you should now see your new environment displayed somewhere in the prompt between parenthesis, like this: `(my_new_book_env)`
4. Additional 4th step: `pip install -r requirements.txt` (explanation in the following section)
Now everytime you want to work on your jupyter-book, you need to activate the environment! (step 3) If you don't activate your environment, you will work in a 'wrong' working environment that might not contain all the packages you need.
As mentioned before, python packages can be downloaded in the environments you create. Both NumPy and pandas are popular Python packages used for data manipulation and analysis. For the creation of Jupyter Books, we will use the package `jupyter-book`. More information about this package [here](jupyter-book-setup.md).
As mentioned before, python packages can be downloaded in the environments you create. Both NumPy and pandas are popular Python packages used for data manipulation and analysis. For the creation of Jupyter Books, we will use the package `teachbooks` which is a wrapper around JupyterBooks. More information about this package [here](jupyter-book-setup.md).
### Import environments
@ -121,7 +121,7 @@ If you want to create an environment based on an existing `*.yml` file, you can
This may take several minutes because you are installing many packages at once! Keep an eye on the terminal window as this process is completed. First `conda` is collecting information about the dependencies, then it will _solve_ the environment; in other words, figure out which version of each package it should use. Once it is ready, it will present the list of packages and proceed with the "installation" (really just downloading `*.py` files and putting them in a folder on your computer)
Note that the prompt may ask you to confirm that the installation should proceed, depending on your system settings.
Once the environment is created, we can activate it, and also check that everything was installed properly. Try `conda env export -n my_new_book` to see what was installed by "default." The list is very long, even though we only asked for a few packages!
Once the environment is created, we can activate it, and also check that everything was installed properly. Try `conda env export -n my_new_book_env` to see what was installed by "default." The list is very long, even though we only asked for a few packages!
It is also interesting to try `conda env export --from-history` (make sure you activated it already), which shows the specific packages requested.
@ -135,7 +135,7 @@ If you have many projects, the amount of environments can take up a lot of space
To remove an environment, in your Anaconda Prompt, run:
`conda remove --name my_new_book --all`
`conda remove --name my_new_book_env --all`
You will be asked to confirm the deletion, then it may take a while to remove all of the files. To verify that the environment was removed, in your terminal window or an Anaconda Prompt, run:

73
book/installation-and-setup/copyright.md Normal file
View file

@ -0,0 +1,73 @@
(copyright)=
# Copyright and Licenses checklist
> This page reuses adapted CC BY content from the TU Delft Library. {cite:p}`tud_cip_24`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
```{admonition} User types
:class: tip
This page is useful for user **all** user types.
```
The previous sections have familiarized you with the necessary software for your user type, the basics of Git, and how to collaborate with your team using Git. Now it's time to create your own content. This section will provide an overview of the copy right laws which need to be taking into account when creating and including content at TU Delft!
Although the focus of TeachBooks is mostly to help the teaching staff create interactive textbooks for their students, it can be attractive to spread ones wings a bit and reach a wider audience. The checklist on this page provides a quick overview of the _minimium_ information you should be aware of when getting started in terms of copyright, avoiding legal issues and making your life easier later on when/if you decide to publish your book with an open license, for example via TU Delft Open.
For more information specifically related to online books read the following pages; for more generic information about publishing visit the [TU Delft Copyright website](https://www.tudelft.nl/library/support/copyright).
## The Copyright Checklist
This checklist is meant to quickly illustrate the proper way of using the copyrighted work of others. In particular for online books that are available on the internet, it is important to be aware that publicly accessible content is already considered _published._
## Item 0: Your book is already published!
**0) If your book is accessible online, it is already published!**
This may surprise you, but _legally_ speaking, once your book content is available online, it is technically already _published._ A quick search on the internet reveals most definitions involve two key words: to _issue_ something for _distribution._ Thus, the act of sharing book material with students via the internet is a form of publishing. Of course this is different than doing so via an established publisher, for example: others may not be able to easily find the material, the product may be unfinished, mistakes may be present, etc. However, this means that _copyright ownership_ and _authorship_ has been established and must be considered (by you!) in at least two ways:
1. You are responsible for properly attributing the work of others included in your book, and
2. You should explicitly state how you would like others to (re)use the content in your book.
The remaining checklist items cover the first point, which is where the risk of legal and financial consequences for you and your employer lie. Continue with the following pages to find out more about the second point.
## Items 1-4: Attribute the work of others properly
**1) Your own new content**
If you have created the content yourself, you are allowed to use it if there are no other agreements in place.
Note that this is specifically for _new_ content; as in unpublished anywhere else! If you have already published it elsewhere, you should attribute yourself as if you would any other material.
**2) Somebody else's content**
If you want to reuse someone else’s work (that is _not_ released under an open license!) you need to ask for permission. When you ask for permission please do it in a written format and let the copyright holders know that you are going to use their work in an open licensed work.
If you are granted permission, be sure to exclude the work from the open licensed conditions specified in your book (typically easiest by stating so in the attribution/footnote/caption, as well in the colophon of the work). If you have asked for permission and received no answer, consider it as a negative response and abstain from using the work you were intended to.
If you really need to reuse someone else’s work, please also check whether the copyright exception right to quote is applicable to you.
_Here are a few selected answers from the [Copyright Information Point](https://www.tudelft.nl/library/support/copyright):_
- [Citations of other work](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131017)
- [Use of copyrighted multimedia](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131031)
- [Use of copyrighted text](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131032).
**3) Your own old content**
Even if created by you, you need to attribute yourself in order to avoid self-plagiarism. If the material has an open license, this is straightforward. If there is no license, or a non-open license, you may need permission from your university (the copyright holder; explained {ref}`here<copyright_considerations_copyright>`). Read more [here](https://www.tudelft.nl/library/support/copyright/teacher-copyright-answers#c1132157)
If you want to use your own content that a (commercial) publisher has published, you must check your contract to see if you are allowed to use it. Read more [here](https://www.tudelft.nl/library/support/copyright/teacher-copyright-answers#c1132153).
Even if you have created the work yourself but years ago, check whether you have the right to reuse it. If you have created it while you were under the employment of your previous employer, then you will need to ask permission from them.
**4) Open licensed work**
Work by others that is provided with an open license can be used without asking for permission; if you find yourself considering whether to reuse someone else’s work that does _not_ have an open license, you should try to check if there is an alternative available that is provided with an open license (i.e., replace the work you wanted to reuse in the first place). It turns out there are many [online platforms that can help you locate open licensed work](https://www.tudelft.nl/en/library/collections/open-educational-resources).
If you use open licensed work, you need to attribute the license under which the work is licensed and you need to check the compatibility of the licenses. This means you need to check which license the work you want to reuse has as well as the license that your TeachBook will be provided with (more information is provided on the {ref}`Licenses page <copyright_licenses>`).
When you want to adapt previously published work you need to ask permission for it. Otherwise please check whether you can find an open licensed work that you can adapt if their license it permits it.
## A Final Note: Open Licenses Make Life Easy!
If it's not clear by now, hopefully you see the value of creating and using material with open licenses. This makes it much easier to reuse content, as the license itself allows for this, and you don't have to spend time asking for permission!
Find out more about open licenses specifically for books on the following pages.

86
book/installation-and-setup/copyright/considerations.md Normal file
View file

@ -0,0 +1,86 @@
(copyright_considerations)=
# Copyright Considerations
> This page reuses adapted CC BY content from {cite:t}`tud_cip_24`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
Copyright law dictates how online book material can and should be created, maintained and shared. An author should understand a few key concepts, as well as best practices, in order to create a book that not only is a useful resource, but, also fairly reuses the work of others and, if provided with an open license, enables original content to also be reused.
Before getting into specific license types and our recommendations for properly attributing and referencing the work of others, let's review a few key copyright-related concepts that are specific to online textbooks.
```{tip}
Here we only focus on aspects that are explicitly relevant to the creation and sharing of online books. Visit the [TU Delft Copyright Information Point website](https://www.tudelft.nl/library/support/copyright) for a more thorough explanation of these important concepts.
```
## Copyright
The legal right of the content _owner_ to use, publish, distribute, share, and/or duplicate the work. Copyright is divided into **legal rights** and **moral rights**, depending on the material and circumstances under which it was created.
As indicated below, it is the _moral rights_ that give you, the author, the right to be named as the creator of the work.
## Types of Material
It appears that copyright law distinguishes between two types of material (not including that of students):
1. Educational material
2. Articles, book (chapter), conference paper, etc.
We aren't really sure what the definition of _educational material_ is, but since pretty much everything we do is for teaching students or teachers about things, we are pretty sure it includes all of it. Perhaps it is easier to see a few examples of what is _not_ included: journal article, book (chapter), conference paper.
```{warning}
The TeachBooks Team isn't really sure when the "line is crossed" from educational material to book. More specifically, when the copyright owner is you (the author) or the University (your employer). For now, we assume that all books made by employees of a university are considered educational material.
Do you have a better answer than this? Let us know!
If you can read Dutch, the report _Leermaterialen kiezen_ may shed some light on uncertainty about what is considered "educational material" ([download PDF here](https://www.versnellingsplan.nl/wp-content/uploads/2021/08/Digitale-leermaterialen-leermaterialen-kiezen.pdf)).
```
(copyright_considerations_copyright)=
## You Don't Own Everything
The law is very clear on this, and the TU Delft Copyright page states it quite clearly:
> Copyright to educational material made by a TU Delft teacher, rests with TU Delft. Amongst the other moral rights, the teacher retains the right to be named.
In case that wasn't clear enough, _TU Delft owns the copyright,_ not you! In other words, you should do this:
> by Last, First © TU Delft, Year
**Don't** do this:
> © Last, First, Year
We recognize that this may make you angry, and we can relate: as teachers we put a lot of effort into the material we create. However, we have come to see that this is _not_ a horrible situation; in fact, it is a good one. As the creator of the material you still retain moral rights to be named as the author, and there are other benefits as well. For example, the ability of other teachers that may take your place after you are gone to legally use and build upon your work in the future.
```{tip}
One reason copyright lies with TU Delft is because educational material must remain available for students when the author leaves. Additional justification can be found in the Open Educational Resources (OER) Policy Document, [here](https://repository.tudelft.nl/record/uuid:68a07efc-fc4d-4a57-8e93-88a3af37465a).
The use of open licenses actually does not prohibit the author from using the material in the future, even if not employed at TU Delft. For example, if you publish a TeachBook at TU OPEN, with a CC BY license, you are always entitled to "take" the book with you when leaving by simply changing the cover.
```
**Still don't agree?** Sorry. Please take this up with your nearest library or copyright expert and let us know if you get a different response! In the meantime, we will simply list ourselves as authors, use CC BY licenses and remember that TU Delft holds the copyright for our work produced as teachers.
```{warning}
The TeachBooks Team isn't sure where code and data lie here. Since TeachBooks is oriented towards education, we assume that TU Delft also owns the copyright for this.
Do you have a better answer? Let us know!
```
## Licensing
This dictates how others may or may not be able to share or (re)use your work. It is (fortunately) becoming more common to include licenses with educational material (including books), which makes it much easier to understand how specific material can be used. Note that _in the absence of a license, you must assume that nothing can be reused!_ In this case you have to ask permission to the copyright holder, which can be a time-consuming process. License considerations are described in more detail in the following pages.
```{warning}
The TeachBooks Team isn't really able to explain why an author can dictate the license of material they create while TU Delft is the copyright holder. In other words, if I create a new assignment, I can choose to license it as CC BY.
Do you know? Please get in touch with us and help!
```
## Summary
There are many legal aspects to consider when creating an online book. Hopefully this page simplifies the story somewhat and indicates that there is a finite set of actions you should take to ensure that your book properly attributes and references the work of others, as well as indicates to others how they can use your work. This includes the following:
1. **Choose a license** and including with the _source code_ and _website_ of your book (we hope you choose CC BY!).
2. Clearly **indicate where and how you have used the work of others** in your book (i.e., within the _content_ of your book).
3. **Summarize all sources** used in your book, as well as what may or may not be included under the license which you have chosen.
The following pages illustrate how to do this. It turns out to be not only a clear set of instructions for (re)users of your content, but also to help you remember what you have used in your book and where to find it later if changes are needed.

BIN
book/installation-and-setup/copyright/figures/1280px-CC_License_Compatibility_Chart.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 543 KiB

BIN
book/installation-and-setup/copyright/figures/open_licenses.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 186 KiB

107
book/installation-and-setup/copyright/licenses.md Normal file
View file

@ -0,0 +1,107 @@
(copyright_licenses)=
# Licenses
> This page reuses adapted CC BY content from {cite:t}`hall21`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
Here we present an overview of various license types, with a particular focus on the preference of TeachBooks to use Permissive Open Licenses, regardless of whether material is _content, code or data_ (described below).
```{admonition} Why permissive open licenses?
:class: tip
Since we (TeachBooks) authors have been working on making online books, we see the value in making content available for reuse. When preparing a new page or assignment, nothing makes us happier than seeing a CC BY license on something that we would like to (re)use ourselves. Why? Because we know that all we have to do is properly attribute the work and we can get on with our true passion: **teaching!**
```
This page is written expressly for content authors of online interactive textbooks (e.g., those including, but not restricted to, Jupyter Books), which are composed of two parts:
1. An online document in the form of a website, accessible at a specific URL, and
2. The _source code,_ which defines the _content_ and is required to create the website.
This generally does _not_ include the software required to convert the _source code_ in the the _website._
```{note}
Because the source code of an online book defines the content, and only occasionally includes code required to create the website, one should consider the _source code_ of a book as _content_ and not _code._ When this is not the case, we recommend included a code-specific license and indicate the specific files to which the license applies in your repository.
```
If you are personally undecided on which license to choose for your work, we hope that the information in this chapter convinces you to also have a preference for permissive open licenses. If you are still unsure, we recommend reading the [blog post by {cite:t}`hall21`](https://agilescientific.com/blog/2021/2/17/which-open-licence-should-i-choose) that inspired this page. Another useful resource is the website [choosealicense.com](https://choosealicense.com/), which includes many more options than those described here. Finally, consider also the policies of your own university or organization; for example, [TU Delft polcies can be found here](https://www.tudelft.nl/en/library/support/library-for-researchers/publishing-outreach/open-access-policy-and-guidelines).
## License Types in Context
Have you ever been overwhelmed by the massive amount of information (and especially _opinions!_) available regarding licenses? We have too! However, you are in luck: by dividing all possible license types into _openness_ and _material type,_ it becomes much easier to understand the differences, and make a decision that fits your situation best.
% retrieved dec 17 2024 by robert; see bib file, credits page
% https://agilescientific.com/blog/2021/2/17/which-open-licence-should-i-choose
```{figure} ./figures/open_licenses.png
:name: fig_license_types
Overview of license types, emphasizing "openness" and subdivided by material type: content, code and data. Source: {cite:t}`hall21`, CC BY. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
```
Although this figure only includes a few different license types, the way of dividing by _openness_ and _material type_ can be applied to any license. This is especially useful when you are unsure which license to choose, or when you are considering a license that is not included in the figure. Remember to check the website [choosealicense.com](https://choosealicense.com/), which includes many more options than those described here. You can also an immediate comparison in [the choosealicense.com appendix](https://choosealicense.com/appendix/).
### Open versus Not Open
We recommend using open licenses to allow other people to reuse your material, just like you'd like to reuse material from others.
### Content, Code and Data
For content, we use a CC BY 4.0 license, for Code we primarily use the BSD-3-Clause license. Both of these are open to allow reuse.
## A Note to the Wary
Are you thinking something like this?
> I've put a lot of work into my material, and I don't want people to take credit for it or use it without my knowledge. However, I do see the value of choosing a license, especially an open one. Maybe I will choose something like CC BY-NC-SA, which allows others to use my work but not for commercial purposes, and not allowing them to modify it. That way, I can still get credit for my work and others can use it for educational purposes.
This is a nice sentiment, but when it comes to books, we don't advise it for several reasons. The following sections anecdotally explain "not open" and "permissive" licenses are not preferred.
```{note}
Think you can improve on the examples described in the following sections? Make an Issue or Pull Request!
```
### Why is ND not preferred?
The "ND" license prohibits derivative works: in other words, the material cannot be modified and must be used in its entirety. This is problematic for a few reasons:
- What if you have a wonderful page describing Topic X, but there are a few contextual phrases that are undesired, for example: "this is required reading for Tuesday, December 17, 2024 in CIEM1000." That would be distracting for your own students, but you can't remove it.
- What is the point of including a website together with another website? It's easier to just link to your material directly.
- What if someone only wants a small part of your book? They can't use it.
- What if someone else makes similar material and releases it under CC BY and you include it in your own book under an ND license? It seems unfair not to also provide them an opportunity to benefit from your work. In addition, this is not allowed! You can’t put work under a more restrictive license (see also compatibility table below).
- Often someone creates a copy of your work and makes improvements. The Git system (e.g., forks, commits, pull requests, etc) make it very straightforward to also include these improvements back into your original work. This would not be possible if you did not allow for reuse in the first place!
### Why is NC not preferred?
The "NC" license prohibits commercial use. It sounds nice, right?
> Great, I can guarantee that big for-profit companies can't use my work for their own gain. This is important to me at a public or non-profit institution.
To be honest, it is more trouble than it's worth, primarily because the law seems to be vague on what constitutes commercial use. Many universities require tuition to cover operating expenses, which is often broken down into by nubmer of students, credits, courses, etc. This could be interpreted as a form of commercial use and thus prevent other educators from using your work, which is precisely the opposite of what you were trying to facilitate!
### Why is SA not preferred?
The "SA" license requires that any derivative works be released under the same license. If you have two sources, each of which has a different SA license, how can you include your work that incorporates that content under the same license? You can't! Once again, if your goal is to convince others to share your work in a responsible way, your effort is thwarted. As with NC, this type of license seems to be more trouble than it's worth.
### Summary of License Type Compatibility
The previous sections can be illustrated by examining a so-called "license compatibility chart," which illustrates whether or not you can reuse material from a specific license type in another. Upon examination, you will see that CC BY is the most permissive license, both in terms of what you can do with the work of others, as well as what others can do with your work. We hope you will consider this when choosing a license for your own work!
```{figure} ./figures/1280px-CC_License_Compatibility_Chart.png
:name: fig_license_compatibility
Compatibility between Creative Commons license types. Source: Kennisland, CC0. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
```
## Examples from Related Applications
```{warning}
Work in progress.
```
### Code in a Book Repository
For example, a simple script to parse files in your repository. You can include a special license with this code.
### Educational Materials with Code
What if your _content_ includes code. This happens in many science and engineering courses where programming is a key part of the learning process.
For example, the [MUDE Team](https://mude.citg.tudelft.nl) is working towards releasing the files associated with assignments under an open license. Since the majority of the content is written in a storytelling style in Jupyter notebooks, a CC BY license is probably the best choice if only one license is applied to a single file. However, if released in bulk it may be better to follow the advice of [Matt Hall](https://agilescientific.com/blog/2021/2/17/which-open-licence-should-i-choose):
> You have to be practical; maybe it depends on whether you consider your notebooks to be 'content' or 'source code'. I sometimes put at the bottom of a notebook something like **Open source content. Text is CC-BY, code is Apache 2.0** and I think this makes my intent clear.

120
book/installation-and-setup/copyright/recommendations.md Normal file
View file

@ -0,0 +1,120 @@
(copyright_recommendations)=
# Recommendations
As authors, one important set of objectives is to make sure that we:
1. Avoid plagiarism and copyright infringement,
2. Properly attribute (reused) content, and
3. Indicate to readers where to find the original content,
4. Create a record for ourselves that clearly documents what we have used.
As item number 3 aligns with the standard approach of citation and references in academic writing, much of the work is already quite clear. At TeachBooks we use APA guidelines by default; instructions for implementing this in your book can be found on {ref}`this page<apa>`.
Addressing Items 1 and 2 can be overwhelming at first, but we have tried to illustrate them clearly in this manual. In particular, the sections in this chapter, especially this page, which collects best practices used by TeachBooks collaborators, along with explanations for why we do it that way. We try to present a standard way of referencing material and attributing authors clearly; however, this can vary widely based on your own content, book setup and discipline.
The recommendations illustrate:
1. An efficient and consistent approach to accomplish the objectives above, and
2. How you can implement this easily in the _source code of your own book._
We believe the approach outlined here is also a useful way for you as an author to _remember which material you have used in your book and find or update it later if changes are needed._ This is Item 4 in the list above, and hopefully avoids frustration in the future if you need to revise your book after a long period of inactivity and cannot remember what content was written by you, or written by others.
The recommendations on this page are designed for content that is available in two formats: _source code_ and a _public website._ Additionally, it is focused primarily on file formats and open content relevant to Jupyer Books, which means content written primarily in _text files_ (e.g., .md, .ipynb, etc.), also called _source code,_ shared with an open license and used to create a _website_ (e.g., HTML files accessible at a specific URL). Software is used to convert the source code into a website, however, this is generally not included in the creative content shared using the book license.
## Key Locations in the Book
Note that there are several types of pages and files that can be incorporated into your TeachBook which, together, accomplish our goals of proper attribution and referencing. These are summarized in the table and explained in more detail in the following sections, along with examples for implementation in a Jupyter Book.
```{list-table} Key Locations in the Book for Attribution and Referencing Best Practices
:header-rows: 1
:name: copyright_book_locations
* - Page Name
- File Name
- Example in this book
- Purpose
* - {ref}`Content Page<copyright_recc_content>`
- `*.md`, `*.ipynb`, etc.
- {ref}`Licenses page <copyright_licenses>`
- Identifies source and links to credits page.
* - {ref}`Credits and License Page<copyright_recc_credits>`
- `credits.md`
- [Credits page](credits)
- Collets license and copyright information in one place.
* - {ref}`References Page<copyright_recc_references>`
- `references.md`
- [References page](../../references.md)
- Documents all sources, as in any other published work.
* - {ref}`License Page<copyright_recc_license>`
- `LICENSE`
- File stored in repository [here](https://github.com/TeachBooks/manual/blob/release/LICENSE).
- Document license terms; includes licenses of reused content.
```
(copyright_recc_content)=
### Content Pages
Make sure you show the source of your content where it is provided. We adopt a standard icon and link to help readers recognize this: {fa}`quote-left`{ref}`Find out more here.<external_resources>`
#### How to implement this in your book
Copy the following line into your content file
```md
> This page reuses <license> content from {cite:t}`bib_id`. {fa}`quote-left`{ref}`Find out more here.<link to external resources section on credits and license page>`
```
Some examples can be found in this manual:
- [](../../external/deploy-book-workflow/README.md): a content page which is taken fully from another repository
- Figure {ref}`fig_license_types`: a single licensed figure added to a page taken from another website
- [](../copyright.md): a content page which adapts material from another website
(copyright_recc_credits)=
### Credits and License Page
This place describes all relevant information in one place regarding copyright and licenses, including reused content. This page should also be useful to the author returning to the book after a long period of inactivity.
#### How to implement this in your book
That's easy! Just copy the page [from out template](https://github.com/TeachBooks/template/blob/main/book/credits.md) and adapt to your purposes.
(copyright_recc_references)=
### References Page
Lists all references used in the book, including those not directly cited in the text (e.g., reused material).
A special case is made for material licensed under the public domain, for example, the "no rights reserved" [CC0 license](https://creativecommons.org/public-domain/cc0/). As these can include a large number of single files (e.g., images), each with their own link and author, by default we do not include these in the References Page, but we do list the source in the credits. This is especially useful for finding the material later, or allowing anyone who would like to reuse your content to find and cite the public domain source material directly.
One example in this manual is {ref}`fig_license_compatibility`, listed on the credits page {ref}`here<external_resources>`.
#### How to implement this in your book
Proper referencing typically involves setting up an entry in your `*.bib` file and using a citation key in the text on the content and Credits pages, which can be handled automatically if you are using the {ref}`APA references tool<apa>`. This also allows you to use the text (`t`) and parentheses (`p`) citation styles.
```
{cite:t}`cite_key`
{cite:p}`cite_key`
```
which produce these citations: text by {cite:t}`jason_moore`. And parentheses {cite:p}`jason_moore` when using {ref}`APA references tool<apa>`.
(copyright_recc_license)=
### License File
Specifies license and copyright of book, along with licenses of reused content also included in source code.
Entire file only included in source code. License type stated on Credits page and included in footer.
#### How to implement this in your book
Create a LICENSE file in the root of your repository (note that there is conventionally no extension in the file name). Platforms like GitHub and GitLab can help you with this via the home page of your repository (look for a button that says "Add a License").
The file should contain the full text of the license you have chosen for your book, along with any other licenses that apply to content you have reused. For example, the TeachBooks Manual uses a [CC BY 4.0 license](https://creativecommons.org/licenses/by/4.0/), which is included in the LICENSE file in the source code at [github.com/TeachBooks/manual](https://github.com/TeachBooks/manual/blob/release/LICENSE).
Note that although most of the license text can be created from a template by GitHub, you may still want to identify yourself as the author and/or the copyright holder at the top of the file. This provides clarity to readers and, if reusing your work, it is also easier for others to identify your license when including it in their own source code.
## Special Cases
Is there a special case you would like to know more about that is not covered here? Please let us know by creating an issue in the appropriate TeachBooks GitHub repository.
It can also be very useful to check what others commonly do in the open source community. Note, however, some discretion should be applied, as not everything you see on the internet is done properly. Our advice is to find a few good examples of people you can trust and copy them.
For example, when Robert and Tom are in this position, they often wonder WWJD? (What Would Jason Do?) Jason Moore has been making and (re)using open source material for a long time, and his GitHub repositories and websites at [github.com/moorepants](https://github.com/moorepants/) are a great source of inspiration!

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

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

2
book/installation-and-setup/tools.md
View file

@ -58,7 +58,7 @@ On GitLab a webserver is required to process book-changes online. Both we and ot
### Setting up book repository and website
On GitHub you can start right away with a git environment and online book using our [template](../external/template/README.md).
On GitLab you can set up your own git environment, but you need to be given access by [TeachBooks](mailto:teachbooks@tudelft.nl) or [TU Delft OIT](mailto:Interactive-textbooks@tudelft.nl) to view your build book online.
On GitLab you can set up your own git environment, but you need to be given access by [TeachBooks](mailto:info@teachbooks.io) or [TU Delft OIT](mailto:Interactive-textbooks@tudelft.nl) to view your build book online.
### Book access with SSO
When you’re releasing your book on a server on which you're in control (connected to GitLab or GitHub), you can set up SSO login for visitors of the website. This can be arranged for on the TeachBooks server.

22
book/intro.md
View file

@ -1,19 +1,19 @@
# TeachBooks Manual
This manual assists you in creating and collaborating on <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> 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 is primarily designed for and by teachers for use in education, but should be a useful resource for anyone interested in creating and collaborating on <a href="https://jupyterbook.org/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="images/logo-wide.svg" alt="Jupyter book"></a>. Our aim is to provide a simple way to start book-making for new users (it only takes 10 clicks!) through advanced usage for experienced users. We hope you find this resource useful and refer back to it often.
## Contact
If you encounter any issues and you have a TU Delft account, report it by clicking <svg class="svg-inline--fa fa-gitlab" aria-hidden="true" focusable="false" data-prefix="fab" data-icon="gitlab" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" data-fa-i2svg=""><path fill="currentColor" d="M503.5 204.6L502.8 202.8L433.1 21.02C431.7 17.45 429.2 14.43 425.9 12.38C423.5 10.83 420.8 9.865 417.9 9.57C415 9.275 412.2 9.653 409.5 10.68C406.8 11.7 404.4 13.34 402.4 15.46C400.5 17.58 399.1 20.13 398.3 22.9L351.3 166.9H160.8L113.7 22.9C112.9 20.13 111.5 17.59 109.6 15.47C107.6 13.35 105.2 11.72 102.5 10.7C99.86 9.675 96.98 9.295 94.12 9.587C91.26 9.878 88.51 10.83 86.08 12.38C82.84 14.43 80.33 17.45 78.92 21.02L9.267 202.8L8.543 204.6C-1.484 230.8-2.72 259.6 5.023 286.6C12.77 313.5 29.07 337.3 51.47 354.2L51.74 354.4L52.33 354.8L158.3 434.3L210.9 474L242.9 498.2C246.6 500.1 251.2 502.5 255.9 502.5C260.6 502.5 265.2 500.1 268.9 498.2L300.9 474L353.5 434.3L460.2 354.4L460.5 354.1C482.9 337.2 499.2 313.5 506.1 286.6C514.7 259.6 513.5 230.8 503.5 204.6z"></path></svg> --> {fa}`lightbulb` on the top right corner of this page. Or contribute directly by creating a merge request in the [repository](https://github.com/TeachBooks/manual).
TeachBooks originated at Delft University of Technology in the Netherlands, and some of the material in this Manual reflects tools and resources specific to TU Delft. With the exception of a few tools for which we have educational licenses at Delft, everything in this Manual is open source. Despite this, we are happy to grow our community beyond Delft and welcome contributions from all users.
If you have questions, contact Tom van Woudenberg, Robert Lanzafame or our TA Julie Kirsch at TeachBooks@tudelft.nl, also for non-TU Delft account holders. TU Delft account holder can also contact us in the [MS Teams Open Interactive Textbooks Community](https://teams.microsoft.com/l/team/19%3Ah9-uRcP_yYauh-VuoPFozJVUvHVOB4a0mz1ZWvh4q4Q1%40thread.tacv2/conversations?groupId=3e88c1f3-4a4f-483a-a366-7e617de9ba99&tenantId=096e524d-6929-4030-8cd3-8ab42de0887b)
For more information about TeachBooks, visit [https://teachbooks.io/](https://teachbooks.io/). Do not hesitate to reach out via email at [info@teachbooks.io](mailto:teachbooks@tudelft.nl) or contribute on GitHub via discussions, issues or pull requests.
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).
Happy book building!
## 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.
## How to Use this Manual
The released book can be found on on https://teachbooks.io/manual. This page shows the built book of the `release` branch. All branches will also be visible online, as pointed to in the actions summaries: https://github.com/TeachBooks/mirror_teachbook_manual/actions
There are several "parts" to the manual:
- **Your First TeachBook!** introduces the essential platforms and workflows, and contains a _workshop_ that can be completed independently or as part of a TeachBooks training. We recommend even experienced Jupyter Book users go through this material to better understand the TeachBooks vision on how to make books collaboratively, as this drives much of our tool development. The workshop is designed to be completed in 1-2 hours and does not require any prior knowledge or installation (just a GitHub account).
- **Getting Going!** begins with an overview of _User Types_, which are used to help understand which parts of the Manual are most relevant to you. Detailed software installation instructions, book and team setup and workflows are also provided in this part.
- The **Features** part describes a suite of tools that are useful for teachers, many of which are developed by TeachBooks contributors specifically for use in education. Many of these tools are illustrated in the **Examples**.
- A few special tools are included in the **Editing Tools** that are useful when writing content.
Some parts of this book are taken from other sources in the form of submodules (linked in the folder [book/external](https://github.com/TeachBooks/manual/tree/release/book/external)). To contribute to those pages, contribute to the source repository directly with a fork and merge/pull request. If you intent to clone this boko including its submodules, clone using: `git clone --recurse-submodules git@github.com:TeachBooks/manual.git`
Happy book building!
See the final chapters of this book (under **Miscellaneous**) for additional information about References, Credits, etc.

106
book/intro/book.md Normal file
View file

@ -0,0 +1,106 @@
# What is a TeachBook?
Never seen a TeachBook before? Here's a small demo of our MUDE-book!
<div style="display: flex; justify-content: center;">
<div style="position: relative; width: 100%; height: 0; padding-bottom: 56.25%;">
<iframe
src="https://www.youtube.com/embed/gbBsWo6em4c?si=ayKhISsx06LmGbDD"
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>
So what are you looking at? It's a website generated with the [Jupyter Book package](https://jupyterbook.org/). Various extensions have been added to improve the student-experience, especially for technical topics! The actual website you're looking at now is a Jupyter Book. With TeachBooks we aim to make it easy to collaboratively use it, even if you've little experience with the software package which is part of it.
## Three Key Ingredients
To create a Jupyter Book, three key ingredients are needed:
1. A **configuration file** to define functionalities, `_config.yml`
2. A **table of contents** file to list which files should end up in the book, `_toc.yml`, as well as define its structure
3. **Content** for your book! Text-based files which allows you to embed figures, videos, math and interactive elements.
The files are typically organized together in a files structure like this:
```
└── my_book_directory/
├── README.md
├── requirements.txt
└── book/
└── _config.yml
└── _toc.yml
└── contents/
└── intro.md
└── chapter1.md
└── chapter2.ipynb
└── images/
└── figure1.png
```
Note the arrangement of the 3 key book ingredients in a subdirectory called `book/`; this is where you should focus when you are just getting started with TeachBooks and are making your first book. Additional files can be used to control the book-building process, and these are typically stored _outside_ the `book/` directory to keep the book contents separate. For now, all you need to understand that everything needed to create a book can be collected in a single top-level directory (`my_book_directory/`, in this case), and this directory is what becomes the collection of files in our Git **repository** (described elsewhere).
`````{admonition} Text-based files? yml? What is that?!
:class: tip, dropdown
Text-based files are digital files on your computer that you can open in a text editor and read directly. There are many file extensions used for text-based files, a few common ones related to Jupyter Book are: Markdown (`*.md`), Jupyter Notebooks (`*.ipynb`), and YAML (`*.yml`).
YAML (or YML) is a text-based file format that is primarily used to store data. It is useful because it is easy for humans to read and write, and easy for machines to _parse_ and generate., which is why YAML is often used for configuration files. Here is an example of a YAML file...can you tell what information is being stored?
```yaml
parts:
- caption: Your First TeachBook!
chapters:
- file: intro/book.md
- file: intro/workflow.md
- file: intro/template.md
sections:
- file: external/teachbooks.md
```
````{admonition} Description of the YAML file
:class: tip, dropdown
You can see quite clearly that a number of files are listed, and that they are organized into chapters and sections. This defines the structure of the book---you can confirm this by comparing to the left sidebar, as this book is where this example YAML snippet came from!
````
`````
## How is a book made?
A book is made by by writing content in text-based files such as Markdown (`*.md`), Jupyter Notebooks (`*.ipynb`), etc. After that, software is used to "parse" these files and create the final book (e.g., Jupyter Book). Fortunately when getting started you don't need to worry about the software because TeachBooks has set up GitHub tools for you that take care of this process automatically! The process is illustrated in the diagram below.
```{figure} figures/intro-book.svg
---
width: 700px
---
The process of building a book with TeachBooks. When just getting started, TeachBooks tools enables you to focus on what matters most: learning to write content for your book!
```
```{admonition} Familiar with LaTeX? There are similarities!
:class: dropdown
Have you ever used LaTeX? It turns out there are a lot of similarities with Jupyter Book. Here is a quick list:
1. Writing "source code" in text-based files (i.e., `*.tex` versus `*.md`, `*.ipynb`, etc) that is generally easy to read without the markup and uses special functions to format rich document objects (e.g., tables, figures, etc).
2. The "book" is created by using a piece of software that parses the source code and creates the final document (a `*.pdf` versus a `*.html` for Jupyter Book).
3. Creating the document structure using a list of files that contain source code that automatically generates the Table of Contents and Index..
4. Sometimes you can spend more time than you like troubleshooting "bugs" that turn out to be simple syntax errors.
If you've used LaTeX before, it will be relatively easy to learn to use a Jupyter Book.
```
## Why are Git and GitHub Important?
The fun part is the collaborative aspect of TeachBooks! However, the amount of software required _when doing this by yourself_ can be intimidating. Git and GitHub are tools used by TeachBooks to make this process as smooth as possible for newcomers.
There are three reasons why Git and GitHub are important for TeachBooks:
1. **Version control**: Git is a version control system that allows you to track changes to your files over time. This is especially useful when you're working with others on a book, as it allows you to see who made what changes and when.
2. **Collaboration**: GitHub is a company that provides a wide array of online tools. These _augment_ the version control features incorporated directly in Git. In short, tools at `github.com` allow you to share your files with others and work on them together. This is especially useful when you're working on a book with multiple authors, as it allows you to easily share your work and collaborate.
3. **Automation**: GitHub provides a number of tools that can help automate the process of building your book. TeachBooks has carefully developed a number of these tools specifically to support teachers and students in the process of creating and sharing educational content.
## What's next?
The following pages will introduce you to a standard "workflow" for editing a book, which is focused entirely in the "source code" of a book (the first box in the diagram above). After we cover this, you'll be ready to make your first book!

1006
book/intro/figures/TeachBooks_flowchart.svg Normal file
View file

File diff suppressed because it is too large Load diff
Side by side

After

Width:  |  Height:  |  Size: 79 KiB

BIN
book/intro/figures/branch.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 7.6 KiB

BIN
book/intro/figures/check.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
book/intro/figures/edit.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
book/intro/figures/idea.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 5 KiB

350
book/intro/figures/intro-book.svg Normal file
View file

@ -0,0 +1,350 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
width="328.00415mm"
height="116.89093mm"
viewBox="0 0 1239.7008 441.7925"
version="1.1"
id="svg1"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns="http://www.w3.org/2000/svg"
xmlns:svg="http://www.w3.org/2000/svg">
<defs
id="defs1">
<rect
x="855.04938"
y="772.0968"
width="0"
height="48.495338"
id="rect29" />
<rect
x="-14.038124"
y="903.54468"
width="1069.4498"
height="246.30527"
id="rect19" />
<linearGradient
id="swatch7">
<stop
style="stop-color:#000000;stop-opacity:1;"
offset="0"
id="stop7" />
</linearGradient>
<marker
style="overflow:visible"
id="marker4-4-1"
refX="0"
refY="0"
orient="auto-start-reverse"
markerWidth="1"
markerHeight="1"
viewBox="0 0 1 1"
preserveAspectRatio="xMidYMid">
<path
style="fill:none;stroke:context-stroke;stroke-width:1;stroke-linecap:round"
d="M 3,-3 0,0 3,3"
transform="rotate(180,0.125,0)"
id="path4-9-32" />
</marker>
<marker
style="overflow:visible"
id="marker4-4-4-95"
refX="0"
refY="0"
orient="auto-start-reverse"
markerWidth="1"
markerHeight="1"
viewBox="0 0 1 1"
preserveAspectRatio="xMidYMid">
<path
style="fill:none;stroke:context-stroke;stroke-width:1;stroke-linecap:round"
d="M 3,-3 0,0 3,3"
transform="rotate(180,0.125,0)"
id="path4-9-3-8" />
</marker>
<marker
style="overflow:visible"
id="marker4-4-2-8"
refX="0"
refY="0"
orient="auto-start-reverse"
markerWidth="1"
markerHeight="1"
viewBox="0 0 1 1"
preserveAspectRatio="xMidYMid">
<path
style="fill:none;stroke:context-stroke;stroke-width:1;stroke-linecap:round"
d="M 3,-3 0,0 3,3"
transform="rotate(180,0.125,0)"
id="path4-9-4-0" />
</marker>
<linearGradient
xlink:href="#swatch7"
id="linearGradient1"
gradientUnits="userSpaceOnUse"
gradientTransform="matrix(0.75152949,0,0,0.67302847,1183.5248,88.848777)"
x1="91.00753"
y1="204.44643"
x2="440.43915"
y2="204.44643" />
<linearGradient
xlink:href="#swatch7"
id="linearGradient2"
gradientUnits="userSpaceOnUse"
gradientTransform="matrix(0.75177303,0,0,0.64991433,1183.4601,90.383898)"
x1="91.00753"
y1="204.44643"
x2="440.43915"
y2="204.44643" />
<linearGradient
xlink:href="#swatch7"
id="linearGradient6"
gradientUnits="userSpaceOnUse"
gradientTransform="matrix(0.75182225,0,0,0.6452922,1183.447,90.690792)"
x1="91.00753"
y1="204.44643"
x2="440.43915"
y2="204.44643" />
<linearGradient
xlink:href="#swatch7"
id="linearGradient7"
gradientUnits="userSpaceOnUse"
gradientTransform="matrix(0.75162636,0,0,0.66378216,1505.0997,-102.68981)"
x1="91.00753"
y1="204.44643"
x2="440.43915"
y2="204.44643" />
<linearGradient
xlink:href="#swatch7"
id="linearGradient8"
gradientUnits="userSpaceOnUse"
gradientTransform="matrix(1.2756681,0,0,0.50207641,1134.8588,176.12325)"
x1="91.00753"
y1="204.44643"
x2="440.43915"
y2="204.44643" />
<linearGradient
xlink:href="#swatch7"
id="linearGradient10"
gradientUnits="userSpaceOnUse"
gradientTransform="matrix(2.1328887,0,0,0.21024579,896.86559,157.30107)"
x1="91.00753"
y1="204.44643"
x2="440.43915"
y2="204.44643" />
</defs>
<g
id="g36"
transform="translate(-58.905582,-716.40082)">
<g
id="g35"
style="display:inline"
transform="translate(-1256.1396,-20.75745)">
<g
id="g10-8"
transform="translate(-443.02906,835.34419)"
style="display:inline">
<g
id="g45-2"
transform="translate(510.79547,-230.4935)"
style="stroke-width:3.77953;stroke-dasharray:none">
<rect
style="fill:#85a5ff;fill-opacity:1;stroke:url(#linearGradient1);stroke-width:4.95847;stroke-linejoin:miter;stroke-dasharray:none"
id="rect1-1-3"
width="262.60815"
height="183.32053"
x="1251.9197"
y="134.78676"
ry="17.516886" />
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:37.3333px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:3.77953;stroke-dasharray:none;stroke-opacity:1"
x="1382.3889"
y="189.92847"
id="text45-2"><tspan
id="tspan21"
x="1382.3889"
y="189.92847"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:37.3333px;font-family:Sans;-inkscape-font-specification:'Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal">Source Code</tspan><tspan
id="tspan23"
x="1382.3889"
y="236.59509"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:37.3333px;font-family:Sans;-inkscape-font-specification:'Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal">(Repository)</tspan><tspan
x="1382.3889"
y="283.26172"
id="tspan25"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:29.3333px;font-family:'Courier New';-inkscape-font-specification:'Courier New, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal">*.md, *.ipynb</tspan></text>
</g>
<g
id="g45-7-6"
transform="translate(1480.768,-225.14112)"
style="stroke-width:3.77953;stroke-dasharray:none">
<rect
style="fill:#85a5ff;fill-opacity:1;stroke:url(#linearGradient2);stroke-width:4.87337;stroke-linejoin:miter;stroke-dasharray:none"
id="rect1-1-1-4"
width="262.69327"
height="177.02466"
x="1251.8771"
y="134.7442"
ry="16.915295" />
<text
xml:space="preserve"
style="font-size:37.3333px;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:3.77953;stroke-dasharray:none;stroke-opacity:1"
x="1388.7699"
y="212.89993"
id="text45-7-6"><tspan
x="1388.7699"
y="212.89993"
id="tspan8-1"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:37.3333px;font-family:Sans;-inkscape-font-specification:'Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal">Online Book</tspan><tspan
x="1388.7699"
y="259.56656"
id="tspan9-3"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:37.3333px;font-family:Sans;-inkscape-font-specification:'Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal">(webserver)</tspan></text>
</g>
<g
id="g45-3-6"
transform="translate(1155.396,-225.30267)"
style="stroke-width:3.77953;stroke-dasharray:none">
<rect
style="fill:#85a5ff;fill-opacity:1;stroke:url(#linearGradient6);stroke-width:4.85617;stroke-linejoin:miter;stroke-dasharray:none"
id="rect1-1-0-4"
width="262.71048"
height="175.76567"
x="1251.8685"
y="134.7356"
ry="16.794992" />
<text
xml:space="preserve"
style="font-size:37.3333px;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:3.77953;stroke-dasharray:none;stroke-opacity:1"
x="1382.389"
y="209.07137"
id="text45-0-65"><tspan
x="1382.389"
y="209.07137"
id="tspan31"><tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:37.3333px;font-family:'Courier New';-inkscape-font-specification:'Courier New, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal"
id="tspan28">html</tspan> <tspan
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:37.3333px;font-family:Sans;-inkscape-font-specification:'Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal"
id="tspan34">files</tspan></tspan><tspan
x="1382.389"
y="256.48807"
id="tspan29"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:37.3333px;font-family:Sans;-inkscape-font-specification:'Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal">(website)</tspan></text>
</g>
<g
id="g11-0"
style="stroke-width:3.77953;stroke-dasharray:none"
transform="translate(510.75613,-36.94968)">
<rect
style="fill:#85a5ff;fill-opacity:1;stroke:url(#linearGradient7);stroke-width:4.92461;stroke-linejoin:miter;stroke-dasharray:none"
id="rect1-1-5-0"
width="262.64203"
height="180.802"
x="1573.5034"
y="-57.382954"
ry="17.276232" />
<text
xml:space="preserve"
style="font-size:37.3333px;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:3.77953;stroke-dasharray:none;stroke-opacity:1"
x="1706.542"
y="2.3280809"
id="text45-1-7"><tspan
x="1706.542"
y="2.3280809"
id="tspan5-0"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:29.3333px;font-family:Sans;-inkscape-font-specification:'Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal">Markup</tspan><tspan
x="1706.542"
y="48.994709"
id="tspan6-6"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:29.3333px;font-family:Sans;-inkscape-font-specification:'Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal">Software</tspan><tspan
x="1706.542"
y="95.661331"
id="tspan26"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:29.3333px;font-family:'Courier New';-inkscape-font-specification:'Courier New, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal">jupyter-book</tspan></text>
</g>
<path
style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:6.37227;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker4-4-1)"
d="m 2349.7386,-5.6622197 h 45.0073"
id="path52-4-7" />
<path
style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:6.37227;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker4-4-4-95)"
d="m 2027.9658,-6.1471948 h 45.0073"
id="path52-4-9-7" />
<path
style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:6.37227;stroke-dasharray:none;stroke-opacity:1;marker-end:url(#marker4-4-2-8)"
d="m 2674.0343,-4.1283267 h 45.0073"
id="path52-4-3-3" />
<text
xml:space="preserve"
transform="translate(1699.1687,-814.58674)"
id="text29"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:37.3333px;font-family:'Courier New';-inkscape-font-specification:'Courier New, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;white-space:pre;shape-inside:url(#rect29);opacity:0;fill:#3b60e4;fill-opacity:1;stroke:#3b60e4;stroke-opacity:1" />
</g>
<g
id="g45-2-6"
transform="translate(66.880941,829.0118)"
style="display:inline;stroke-width:3.77953;stroke-dasharray:none">
<rect
style="fill:#85a5ff;fill-opacity:1;stroke:url(#linearGradient8);stroke-width:5.57972;stroke-linejoin:miter;stroke-dasharray:none"
id="rect1-1-3-5"
width="445.7587"
height="136.75632"
x="1250.9541"
y="210.39278"
ry="13.067522" />
<text
xml:space="preserve"
style="font-size:37.3333px;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:3.77953;stroke-dasharray:none;stroke-opacity:1"
x="1475.551"
y="269.05243"
id="text45-2-1"><tspan
x="1475.551"
y="269.05243"
id="tspan19"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:37.3333px;font-family:Sans;-inkscape-font-specification:'Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal">You edit text-based files</tspan><tspan
x="1475.551"
y="315.71906"
id="tspan32"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:37.3333px;font-family:Sans;-inkscape-font-specification:'Sans, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal">(source code)</tspan></text>
<text
xml:space="preserve"
transform="translate(1189.2586,-817.18775)"
id="text19"
style="font-size:29.3333px;font-family:Sans;-inkscape-font-specification:'Sans, Normal';text-align:center;white-space:pre;shape-inside:url(#rect19);opacity:0;fill:#3b60e4;fill-opacity:1;stroke:#3b60e4;stroke-opacity:1" />
</g>
<rect
style="display:inline;fill:#85a5ff;fill-opacity:1;stroke:url(#linearGradient10);stroke-width:4.66881;stroke-linejoin:miter;stroke-dasharray:none"
id="rect1-1-0-4-0"
width="745.29883"
height="57.267071"
x="1090.9745"
y="171.65152"
ry="5.4720592"
transform="translate(712.75782,905.66944)" />
<text
xml:space="preserve"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:37.3333px;font-family:sans-serif;-inkscape-font-specification:'sans-serif, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;text-align:center;text-anchor:middle;display:inline;fill:#000000;fill-opacity:1;stroke:none;stroke-width:3.77953;stroke-dasharray:none;stroke-opacity:1"
x="1464.0653"
y="214.17613"
id="text45-0-65-5"
transform="translate(712.75782,905.66944)"><tspan
id="tspan35"
x="1464.0653"
y="214.17613">TeachBooks tools and GitHub do the rest!</tspan></text>
<path
style="fill:none;fill-opacity:1;stroke:#3b60e4;stroke-width:12.6442;stroke-dasharray:none;stroke-opacity:1"
d="m 2547.6959,946.20592 v 36.15346 h -903.2871 v -36.15346"
id="path58-3" />
<path
style="fill:none;fill-opacity:1;stroke:#3b60e4;stroke-width:11.8218;stroke-dasharray:none;stroke-opacity:1"
d="m 2082.4994,1066.7287 0.2586,-77.80903"
id="path58-3-4" />
<path
style="fill:none;fill-opacity:1;stroke:#3b60e4;stroke-width:12.6442;stroke-dasharray:none;stroke-opacity:1"
d="m 1448.766,1025.3091 0.2576,-89.33348"
id="path58-3-4-3" />
</g>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
book/intro/figures/online.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 22 KiB

BIN
book/intro/figures/review.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 7.8 KiB

BIN
book/intro/figures/template.jpg Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 31 KiB

20
book/intro/next.md Normal file
View file

@ -0,0 +1,20 @@
# You Know the Basics: What Next?
You've seen what a JupyterBook is, how TeachBooks tries to help you with making those, and what the potential is in teaching. So what's next?
In this manual we explain how to get going depending on the way you want to use it. If you successfully followed the steps until here, you'll be able to make book as a 'user type 3'!
```{figure} ../installation-and-setup/figures/usertype3.jpg
---
name: usertype1
width: 300px
align: center
---
User type 3
```
In the next part of this manual 'Getting going!', we'll explain which options you have as more advanced user, how to collaboratively edit books en how to organize you team, tools, websites and copyright-considerations.
Furthermore, in the 'Features' part we'll collect a suite of existing open-source software to ease the editing process, add functionalities, improve styling and improve the student-experience. Finally, the 'Examples' page contain some example pages of some book.
We hope you enjoin making books with TeachBooks. If you encounter any problem, please reach out to us on [email](mailto:info@teachbooks.io) or our [GitHub Discussions](https://github.com/orgs/TeachBooks/discussions). We'd be happy to collaborate with you or simple receive some feedback, examples, cool ideas. Happy book building!

52
book/intro/template.md Normal file
View file

@ -0,0 +1,52 @@
# It only takes 10 clicks!
```{figure} figures/template.jpg
---
name: template
width: 150px
align: right
```
Now that you've been introduced to the basics of a Jupyter Book, let's make one! The TeachBooks Team has put together a set of tools to make the book-creation process as smooth and automatic as possible. This page guides you through the process of creating a book, followed by a series of exercises that are designed to help you get used to the syntax and structure of a Jupyter Book, as well as the tools and essential workflows associated with the editing, checking and review processes.
## 1. Create a GitHub account
TeachBooks relies of freely available services from GitHub to store files online, carry out the book-building process and host your book as a website. All you need to get started is a GitHub account (not counted in the 10 clicks 🤭).
```{exercise}
If you don't already have one, create a GitHub account here by visiting [github.com/signup](https://github.com/signup).
```
## 2. Use the template---it's really just 10 clicks!
Now, let's make a book: we've made a template on GitHub which carries out _most_ of the technical steps required to create a book and put it online. Instructions for using the template are in the `README` of the TeachBooks Template repository on GitHub, which is by default visible on the repository homepage.
```{exercise}
Go to the [TeachBooks Template repository on GitHub](https://github.com/TeachBooks/template) and follow the instructions to create your book. At the end, it should be visible at `<your_username>.github.io/<book>`. When finished, come back to this page.
```
## 3. Let's practice!
Getting used to the syntax of writing in a Jupyter Book can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises have been prepared for you The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages.
The exercises can be found in your book at `https://<username or organiszation_name>.github.io/<repository_name>/exercises/exercises` (case sensitive) or at https://teachbooks.io/template/exercises.html.
```{figure} ../external/template/figures/exercises.png
---
name: exercises
width: 200px
align: center
```
```{tip}
Maybe you're already comfortable with Git, GitHub and the concept of using software to parse text-based files and create marked-up documents. In that case, can you answer the following questions (refering to the exercises):
1. Can you add some content to the intro page?
2. Can you add the file named `file_to_be_added_to_toc.md` to the book website?
3. Can you edit the repository url defined in the `_config.yml`, change the title shown below the logo and change the author as shown in the footer?
4. Can you make a new branch of your book with an additional file `file_on_new_version.md` and view it online?
5. Can you merge your branch into `main` with a pull request?
6. Can you fork someone else's repo, and suggest a change in a pull request?
If something is not clear, dive into to the relevant exercise page.
```

55
book/intro/workflow.md Normal file
View file

@ -0,0 +1,55 @@
# How can you do it?
The fun part is the collaborative aspect of TeachBooks! Because all the files are text-based, they're well suited for using git. That allows us to use the version-control principles of git to its best!
Assuming you have a book (well make that happen soon!) and you're ready to collaborate, the process is as follows:
## 1 get an idea
```{figure} figures/idea.png
---
width: 70px
align: right
```
You have an idea to improve a book or add some content! Let's make that happen! Share you idea with the book-authors to let them know you're starting something! Maybe someone else has some ideas on it as well. Later on, you can use GitHub `Issues`, `Projects` and `Milestones` to keep track of this.
## 2 create your version of the book
```{figure} figures/branch.png
---
width: 100px
align: right
```
Let's create a space for you idea to form. You can create your own version of the book, visible for everyone to see. On GitHub, you'll use `branches` or `forks`.
## 3 edit the book
```{figure} figures/edit.png
---
width: 100px
align: right
```
Creativity activated, let's start adding content to your book! You'll add text, images, videos, math, interactive quizes, coding, widgets, etc. As editing the book is not directly done in a graphical interface with buttons like Microsoft Word, you'll need to learn a bit of syntax. The [MyST syntax cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) will be added to your bookmarks. The changes you'll make have to be added to the GitHub version control system, creating `commits` on the your git `branch`.
## 4 check changes
```{figure} figures/check.png
---
width: 100px
align: right
```
You've made a change, how does is look like? Your raw file have to be parsed. You can do that yourself or use the tooling provided by use in a GitHub `Action`. As soon as you uploaded (`pushed` in Git language) your changes to GitHub, it'll create a nice looking website for you!
## 5 repeat, edit and check
```{figure} figures/review.png
---
width: 100px
align: right
```
You'll make mistakes and you'll want to alter content... many, many times... As long as your idea is not ready to be shared with other, keep iterating step 3 and 4 until it's perfect!
## 6 submit for review
```{figure} figures/online.png
---
width: 100px
align: right
```
You're done! Great! Now let's see what others think of your contribution. You'll submit your changes to the original book, in GitHub language this is called a `Pull request`. Other will be able to review, adapt and eventually `merge` your version into the book!
I hope that all of this seems fun! Let's continue on making this happen!

21
book/intro/workshop/summary.md Normal file
View file

@ -0,0 +1,21 @@
# Summary of Workshop: All Exercises
With the exercises, you did all the steps of our TeachBooks workflow!
```{figure} ../figures/TeachBooks_flowchart.svg
---
width: 500px
align: center
---
```
Here is how the exercises relate to the workflow.
| Step No. | Name | Exercise | Description |
| :---: | :---: | :---: | :---: |
| 1 | Get and idea | 4 | Create an issue |
| 2 | Create _your_ version of the book | 4 | Create a branch |
| 3 | Edit the book | 1, 2, 3| Editing `.md`-files, the `_toc.yml` and the `_config.yml` |
| 4 | Check changes online | 1, 2, 3 | Workflows and Actions Summary |
| 5 | Repeat edit and checking | 1, 2, 3, 4, 5 | Keep on doing all the steps until it's ready|
| 6 | Submit for review | 5, 6 | Open and merge a Pull Request, from a branch or forks |

120
book/references.bib Normal file
View file

@ -0,0 +1,120 @@
@misc{timon_latex,
title={LaTeX to Markdown conversion},
author={Idema (Delft University of Technology), Timon},
institution ={Delft University of Technology},
url={https://gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion},
year={2024},
note = {Retrieved December, 2024. BSD-3.}
}
@misc{hall21,
author = {Hall, Matt},
title = {Which open licence should I choose?},
institution = {Agile Scientific},
url = {https://agilescientific.com/blog/2021/2/17/which-open-licence-should-i-choose},
year = {2021},
note = {Online; posted 17-February-2021. CC BY.}
}
@misc{jason_moore,
title={Learn Multibody Dynamics, SymPy},
author={Moore, Jason},
url={https://moorepants.github.io/learn-multibody-dynamics/sympy.html},
year={2023}
}
@misc{tud_cip_24,
author = {{TU Delft Library}},
title = {Copyright Information Point},
url = {https://www.tudelft.nl/library/support/copyright},
year = {2024},
note = {Retrieved December, 2024. CC BY 4.0.}
}
@misc{deploy_book,
author = {{TeachBooks}},
title = {GitHub reusable action: publish your book online to GitHub Pages},
url = {https://github.com/TeachBooks/deploy-book-workflow},
year = {2024},
note = {Retrieved December, 2024. BSD-3-Clause.}
}
@misc{download_link,
author = {{TeachBooks}},
title = {Sphinx extension: download link replacer},
url = {https://github.com/TeachBooks/Download-Link-Replacer},
year = {2024},
note = {Retrieved December, 2024. BSD-3-Clause.}
}
@misc{patches,
author = {{TeachBooks}},
title = {Sphinx extension: JupyterBook-Patches},
url = {https://github.com/TeachBooks/JupyterBook-Patches},
year = {2024},
note = {Retrieved December, 2024. BSD-3-Clause.}
}
@misc{annotator,
author = {{TeachBooks}},
title = {Local Annotator Extension},
url = {https://github.com/TeachBooks/annotator},
year = {2024},
note = {Retrieved December, 2024. BSD-3-Clause.}
}
@misc{nested,
author = {{TeachBooks}},
title = {Git workflow: Share content between book},
url = {https://github.com/TeachBooks/Nested-Books},
year = {2024},
note = {Retrieved December, 2024. CC BY 4.0.}
}
@misc{grasple,
author = {{TeachBooks}},
title = {Sphinx extension: Grasple},
url = {https://github.com/TeachBooks/Sphinx-Grasple-public},
year = {2024},
note = {Retrieved December, 2024. MIT.}
}
@misc{image,
author = {{TeachBooks}},
title = {Sphinx extension: Image Inverter},
url = {https://github.com/TeachBooks/Sphinx-Image-Inverter},
year = {2024},
note = {Retrieved December, 2024. BSD-3-Clause.}
}
@misc{tudelft_theme,
author = {{TeachBooks}},
title = {Sphinx extension: TU Delft theme},
url = {https://github.com/TeachBooks/Sphinx-TUDelft-theme},
year = {2024},
note = {Retrieved December, 2024. MIT.}
}
@misc{tippy,
author = {{TeachBooks}},
title = {TeachBooks Sphinx extension: Rich hover over tips},
url = {https://github.com/TeachBooks/teachbooks-sphinx-tippy},
year = {2024},
note = {Retrieved December, 2024. MIT.}
}
@misc{template,
author = {{TeachBooks}},
title = {Your first TeachBook using the GitHub template},
url = {https://github.com/TeachBooks/template},
year = {2024},
note = {Retrieved December, 2024. CC BY 4.0.}
}
@misc{useful_code,
author = {{TeachBooks}},
title = {Useful python code},
url = {https://github.com/TeachBooks/Useful_python_code},
year = {2024},
note = {Retrieved December, 2024. BSD-3-Clause.}
}

3
book/references.md Normal file
View file

@ -0,0 +1,3 @@
# References
:::{bibliography}
:::

410
book/workflows/edit_book.md
View file

@ -18,45 +18,50 @@ In GitLab, you can directly make changes in the files on the remote repository.
2. Create a new file by clicking on the plus button in the top bar. You can either create an entirely new file by clicking `New File` or if you already have created a file you can upload it by clicking `Upload File`.
```{figure} figures/User3_NewFile.PNG
---
width: 60%
align: center
---
Create new file
```
3. In the new window, you can start typing your content. Give your file a name and make sure to use the markdown extension: `Chapter1.md`. Once you are done, commit the new file to the repository by clicking the blue button `Commit changes`.
```{figure} figures/User3_NewFile2.PNG
---
align: center
---
Edit new file
```
4. In case you want to make changes to an existing file, navigate to the file in your remote repository. Then click the blue button called `Edit` and select the option `Edit single file`.
```{figure} figures/User3_EditFile.PNG
---
align: center
---
Web Editor
```
5. Make your changes in the text editor and when you are ready, commit your changes to the remote repository by clicking on the blue `Commit changes` button.
```{figure} figures/User3_NewFile2.PNG
---
align: center
---
Commit changes
```
6. In case you added a new file, you also need to include it table of contents of your book! The table of contents is specified in a file called `toc.yml` and it is already included in your repository if you used the teachbooks template. You can edit it and commit the changes in the same manner as you did with markdown `file.md` files.
```{figure} figures/User3_toc.PNG
---
align: center
---
Table of contents (TOC)
```
``````
``````
``````{tab-item} ... GitHub...
`````{tab-set}
@ -88,36 +93,40 @@ Create new file
3. In the new window, you can start typing your content. Give your file a name and make sure to use the markdown extension: `file_name.md`. Once you are done, commit the new file to the repository by clicking the green button `Commit changes`.
```{figure} figures/HubUser3_NewFile2.PNG
---
width: 80%
align: center
---
Edit new file
```
4. In case you want to make changes to an existing file, navigate to the file in your remote repository. Then click the downward pointing arrow on the very left in the top bar. Select the option `Edit in place`.
```{figure} figures/HubUser3_EditFile.PNG
---
width: 80%
align: center
---
Edit in place
```
5. Make your changes in the text editor and when you are ready, commit your changes to the remote repository by clicking on the green `Commit changes` button.
```{figure} figures/HubUser3_EditFile2.PNG
---
width: 80%
align: center
---
Commit changes
```
6. In case you added a new file, you also need to include it table of contents of your book! The table of contents is specified in a file called `toc.yml` and it is already included in your repository if you used the teachbooks template. You can edit it and commit the changes in the same manner as with markdown `(file.md)` files.
```{figure} figures/HubUser3_toc.PNG
---
width: 80%
align: center
---
Table of contents
```
````
@ -157,52 +166,19 @@ name: user4_clone_edit_demo
Demonstration, video available [here](https://youtu.be/bThimdDRXTc)
```
1. Make some changes to a file in for example VS Code and save them.
**Make some changes to a file in for example VS Code and save them**
2. Select the files ready to be added to Git-timeline (staging).
For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu:
```{figure} ../images/git-new-file.png
The new file appears in the Source Control menu.
```{include} stage_commit_push_vscode.md
```
Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file.
3. Adding changes to the Git-timeline (committing)
Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this:
```{figure} ../images/git-file-added.png
The new file has been staged, and we've written a Commit Message.
```
Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu.
4. In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab.
```{figure} ../images/git-push.png
After committing, click the 🔄 button to push our changes to the remote repository.
```
````
````{tab-item} ... GitHub Desktop
1. Make some changes to a file in for example VS Code and save them.
**Make some changes to a file in for example VS Code and save them**
2. The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*.
```{include} stage_commit_push_github_desktop.md
```
<figure align="center">
<img src="figures/Stage_GitHubDekstop.PNG" alt="Example Image" width="400">
</figure>
3. Add changes to Git-timeline locally (committing). In the field that says `Summary(Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, click the blue button `Commit to repository`.
4. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repository. After committing, click on `Push origin` in the top bar.
<figure align="center">
<img src="figures/Push_GitHubDesktop.PNG" alt="Example Image" width="650">
</figure>
````
`````
``````
@ -219,7 +195,9 @@ After committing, click the 🔄 button to push our changes to the remote reposi
`````{tab-set}
````{tab-item} ... Git in VS Code
1. If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repository with your local repository on your machine. On the left side-bar click on the icon that looks like a branch.
**Regularly obtain updates from colleagues from GitLab/GitHub (pulling)**
If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repository with your local repository on your machine. On the left side-bar click on the icon that looks like a branch.
<figure align="center">
<img src="figures/VSCode_Pull.PNG" alt="Example Image" width="400">
@ -227,7 +205,9 @@ After committing, click the 🔄 button to push our changes to the remote reposi
By clicking on the 🔄 button, you will pull your colleages' changes.
2. When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repository, Git in VS Code will recognize conflicts and help you to solve potential incompatible changes (merging conflicts). Open the files that are marked as conflicitng.
**Solving potential incompatible changes (merging conflicts)**
When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repository, Git in VS Code will recognize conflicts and help you to solve potential incompatible changes (merging conflicts). Open the files that are marked as conflicitng.
<figure align="center">
<img src="figures/Conflicts2.PNG" alt="Example Image" width="650">
@ -241,47 +221,28 @@ The figure above shows the conflicts. If you look closely you can see that the l
Choose one of the options to resolve the merge conflict. You now have updated your work with work from your colleagues and resolved potential conlicts. You are now ready to continue working on the content.
3. Make some further changes to a file in for example VS Code and save them.
**Make some further changes to a file in for example VS Code and save them**
4. Select the files ready to be added to Git-timeline (staging)
For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu:
```{figure} ../images/git-new-file.png
The new file appears in the Source Control menu.
```{include} stage_commit_push_vscode.md
```
Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file.
5. Adding changes to the Git-timeline (committing)
Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this:
```{figure} ../images/git-file-added.png
The new file has been staged, and we've written a Commit Message.
```
Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu.
6. In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab.
```{figure} ../images/git-push.png
After committing, click the 🔄 button to push our changes to the remote repository.
````
````{tab-item} ... GitHub Desktop
1. If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repository with your local repository on your machine. Click on `Fetch` in the top bar. Then on the same place, click on 'Pull'.
**Regularly obtain updates from colleagues from GitLab/GitHub (pulling)**
If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repository with your local repository on your machine. Click on `Fetch` in the top bar. Then on the same place, click on 'Pull'.
<figure align="center">
<img src="figures/Fetch.PNG" alt="Example Image" width="650">
</figure>
2. When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repository, GitHub Desktop will recognize conflicts and help you to solve potential incompatible changes (merging conflicts).
**Solving potential incompatible changes (merging conflicts)**
When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repository, GitHub Desktop will recognize conflicts and help you to solve potential incompatible changes (merging conflicts).
<figure align="center">
<img src="figures/Conflicts1.PNG" alt="Example Image" width="650">
<img src="figures/Conflicts1.PNG" alt="Example Image" width="450">
</figure>
In this case there are two conflicted files. GitHub Desktop is suggesting to resolve the changes in VS Code (in that case have a look at the section treating VS Code). By clicking on the small downwards arrow you can also solve the conflict directly in GitHub Desktop by choosing the branch of the file you want to keep.
@ -298,21 +259,10 @@ The figure above shows the conflicts. If you look closely you can see that the l
Choose one of the options to resolve the merge conflict. You now have updated your work with work from your colleagues and resolved potential conlicts. You are now ready to continue working on the content.
3. Make some further changes to a file in for example VS Code and save them.
**Make some further changes to a file in for example VS Code and save them**
4. The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*.
<figure align="center">
<img src="figures/Stage_GitHubDekstop.PNG" alt="Example Image" width="400">
</figure>
5. Add changes to Git-timeline locally (committing). In the field that says `Summary(Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, click the blue button `Commit to repository`.
6. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repository. After committing, click on `Push origin` in the top bar.
<figure align="center">
<img src="figures/Push_GitHubDesktop.PNG" alt="Example Image" width="650">
</figure>
```{include} stage_commit_push_github_desktop.md
```
````
````{tab-item} ... using 'VS Code in your browser'
@ -351,151 +301,25 @@ name: user5_demo
Demonstration, video available [here](https://youtu.be/2ttjBevkEP8)
```
1. Make some changes to a file in for example VS Code and save them.
**Make some changes to a file in for example VS Code and save them**
2. Once all the changes are made, it can be useful to check the changes locally on your device.<br />
By doing that you can preview how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy.
Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
You will firstly need to activate the right environment. Type the following command:
```
conda activate jupyter-book-env
```{include} user45_check_changes.md
```
(or the environment in which you have installed the `teachbooks` package!)
Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command:
```
teachbooks build <path-to-book>
```{include} stage_commit_push_vscode.md
```
Alternatively:
```
jupyter-book build <path-to-book>
```
Note: use `--all` for the `teachbook` or `jupyter-book` command whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book.
Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following:
```{figure} figures/buildbook.PNG
Output
```
Paste the last line into your browser to see the updated changes.
```{Note}
Sometimes there are problems building the book. It could be that the building requires extensions that are not present in your environment. To prevent issues, make sure to update your environment by routinely updating your packages. You can do this by executing the following line in your environment in the command line.
`pip install -r requirements.txt --upgrade`
```
If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server]
3. If you are satisfied with your changes, you can select the files ready to be added to Git-timeline (staging)
For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu:
```{figure} ../images/git-new-file.png
The new file appears in the Source Control menu.
```
Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file.
4. Adding changes to the Git-timeline (committing)
Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this:
```{figure} ../images/git-file-added.png
The new file has been staged, and we've written a Commit Message.
```
Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu.
5. Adding changes to GitLab/GitHub (pushing)
In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab/GitHub.
```{figure} ../images/git-push.png
After committing, click the 🔄 button to push our changes to the remote repository.
````
````{tab-item} ... GitHub Desktop
1. Make some changes to a file in for example VS Code and save them.
**Make some changes to a file in for example VS Code and save them**
2. Once all the changes are made, it can be useful to check the changes locally on your device.<br />
By doing that you can preview how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy.
Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
You will firstly need to activate the right environment. Type the following command:
```
conda activate jupyter-book-env
```{include} user45_check_changes.md
```
(or the environment in which you have installed the `teachbooks` package!)
Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command:
```
teachbooks build <path-to-book>
```{include} stage_commit_push_github_desktop.md
```
Alternatively:
```
jupyter-book build <path-to-book>
```
Note: use `--all` for the `teachbook` or `jupyter-book` command whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book.
Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following:
```{figure} figures/buildbook.PNG
Output
```
Paste the last line into your browser to see the updated changes.
```{Note}
Sometimes there are problems building the book. It could be that the building requires extensions that are not present in your environment. To prevent issues, make sure to update your environment by routinely updating your packages. You can do this by executing the following line in your environment in the command line.
`pip install -r requirements.txt --upgrade`
```
If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server]
3. If you are satisfied with your changes, you can select the files ready to be added to Git-timeline (staging)
The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*.
```{figure} figures/Stage_GitHubDekstop.PNG
width: 50%
Staging
```
4. Add changes to Git-timeline locally (committing). In the field that says `Summary (Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, click the blue button `Commit to repository`.
5. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repository. After committing, click on `Push Origin` in the top bar.
```{figure} figures/Push_GitHubDekstop.PNG
width: 100%
Push origin
```
````
`````
``````
@ -513,7 +337,9 @@ Push origin
`````{tab-set}
````{tab-item} ... Git in VS Code
1. If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repository with your local repository on your machine. On the left side-bar click on the icon that looks like a branch.
**Regularly obtain updates from colleagues from GitLab/GitHub (pulling)**
If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repository with your local repository on your machine. On the left side-bar click on the icon that looks like a branch.
<figure align="center">
<img src="figures/VSCode_Pull.PNG" alt="Example Image" width="400">
@ -521,7 +347,9 @@ Push origin
By clicking on the 🔄 button, you will pull your colleages' changes.
2. When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repository, Git in VS Code will recognize conflicts and help you to solve potential incompatible changes (merging conflicts). Open the files that are marked as conflicitng.
**Solve potential incompatible changes (merging conflicts)**
When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repository, Git in VS Code will recognize conflicts and help you to solve potential incompatible changes (merging conflicts). Open the files that are marked as conflicitng.
<figure align="center">
<img src="figures/Conflicts2.PNG" alt="Example Image" width="600">
@ -535,85 +363,28 @@ The figure above shows the conflicts. If you look closely you can see that the l
Choose one of the options to resolve the merge conflict. You now have updated your work with work from your colleagues and resolved potential conlicts. You are now ready to continue working on the content.
3. Make some further changes to a file in for example VS Code and save them.
**Make some further changes to a file in for example VS Code and save them**
4. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy!
Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
You will firstly need to activate the right environment. Type the following command:
`conda activate jupyter-book-env`
(or the environment in which you have installed the TeachBooks package)
Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command:
```
teachbooks build <path-to-book>
```{include} user45_check_changes.md
```
Alternatively:
```
jupyter-book build <path-to-book>
```{include} stage_commit_push_vscode.md
```
Note: use `--all` for the `teachbook` or `jupyter-book` command whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book.
Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following:
```{figure} figures/buildbook.PNG
Output
```
Paste the last line into your browser to see the updated changes.
```{Note}
Sometimes there are problems building the book. It could be that the building requires extensions that are not present in your environment. To prevent issues, make sure to update your environment by routinely updating your packages. You can do this by executing the following line in your environment in the command line.
`pip install -r requirements.txt --upgrade`
```
If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server]
5. Select the files ready to be added to Git-timeline (staging)
For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu:
```{figure} ../images/git-new-file.png
The new file appears in the Source Control menu.
```
Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file.
6. Adding changes to the Git-timeline (committing)
Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this:
```{figure} ../images/git-file-added.png
The new file has been staged, and we've written a Commit Message.
```
Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu.
7. In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab.
```{figure} ../images/git-push.png
After committing, click the 🔄 button to push our changes to the remote repository.
````
````{tab-item} ... GitHub Desktop
1. If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repository with your local repository on your machine. Click on `Fetch` in the top bar. Then on the same place, click on 'Pull'.
**Regularly obtain updates from colleagues from GitLab/GitHub (pulling)**
If you collaborate with colleagues on your branch, you can get the updates from your colleagues as well by pulling from GitLab/GitHub. This synchronizes the remote repository with your local repository on your machine. Click on `Fetch` in the top bar. Then on the same place, click on 'Pull'.
<figure align="center">
<img src="figures/Fetch.PNG" alt="Example Image" width="650">
</figure>
2. When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repository, GitHub Desktop will recognize conflicts and help you to solve potential incompatible changes (merging conflicts).
**Solve potential incompatible changes (merging conflicts)**
When multiple people work on one chapter, it is possible that conflicts will arise if you and your colleagues have made incompatible changes in the same branch. In that case, when pulling from the remote repository, GitHub Desktop will recognize conflicts and help you to solve potential incompatible changes (merging conflicts).
<figure align="center">
<img src="figures/Merge_Conflict_GitHubDesktop2.PNG" alt="Example Image" width="400">
@ -623,63 +394,14 @@ In this case there are two conflicted files. GitHub Desktop is suggesting to res
Choose one of the options to resolve the merge conflict. You now have updated your work with work from your colleagues and resolved potential conlicts. You are now ready to continue working on the content.
3. Make some further changes to a file in for example VS Code and save them.
**Make some further changes to a file in for example VS Code and save them**
4. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy!
Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
You will firstly need to activate the right environment. Type the following command:
`conda activate jupyter-book-env`
(or the environment in which you have installed the TeachBooks package)
Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command:
```
teachbooks build <path-to-book>
```{include} user45_check_changes.md
```
Alternatively:
```
jupyter-book build <path-to-book>
```{include} stage_commit_push_github_desktop.md
```
Note: use `--all` for the `teachbook` or `jupyter-book` command whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book.
Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following:
```{figure} figures/buildbook.PNG
Output
```
Paste the last line into your browser to see the updated changes.
```{Note}
Sometimes there are problems building the book. It could be that the building requires extensions that are not present in your environment. To prevent issues, make sure to update your environment by routinely updating your packages. You can do this by executing the following line in your environment in the command line.
`pip install -r requirements.txt --upgrade`
```
If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server]
5. The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*.
<figure align="center">
<img src="figures/Stage_GitHubDekstop.PNG" alt="Example Image" width="400">
</figure>
6. Add changes to Git-timeline locally (committing). In the field that says `Summary(Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, click the blue button `Commit to repository`.
7. Now we need to add changes to GitHub/GitLab. This is called pushing to the local repository. After committing, click on `Push origin` in the top bar.
<figure align="center">
<img src="figures/Push_GitHubDesktop.PNG" alt="Example Image" width="650">
</figure>
````
````{tab-item} ... using 'VS Code in your browser'

BIN
book/workflows/figures/Push_GitHubDekstop.PNG Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 11 KiB

16
book/workflows/github_dev.md
View file

@ -4,20 +4,20 @@
4. In case you want to add a new file, navigate to the explorer file (the page icon) and click on the `New File` icon. This will create a new file in the folder that you are in. Give it the right extension!
```{figure} figures/Online_VS0.PNG
name: New File
---
width: 50%
align: center
---
New File
```
5. In case you want to make changes to an existing file, navigate to a file and make some changes.
```{figure} figures/Online_VS1.PNG
name: VS Code in Browser
---
width: 70%
align: center
---
VS Code in Browser
```
In the bottom left you can see the branch you are working in.
@ -26,19 +26,19 @@ In the bottom left you can see the branch you are working in.
7. Now let's see the result. Go back to your GitHub repo. In the top bar, go to actions.
```{figure} figures/Online_VS2.PNG
name: GitHub Actions
---
width: 70%
align: center
---
GitHub Actions
```
You will see the latest commit you just did (in this case text). After the pipeline has run, the yellow icon will turn green. Click on the commit and scroll until you see the title Deployed Branches.
```{figure} figures/Online_VS3.PNG
name: Deployed Branches
---
width: 60%
align: center
---
Deployed Branches
```
Click on the link and admire your changes:)

25
book/workflows/stage_commit_push_github_desktop.md Normal file
View file

@ -0,0 +1,25 @@
**Selecting changes to be added to the Git-timeline (staging)**
The staging GitHub Desktop assumes you want to stage all files. These files will show up on the left side bar when you open GitHub Desktop. You can unselect some of them (unstaging them) by clicking on the *check*.
```{figure} figures/Stage_GitHubDekstop.PNG
---
width: 50%
---
Staging
```
**Adding changes to the Git-timeline (committing)**
In the field that says `Summary(Required)`, write a short description of the changes you have made. This message is what is called the *Commit Message*. After you've done this, click the blue button `Commit to repository`.
**Adding changes to GitLab/GitHub (pushing)**
Now we need to add changes to GitHub/GitLab. This is called pushing to the remote repository. After committing, click on `Push origin` in the top bar.
```{figure} figures/Push_GitHubDekstop.PNG
---
width: 80%
---
Push origin
```

38
book/workflows/stage_commit_push_vscode.md Normal file
View file

@ -0,0 +1,38 @@
**Selecting changes to be added to the Git-timeline (staging)**
For demonstration purposes, we have created a new Markdown file called `new-chapter.md`, which we want to add to the book. Since this is a new file, Git has no knowledge about its existence yet. I.e., the file is *untracked*. To add new files to our repository, we need to *stage* and *commit* them. To do this, open the Source Control menu in the left side bar. Our new file should appear in this menu:
```{figure} ../images/git-new-file.png
---
width: 100%
---
The new file appears in the Source Control menu.
```
Notice that there is a green letter U placed besides the file, meaning that our file is untracked. To add a file to the *staging area*, click on the + that appears when you hover over the file.
**Adding changes to the Git-timeline (committing)**
Next, in the field that says "Message", write a short description of the changes you have made. This message is what is called the *Commit Message*. After we've done this, the menu should now look something like this:
```{figure} ../images/git-file-added.png
---
width: 100%
---
The new file has been staged, and we've written a Commit Message.
```
Now, we are ready to add the changes to the repository. This is done by *committing* the staged changes. To do this, simply press the big, blue "Commit" button in the Source Control menu.
**Adding changes to GitLab/GitHub (pushing)**
In the bottom left corner, next to the branch name, click the "Synchronize Changes" button (the one that looks like this: 🔄, highlighted in the image below) to push the changes to GitLab/GitHub.
```{figure} ../images/git-push.png
---
width: 100%
---
After committing, click the 🔄 button to push our changes to the remote repository.
```

33
book/workflows/user45_check_changes.md
View file

@ -1,37 +1,34 @@
Once all the changes are made, it can be useful to check the changes locally on your device.
**Checking changes locally**
Once all the changes are made, it can be useful to check the changes locally on your device.
By doing that you can preview how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy.
By doing that you can preview how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy.
Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
You will firstly need to activate the right environment. Type the following command:
Navigate to the terminal in VS code, located at the bottom of the window or by clicking on `Terminal` in the top bar.
You will firstly need to activate the right environment. Type the following command:
```
conda activate jupyter-book-env
conda activate my_new_book_env
```
(or the environment in which you have installed the `teachbooks` package!)
Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command:
(or the environment in which you have installed the `teachbooks` package!)
Then we can build the book locally. Make sure you are in the right repository in VS code and type the following command:
```
teachbooks build <path-to-book>
```
Alternatively:
Note: use `--all` for the jupyter-book whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book.
```
jupyter-book build <path-to-book> --all
```
Note: use `--all` for the jupyter-book whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book.
Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following:
Where book is the name of the folder containing all the files that make up your book. After `teachbooks` is done running you will get the following:
```{figure} ../figures/buildbook.PNG
Output
```
Paste the last line into your browser to see the updated changes.
Paste the last line into your browser to see the updated changes.
```{Note}
@ -41,4 +38,4 @@ Sometimes there are problems building the book. It could be that the building re
```
If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server]
If your book includes interactive element a webserver is required to host the book. If you want to do this locally, you can make use of (the teachbooks package to start up a local webserver)[setup-local-server]

3
requirements.txt
View file

@ -10,3 +10,6 @@ sphinx-image-inverter
--extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple
sphinx-thebe ~= 0.9.9
docutils==0.17.1
sphinx-exercise