mirror of
https://github.com/TeachBooks/manual.git
synced 2026-11-12 22:35:51 +00:00
Merge branch 'release' into credits_references_overview_page
This commit is contained in:
Robert Lanzafame
GitHub
commit
e2489b4b5e
36 changed files with 1051 additions and 400 deletions
|
|
@ -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'
|
||||
|
||||
|
|
@ -27,6 +25,10 @@ sphinx:
|
|||
use_thebe_lite: true
|
||||
exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb","**/*.gif","**/*.txt","**/*.json",]
|
||||
html_theme_options:
|
||||
logo:
|
||||
text: Manual
|
||||
image_light: TB_logo.png
|
||||
image_dark: TB_logo_dark.png
|
||||
repository_url: "https://github.com/TeachBooks/manual/"
|
||||
path_to_docs: "book"
|
||||
repository_branch: "release"
|
||||
|
|
@ -37,6 +39,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
|
||||
- references.bib
|
||||
|
|
|
|||
17
book/_ext/apastyle.py
Normal file
17
book/_ext/apastyle.py
Normal file
|
|
@ -0,0 +1,17 @@
|
|||
|
||||
# from pybtex.style.formatting.unsrt import Style
|
||||
from pybtexapastyle.formatting.apa import APAStyle
|
||||
from pybtexapastyle.labels.apa import LabelStyle as APALabelStyle
|
||||
from pybtex.plugin import register_plugin
|
||||
# from pybtex.style.template import names, sentence
|
||||
|
||||
class MyAPALabelStyle(APALabelStyle):
|
||||
def format_label(self, entry):
|
||||
return APALabelStyle.format_label(self, entry)
|
||||
|
||||
class MyAPAStyle(APAStyle):
|
||||
default_label_style = 'myapa'
|
||||
|
||||
def setup(app):
|
||||
register_plugin('pybtex.style.labels', 'myapa', MyAPALabelStyle)
|
||||
register_plugin('pybtex.style.formatting', 'myapastyle', MyAPAStyle)
|
||||
27
book/_ext/bracket_citation_style.py
Normal file
27
book/_ext/bracket_citation_style.py
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
from dataclasses import dataclass, field
|
||||
import sphinxcontrib.bibtex.plugin
|
||||
|
||||
from sphinxcontrib.bibtex.style.referencing import BracketStyle
|
||||
from sphinxcontrib.bibtex.style.referencing.author_year import AuthorYearReferenceStyle
|
||||
|
||||
|
||||
def bracket_style() -> BracketStyle:
|
||||
return BracketStyle(
|
||||
left='(',
|
||||
right=')',
|
||||
)
|
||||
|
||||
|
||||
@dataclass
|
||||
class MyReferenceStyle(AuthorYearReferenceStyle):
|
||||
bracket_parenthetical: BracketStyle = field(default_factory=bracket_style)
|
||||
bracket_textual: BracketStyle = field(default_factory=bracket_style)
|
||||
bracket_author: BracketStyle = field(default_factory=bracket_style)
|
||||
bracket_label: BracketStyle = field(default_factory=bracket_style)
|
||||
bracket_year: BracketStyle = field(default_factory=bracket_style)
|
||||
|
||||
|
||||
def setup(app):
|
||||
sphinxcontrib.bibtex.plugin.register_plugin(
|
||||
'sphinxcontrib.bibtex.style.referencing',
|
||||
'author_year_round', MyReferenceStyle)
|
||||
21
book/_ext/pybtexapastyle/LICENSE
Normal file
21
book/_ext/pybtexapastyle/LICENSE
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
MIT License
|
||||
|
||||
Copyright (c) 2018 Naeka
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
0
book/_ext/pybtexapastyle/formatting/__init__.py
Normal file
0
book/_ext/pybtexapastyle/formatting/__init__.py
Normal file
486
book/_ext/pybtexapastyle/formatting/apa.py
Normal file
486
book/_ext/pybtexapastyle/formatting/apa.py
Normal file
|
|
@ -0,0 +1,486 @@
|
|||
# -*- coding:Utf-8 -*-
|
||||
from __future__ import unicode_literals
|
||||
|
||||
import re
|
||||
import six
|
||||
|
||||
from pybtex.plugin import find_plugin
|
||||
from pybtex.style.formatting import BaseStyle, toplevel
|
||||
from pybtex.style.template import (
|
||||
field, first_of, href, join, optional, optional_field, sentence, tag,
|
||||
together, words, node, FieldIsMissing
|
||||
)
|
||||
|
||||
from pybtex.richtext import Text, Symbol
|
||||
|
||||
|
||||
firstlast = find_plugin('pybtex.style.names', 'lastfirst')()
|
||||
|
||||
if six.PY2:
|
||||
def format_pages(text):
|
||||
dash_re = re.compile(r'-+')
|
||||
pages = Text(Symbol('ndash')).join(
|
||||
re.split(dash_re, six.text_type(text)))
|
||||
if re.search('[-‒–—―]', six.text_type(text)):
|
||||
return Text("pp.", Symbol('nbsp'), pages)
|
||||
return Text("p.", Symbol('nbsp'), pages)
|
||||
else:
|
||||
def format_pages(text):
|
||||
dash_re = re.compile(r'-+')
|
||||
pages = Text(Symbol('ndash')).join(text.split(dash_re))
|
||||
if re.search('[-‒–—―]', str(text)):
|
||||
return Text("pp.", Symbol('nbsp'), pages)
|
||||
return Text("p.", Symbol('nbsp'), pages)
|
||||
|
||||
|
||||
pages = field('pages', apply_func=format_pages)
|
||||
date = words[field('year'), optional[", ", field('month')]]
|
||||
|
||||
|
||||
@node
|
||||
def apa_names(children, context, role, **kwargs):
|
||||
"""
|
||||
Returns formatted names as an APA compliant reference list citation.
|
||||
"""
|
||||
assert not children
|
||||
|
||||
try:
|
||||
persons = context['entry'].persons[role]
|
||||
except KeyError:
|
||||
raise FieldIsMissing(role, context['entry'])
|
||||
|
||||
style = context['style']
|
||||
|
||||
if len(persons) > 7:
|
||||
persons = persons[:6] + persons[-1:]
|
||||
formatted_names = [style.format_name(
|
||||
person, style.abbreviate_names) for person in persons]
|
||||
return join(sep=', ', last_sep=', … ')[
|
||||
formatted_names].format_data(context)
|
||||
else:
|
||||
formatted_names = [style.format_name(
|
||||
person, style.abbreviate_names) for person in persons]
|
||||
return join(sep=', ', sep2=', & ', last_sep=', & ')[
|
||||
formatted_names].format_data(context)
|
||||
|
||||
|
||||
@node
|
||||
def editor_names(children, context, with_suffix=True, **kwargs):
|
||||
"""
|
||||
Returns formatted editor names for inbook.
|
||||
"""
|
||||
assert not children
|
||||
|
||||
try:
|
||||
editors = context['entry'].persons['editor']
|
||||
except KeyError:
|
||||
raise FieldIsMissing('editor', context['entry'])
|
||||
|
||||
formatted_names = [
|
||||
firstlast.format(editor, True) for editor in editors]
|
||||
|
||||
if with_suffix:
|
||||
return words[
|
||||
join(sep=', ', sep2=', & ', last_sep=', & ')[formatted_names],
|
||||
"(Eds.)" if len(editors) > 1 else "(Ed.)"
|
||||
].format_data(context)
|
||||
|
||||
return join(sep=', ', sep2=', & ', last_sep=', & ')[
|
||||
formatted_names
|
||||
].format_data(context)
|
||||
|
||||
|
||||
class APAStyle(BaseStyle):
|
||||
name = 'apa'
|
||||
default_name_style = 'lastfirst'
|
||||
default_sorting_style = 'author_year_title'
|
||||
default_label_style = 'apa'
|
||||
|
||||
def __init__(self, *args, **kwargs):
|
||||
super(APAStyle, self).__init__(*args, **kwargs)
|
||||
self.abbreviate_names = True
|
||||
|
||||
def format_names(self, role, as_sentence=True):
|
||||
formatted_names = apa_names(role)
|
||||
if as_sentence:
|
||||
return sentence(capfirst=False)[formatted_names]
|
||||
else:
|
||||
return formatted_names
|
||||
|
||||
def format_author_or_editor_and_date(self, e):
|
||||
if 'author' in e.persons and 'editor' in e.persons:
|
||||
return sentence(sep=' ')[
|
||||
self.format_names('author'), join["(", date, ")."],
|
||||
self.format_editor(e, as_sentence=False)]
|
||||
elif 'author' in e.persons:
|
||||
return sentence(sep=' ')[
|
||||
self.format_names('author'), join["(", date, ")"]]
|
||||
else:
|
||||
return sentence(sep=' ')[
|
||||
self.format_editor(e, as_sentence=False),
|
||||
join["(", date, ")"]]
|
||||
|
||||
def format_editor(self, e, as_sentence=True):
|
||||
editors = self.format_names('editor', as_sentence=False)
|
||||
if 'editor' not in e.persons:
|
||||
# when parsing the template, a FieldIsMissing exception
|
||||
# will be thrown anyway; no need to do anything now,
|
||||
# just return the template that will throw the exception
|
||||
return editors
|
||||
if len(e.persons['editor']) > 1:
|
||||
word = '(Eds.)'
|
||||
else:
|
||||
word = '(Ed.)'
|
||||
result = join(sep=' ')[editors, word]
|
||||
if as_sentence:
|
||||
return sentence[result]
|
||||
else:
|
||||
return result
|
||||
|
||||
def format_volume(self, e, for_article=False):
|
||||
prefix = "Vol."
|
||||
if for_article:
|
||||
return join[
|
||||
tag('em')[field('volume')],
|
||||
optional['(', field('number'), ')'],
|
||||
]
|
||||
else:
|
||||
return optional[together[prefix, field('volume')]]
|
||||
|
||||
def format_title(self, e, which_field, as_sentence=True):
|
||||
formatted_title = field(
|
||||
which_field, apply_func=lambda text: text.capitalize()
|
||||
)
|
||||
if as_sentence:
|
||||
return sentence[formatted_title]
|
||||
else:
|
||||
return formatted_title
|
||||
|
||||
def format_btitle(self, e, which_field, as_sentence=True):
|
||||
formatted_title = tag('em')[field(which_field)]
|
||||
if as_sentence:
|
||||
return sentence[formatted_title]
|
||||
else:
|
||||
return formatted_title
|
||||
|
||||
def format_web_refs(self, e):
|
||||
# Based on urlbst output.web.refs
|
||||
return sentence(add_period=False)[
|
||||
optional[self.format_url(e)],
|
||||
optional[self.format_eprint(e)],
|
||||
optional[self.format_pubmed(e)],
|
||||
optional[self.format_doi(e)],
|
||||
]
|
||||
|
||||
def format_url(self, e):
|
||||
# Based on urlbst format.url
|
||||
return words[
|
||||
'URL:',
|
||||
href[
|
||||
field('url', raw=True),
|
||||
field('url', raw=True)
|
||||
]
|
||||
]
|
||||
|
||||
def format_pubmed(self, e):
|
||||
# Based on urlbst format.pubmed
|
||||
return href[
|
||||
join[
|
||||
'https://www.ncbi.nlm.nih.gov/pubmed/',
|
||||
field('pubmed', raw=True)
|
||||
],
|
||||
join[
|
||||
'PMID:',
|
||||
field('pubmed', raw=True)
|
||||
]
|
||||
]
|
||||
|
||||
def format_doi(self, e):
|
||||
# Based on urlbst format.doi
|
||||
return href[
|
||||
join[
|
||||
'https://doi.org/',
|
||||
field('doi', raw=True)
|
||||
],
|
||||
join[
|
||||
'doi:',
|
||||
field('doi', raw=True)
|
||||
]
|
||||
]
|
||||
|
||||
def format_eprint(self, e):
|
||||
# Based on urlbst format.eprint
|
||||
return href[
|
||||
join[
|
||||
'https://arxiv.org/abs/',
|
||||
field('eprint', raw=True)
|
||||
],
|
||||
join[
|
||||
'arXiv:',
|
||||
field('eprint', raw=True)
|
||||
]
|
||||
]
|
||||
|
||||
def get_article_template(self, e):
|
||||
# Required fields: author, title, journal, year
|
||||
# Optional fields: volume, number, pages, month, note, key
|
||||
volume_and_pages = first_of[
|
||||
# Volume and pages, with optional issue number
|
||||
optional[
|
||||
join[
|
||||
self.format_volume(e, for_article=True),
|
||||
optional[', ', field('pages')]
|
||||
],
|
||||
],
|
||||
# Pages only
|
||||
pages,
|
||||
]
|
||||
template = toplevel[
|
||||
self.format_names('author'),
|
||||
sentence[
|
||||
join["(", date, ")"]
|
||||
],
|
||||
self.format_title(e, 'title'),
|
||||
sentence[
|
||||
tag('em')[field('journal')],
|
||||
optional[volume_and_pages],
|
||||
],
|
||||
sentence[optional_field('note')],
|
||||
self.format_web_refs(e),
|
||||
]
|
||||
return template
|
||||
|
||||
def get_book_template(self, e):
|
||||
# Required fields: author/editor, title, publisher, year
|
||||
# Optional fields: volume, series, address, edition, month, note, key,
|
||||
# isbn
|
||||
return toplevel[
|
||||
self.format_author_or_editor_and_date(e),
|
||||
sentence(sep=' ')[
|
||||
self.format_btitle(e, 'title'),
|
||||
optional[
|
||||
sentence[
|
||||
optional[field('edition'), ' ed.'],
|
||||
self.format_volume(e),
|
||||
]
|
||||
]
|
||||
],
|
||||
sentence(sep=': ')[
|
||||
optional_field('address'),
|
||||
field('publisher'),
|
||||
],
|
||||
sentence[optional_field('note')],
|
||||
]
|
||||
|
||||
def get_booklet_template(self, e):
|
||||
# Required fields: title
|
||||
# Optional fields: author, howpublished, address, month, year, note,
|
||||
# key
|
||||
return toplevel[
|
||||
sentence(sep=' ')[
|
||||
first_of[
|
||||
optional[self.format_names(
|
||||
'author', as_sentence=False)],
|
||||
"None to claim their bones"
|
||||
],
|
||||
join["(", first_of[optional[date], "n.d."], ")"]
|
||||
],
|
||||
self.format_title(e, 'title'),
|
||||
sentence[optional_field('address')],
|
||||
sentence[optional_field('note')],
|
||||
]
|
||||
|
||||
def get_inbook_template(self, e):
|
||||
# Required fields: author/editor, title, chapter/pages, publisher, year
|
||||
# Optional fields: volume, series, address, edition, month, note, key
|
||||
return toplevel[
|
||||
sentence(sep=' ')[
|
||||
self.format_names('author'),
|
||||
join["(", date, ")"]
|
||||
],
|
||||
self.format_title(e, 'title'),
|
||||
sentence(sep=' ')[
|
||||
optional[
|
||||
"In ",
|
||||
editor_names(),
|
||||
","
|
||||
],
|
||||
self.format_btitle(e, 'booktitle', as_sentence=False),
|
||||
optional[
|
||||
join[
|
||||
"(",
|
||||
sentence(add_period=False)[
|
||||
optional[field('edition'), ' ed.'],
|
||||
self.format_volume(e),
|
||||
pages,
|
||||
],
|
||||
")"
|
||||
]
|
||||
]
|
||||
],
|
||||
sentence(sep=': ')[
|
||||
optional_field('address'),
|
||||
field('publisher'),
|
||||
],
|
||||
sentence[optional_field('note')],
|
||||
]
|
||||
|
||||
def get_incollection_template(self, e):
|
||||
# Required fields: author, title, booktitle, year
|
||||
# Optional fields: editor, pages, organization, publisher, address,
|
||||
# month, note, key
|
||||
return toplevel[
|
||||
self.format_author_or_editor_and_date(e),
|
||||
self.format_title(e, 'title'),
|
||||
sentence(sep=' ')[
|
||||
self.format_btitle(e, 'booktitle', as_sentence=False),
|
||||
optional["(", pages, ")"]
|
||||
],
|
||||
sentence(sep=': ')[
|
||||
optional_field('address'),
|
||||
optional_field('publisher'),
|
||||
],
|
||||
sentence[optional_field('note')],
|
||||
]
|
||||
|
||||
def get_inproceedings_template(self, e):
|
||||
# Required fields: author, title, booktitle, year
|
||||
# Optional fields: editor, pages, organization, publisher, address,
|
||||
# month, note, key
|
||||
return toplevel[
|
||||
self.format_author_or_editor_and_date(e),
|
||||
self.format_title(e, 'title'),
|
||||
sentence(sep=' ')[
|
||||
self.format_btitle(e, 'booktitle', as_sentence=False),
|
||||
optional["(", pages, ")"]
|
||||
],
|
||||
sentence(sep=': ')[
|
||||
optional_field('address'),
|
||||
optional_field('publisher'),
|
||||
],
|
||||
sentence[optional_field('note')],
|
||||
self.format_web_refs(e)
|
||||
]
|
||||
|
||||
def get_manual_template(self, e):
|
||||
# Required fields: title
|
||||
# Optional fields: author, organization, address, edition, month, year,
|
||||
# note, key
|
||||
return toplevel[
|
||||
sentence(sep=' ')[
|
||||
first_of[
|
||||
optional[self.format_names('author', as_sentence=False)],
|
||||
optional_field('organization'),
|
||||
"None to claim their bones"
|
||||
],
|
||||
join["(", first_of[optional[date], "n.d."], ")"]
|
||||
],
|
||||
self.format_btitle(e, 'title'),
|
||||
sentence[optional_field('address')],
|
||||
sentence[optional_field('note')],
|
||||
self.format_web_refs(e)
|
||||
]
|
||||
|
||||
def get_mastersthesis_template(self, e):
|
||||
# Required fields: author, title, school, year
|
||||
# Optional fields: address, month, note, key
|
||||
return toplevel[
|
||||
sentence(sep=' ')[
|
||||
self.format_names('author'),
|
||||
join["(", date, ")"]
|
||||
],
|
||||
sentence(sep=' ')[
|
||||
self.format_btitle(e, 'title', as_sentence=False),
|
||||
"(Master's thesis)"
|
||||
],
|
||||
sentence[
|
||||
field('school'),
|
||||
optional_field('address'),
|
||||
],
|
||||
sentence[optional_field('note')],
|
||||
]
|
||||
|
||||
def get_misc_template(self, e):
|
||||
# Required fields: aucun
|
||||
# Optional fields: author, title, howpublished, month, year, note, key,
|
||||
# type
|
||||
template = toplevel[
|
||||
sentence(sep=' ')[
|
||||
first_of[
|
||||
optional[self.format_names('author', as_sentence=False)],
|
||||
optional_field('publisher'),
|
||||
"None to claim their bones"
|
||||
],
|
||||
join["(", first_of[optional[date], "n.d."], ")"]
|
||||
],
|
||||
optional[self.format_title(e, 'title')],
|
||||
sentence[optional_field('note')],
|
||||
self.format_web_refs(e)
|
||||
]
|
||||
return template
|
||||
|
||||
def get_phdthesis_template(self, e):
|
||||
# Required fields: author, title, school, year
|
||||
# Optional fields: address, month, note, key
|
||||
return toplevel[
|
||||
sentence(sep=' ')[
|
||||
self.format_names('author'),
|
||||
join["(", date, ")"]
|
||||
],
|
||||
sentence(sep=' ')[
|
||||
self.format_btitle(e, 'title', as_sentence=False),
|
||||
"(Doctoral dissertation)"
|
||||
],
|
||||
sentence[
|
||||
field('school'),
|
||||
optional_field('address'),
|
||||
],
|
||||
sentence[optional_field('note')],
|
||||
]
|
||||
|
||||
def get_proceedings_template(self, e):
|
||||
# Required fields: title, year
|
||||
# Optional fields: editor, publisher, organization, address, month,
|
||||
# note, key
|
||||
return toplevel[
|
||||
sentence(sep=' ')[
|
||||
first_of[
|
||||
optional[self.format_editor(e, as_sentence=False)],
|
||||
optional_field('organization'),
|
||||
"None to claim their bones"
|
||||
],
|
||||
join["(", first_of[optional[date], "n.d."], ")"]
|
||||
],
|
||||
self.format_btitle(e, 'title'),
|
||||
sentence(sep=': ')[
|
||||
optional_field('address'),
|
||||
optional_field('publisher'),
|
||||
],
|
||||
sentence[optional_field('note')],
|
||||
]
|
||||
|
||||
def get_techreport_template(self, e):
|
||||
# Required fields: author, title, institution, year
|
||||
# Optional fields: type, number, address, month, note, key
|
||||
return toplevel[
|
||||
sentence(sep=' ')[
|
||||
self.format_names('author', as_sentence=False),
|
||||
join["(", date, ")"]
|
||||
],
|
||||
self.format_btitle(e, 'title'),
|
||||
sentence[field('institution')],
|
||||
sentence[optional_field('note')],
|
||||
]
|
||||
|
||||
def get_unpublished_template(self, e):
|
||||
# Required fields: author, title, note
|
||||
# Optional fields: month, year, key
|
||||
template = toplevel[
|
||||
sentence(sep=' ')[
|
||||
self.format_names('author', as_sentence=False),
|
||||
join["(", first_of[optional[date], "n.d."], ")"]
|
||||
],
|
||||
self.format_btitle(e, 'title'),
|
||||
sentence[field('note')],
|
||||
]
|
||||
return template
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
from __future__ import unicode_literals
|
||||
|
||||
from pybtex.style import FormattedEntry, FormattedBibliography
|
||||
from pybtex.style.template import node, join
|
||||
from pybtex.richtext import Symbol
|
||||
from pybtex.plugin import Plugin, find_plugin
|
||||
|
||||
|
||||
@node
|
||||
def toplevel(children, data):
|
||||
return join(sep=Symbol('newblock')) [children].format_data(data)
|
||||
|
||||
|
||||
class BaseStyle(Plugin):
|
||||
"""
|
||||
The base class for pythonic formatting styles.
|
||||
"""
|
||||
|
||||
default_name_style = None
|
||||
default_label_style = None
|
||||
default_sorting_style = None
|
||||
|
||||
def __init__(self, label_style=None, name_style=None, sorting_style=None, abbreviate_names=False, min_crossrefs=2, **kwargs):
|
||||
self.name_style = find_plugin('pybtex.style.names', name_style or self.default_name_style)()
|
||||
self.label_style = find_plugin('pybtex.style.labels', label_style or self.default_label_style)()
|
||||
self.sorting_style = find_plugin('pybtex.style.sorting', sorting_style or self.default_sorting_style)()
|
||||
self.format_name = self.name_style.format
|
||||
self.format_labels = self.label_style.format_labels
|
||||
self.sort = self.sorting_style.sort
|
||||
self.abbreviate_names = abbreviate_names
|
||||
self.min_crossrefs = min_crossrefs
|
||||
|
||||
def format_entries(self, entries, bib_data=None):
|
||||
sorted_entries = self.sort(entries)
|
||||
labels = self.format_labels(sorted_entries)
|
||||
for label, entry in zip(labels, sorted_entries):
|
||||
yield self.format_entry(label, entry, bib_data=bib_data)
|
||||
|
||||
def format_entry(self, label, entry, bib_data=None):
|
||||
context = {
|
||||
'entry': entry,
|
||||
'style': self,
|
||||
'bib_data': bib_data,
|
||||
}
|
||||
try:
|
||||
get_template = getattr(self, 'get_{}_template'.format(entry.type))
|
||||
except AttributeError:
|
||||
format_method = getattr(self, "format_" + entry.type)
|
||||
text = format_method(context)
|
||||
else:
|
||||
text = get_template(entry).format_data(context)
|
||||
return FormattedEntry(entry.key, text, label)
|
||||
|
||||
def format_bibliography(self, bib_data, citations=None):
|
||||
"""
|
||||
Format bibliography entries with the given keys and return a
|
||||
``FormattedBibliography`` object.
|
||||
|
||||
:param bib_data: A :py:class:`pybtex.database.BibliographyData` object.
|
||||
:param citations: A list of citation keys.
|
||||
"""
|
||||
|
||||
if citations is None:
|
||||
citations = list(bib_data.entries.keys())
|
||||
citations = bib_data.add_extra_citations(citations, self.min_crossrefs)
|
||||
entries = [bib_data.entries[key] for key in citations]
|
||||
formatted_entries = self.format_entries(entries)
|
||||
formatted_bibliography = FormattedBibliography(formatted_entries, style=self, preamble=bib_data.preamble)
|
||||
return formatted_bibliography
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
from __future__ import unicode_literals
|
||||
|
||||
|
||||
from pybtex.plugin import Plugin
|
||||
|
||||
|
||||
class BaseSortingStyle(Plugin):
|
||||
def sorting_key(self, entry):
|
||||
raise NotImplementedError
|
||||
|
||||
def sort(self, entries):
|
||||
return sorted(entries, key=self.sorting_key)
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
from __future__ import unicode_literals
|
||||
|
||||
from pybtex.style.sorting import BaseSortingStyle
|
||||
|
||||
class SortingStyle(BaseSortingStyle):
|
||||
|
||||
def sorting_key(self, entry):
|
||||
if entry.type in ('book', 'inbook'):
|
||||
author_key = self.author_editor_key(entry)
|
||||
elif 'author' in entry.persons:
|
||||
author_key = self.persons_key(entry.persons['author'])
|
||||
else:
|
||||
author_key = ''
|
||||
return (author_key, entry.fields.get('year', ''), entry.fields.get('title', ''))
|
||||
|
||||
def persons_key(self, persons):
|
||||
return ' '.join(self.person_key(person) for person in persons)
|
||||
|
||||
def person_key(self, person):
|
||||
if person.prelast_names[0] != '{' and person.last_names[0] != '{' and person.first_names[0] != '{':
|
||||
return ' '.join((
|
||||
' '.join(person.prelast_names + person.last_names),
|
||||
' '.join(person.first_names + person.middle_names),
|
||||
' '.join(person.lineage_names),
|
||||
)).lower()
|
||||
else:
|
||||
return ' '.join((
|
||||
' '.join(person.first_names + person.middle_names),
|
||||
' '.join(person.prelast_names + person.last_names),
|
||||
' '.join(person.lineage_names),
|
||||
)).lower()
|
||||
|
||||
def author_editor_key(self, entry):
|
||||
if entry.persons.get('author'):
|
||||
return self.persons_key(entry.persons['author'])
|
||||
elif entry.persons.get('editor'):
|
||||
return self.persons_key(entry.persons['editor'])
|
||||
else:
|
||||
return ''
|
||||
0
book/_ext/pybtexapastyle/labels/__init__.py
Normal file
0
book/_ext/pybtexapastyle/labels/__init__.py
Normal file
67
book/_ext/pybtexapastyle/labels/apa.py
Normal file
67
book/_ext/pybtexapastyle/labels/apa.py
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
# -*- coding:Utf-8 -*-
|
||||
from __future__ import unicode_literals
|
||||
|
||||
from collections import Counter
|
||||
import re
|
||||
import unicodedata
|
||||
|
||||
from pybtex.style.labels import BaseLabelStyle
|
||||
|
||||
|
||||
_nonalnum_pattern = re.compile('[^A-Za-z0-9 \-]+', re.UNICODE)
|
||||
|
||||
|
||||
def _strip_accents(s):
|
||||
return "".join(
|
||||
(c for c in unicodedata.normalize('NFD', s)
|
||||
if not unicodedata.combining(c)))
|
||||
|
||||
|
||||
def _strip_nonalnum(parts):
|
||||
"""Strip all non-alphanumerical characters from a list of strings.
|
||||
|
||||
>>> print(_strip_nonalnum([u"ÅA. B. Testing 12+}[.@~_", u" 3%"]))
|
||||
AABTesting123
|
||||
"""
|
||||
s = "".join(parts)
|
||||
return _nonalnum_pattern.sub("", _strip_accents(s))
|
||||
|
||||
|
||||
class LabelStyle(BaseLabelStyle):
|
||||
def format_labels(self, sorted_entries):
|
||||
labels = [self.format_label(entry) for entry in sorted_entries]
|
||||
count = Counter(labels)
|
||||
counted = Counter()
|
||||
for label in labels:
|
||||
if count[label] == 1:
|
||||
yield label
|
||||
else:
|
||||
yield label # + chr(ord('a') + counted[label])
|
||||
# counted.update([label])
|
||||
|
||||
def format_label(self, entry):
|
||||
label = "Anonymous"
|
||||
if 'author' in entry.persons:
|
||||
label = self.format_author_or_editor_names(entry.persons['author'])
|
||||
elif 'editor' in entry.persons:
|
||||
label = self.format_author_or_editor_names(entry.persons['editor'])
|
||||
elif 'organization' in entry.fields:
|
||||
label = entry.fields['organization']
|
||||
if label.startswith("The "):
|
||||
label = label[4:]
|
||||
return ''
|
||||
# if 'year' in entry.fields:
|
||||
# return "{}, {}".format(label, entry.fields['year'])
|
||||
# else:
|
||||
# return "{}, n.d.".format(label)
|
||||
|
||||
def format_author_or_editor_names(self, persons):
|
||||
if len(persons)==1:
|
||||
return _strip_nonalnum(persons[0].last_names)
|
||||
elif len(persons)==2:
|
||||
return "{} & {}".format(
|
||||
_strip_nonalnum(persons[0].last_names),
|
||||
_strip_nonalnum(persons[1].last_names))
|
||||
else:
|
||||
return "{} et al.".format(
|
||||
_strip_nonalnum(persons[0].last_names))
|
||||
0
book/_ext/pybtexapastyle/names/__init__.py
Normal file
0
book/_ext/pybtexapastyle/names/__init__.py
Normal file
39
book/_ext/pybtexapastyle/names/firstlast.py
Normal file
39
book/_ext/pybtexapastyle/names/firstlast.py
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
# -*- coding:Utf-8 -*-
|
||||
from __future__ import unicode_literals
|
||||
|
||||
from pybtex.style.names import BaseNameStyle, name_part
|
||||
from pybtex.style.template import join
|
||||
|
||||
|
||||
class NameStyle(BaseNameStyle):
|
||||
|
||||
def format(self, person, abbr=False):
|
||||
r"""
|
||||
Format names similarly to {vv~}{ll}{, jj}{, f.} in BibTeX.
|
||||
|
||||
>>> from pybtex.database import Person
|
||||
>>> name = Person(string=r"Charles Louis Xavier Joseph de la Vall{\'e}e Poussin")
|
||||
>>> firstlast = NameStyle().format
|
||||
|
||||
>>> print(firstlast(name).format().render_as('latex'))
|
||||
Charles Louis Xavier~Joseph de~la Vall{é}e~Poussin
|
||||
>>> print(firstlast(name).format().render_as('html'))
|
||||
Charles Louis Xavier Joseph de la Vall<span class="bibtex-protected">é</span>e Poussin
|
||||
|
||||
>>> print(firstlast(name, abbr=True).format().render_as('latex'))
|
||||
C.~L. X.~J. de~la Vall{é}e~Poussin
|
||||
>>> print(firstlast(name, abbr=True).format().render_as('html'))
|
||||
C. L. X. J. de la Vall<span class="bibtex-protected">é</span>e Poussin
|
||||
|
||||
>>> name = Person(first='First', last='Last', middle='Middle')
|
||||
>>> print(firstlast(name).format().render_as('latex'))
|
||||
First~Middle Last
|
||||
>>> print(firstlast(name, abbr=True).format().render_as('latex'))
|
||||
F.~M. Last
|
||||
|
||||
"""
|
||||
return join[
|
||||
name_part(abbr=abbr)[person.rich_first_names + person.rich_middle_names],
|
||||
name_part(before=' ')[person.rich_prelast_names],
|
||||
name_part(before=' ')[person.rich_last_names],
|
||||
]
|
||||
27
book/_ext/pybtexapastyle/setup.py
Normal file
27
book/_ext/pybtexapastyle/setup.py
Normal file
|
|
@ -0,0 +1,27 @@
|
|||
import setuptools
|
||||
|
||||
|
||||
setuptools.setup(
|
||||
name='pybtex-apa-style',
|
||||
version='1.3',
|
||||
author='Naeka',
|
||||
author_email='contact@naeka.fr',
|
||||
description='Pybtex APA-like style',
|
||||
url='https://github.com/naeka/pybtex-apa-style',
|
||||
py_modules=['formatting.apa', 'labels.apa', 'names.firstlast'],
|
||||
entry_points={
|
||||
'pybtex.style.formatting': 'apa = formatting.apa:APAStyle',
|
||||
'pybtex.style.labels': 'apa = labels.apa:LabelStyle',
|
||||
'pybtex.style.names': 'firstlast = names.firstlast:NameStyle',
|
||||
},
|
||||
classifiers=(
|
||||
'Operating System :: OS Independent',
|
||||
'Programming Language :: Python',
|
||||
'Programming Language :: Python :: 2.7',
|
||||
'Programming Language :: Python :: 3',
|
||||
'License :: OSI Approved :: MIT License',
|
||||
'Operating System :: OS Independent',
|
||||
'Topic :: Text Processing :: Markup',
|
||||
'Topic :: Utilities',
|
||||
),
|
||||
)
|
||||
|
|
@ -4,10 +4,14 @@
|
|||
|
||||
[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 +28,4 @@ Below you see an example of this feature!
|
|||
theme="github-light"
|
||||
crossorigin="anonymous"
|
||||
async>
|
||||
</script>
|
||||
</script>
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ Parts of this book are taken from other external resources. If an author is not
|
|||
|
||||
The following pages are not edited by the TeachBooks Team:
|
||||
|
||||
- [](external/latex-to-markdown-conversion/README.md) {cite:ts}`timon_latex`, [BSD 3-clause license](https://opensource.org/license/BSD-3-Clause).
|
||||
- [](external/latex-to-markdown-conversion/README.md) by {cite:t}`timon_latex`, [BSD 3-clause license](https://opensource.org/license/BSD-3-Clause).
|
||||
|
||||
The following pages contain content written by others, part of which may be reused and/or modified by the TeachBooks Team:
|
||||
- Page {ref}`copyright_licenses` includes an unmodified figure, paraphrased and quoted text (including hyperlinks) from {cite:ts}`hall21`.
|
||||
|
|
@ -42,4 +42,4 @@ The following pages contain content written by others, part of which may be reus
|
|||
Big thanks to the various colleagues and teaching assistant part of the [TeachBooks](https://teachbooks.io/) for developing tools and providing support to improve this book.
|
||||
|
||||
## 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. Additional licenses may be applicable for external resources.
|
||||
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. Additional licenses may be applicable for external resources.
|
||||
|
|
|
|||
2
book/external/Sphinx-TUDelft-theme
vendored
2
book/external/Sphinx-TUDelft-theme
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 0f4758586bebb1db4da0738b66d02d883ff7b54d
|
||||
Subproject commit a7a87d4d4c9dc3839af49104492048724d1e6191
|
||||
2
book/external/template
vendored
2
book/external/template
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 5aadbc527ee1251a60cbd4877d109b0558e03aad
|
||||
Subproject commit 9c54cdf1ccbfdb8bfb4b79090b83019f00cfc828
|
||||
BIN
book/images/TB_logo.png
Normal file
BIN
book/images/TB_logo.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 544 KiB |
BIN
book/images/TB_logo_dark.png
Normal file
BIN
book/images/TB_logo_dark.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 268 KiB |
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 175 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 192 KiB |
BIN
book/installation-and-setup/figures/usertype1.jpg
Normal file
BIN
book/installation-and-setup/figures/usertype1.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 61 KiB |
BIN
book/installation-and-setup/figures/usertype2.jpg
Normal file
BIN
book/installation-and-setup/figures/usertype2.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 63 KiB |
BIN
book/installation-and-setup/figures/usertype3.jpg
Normal file
BIN
book/installation-and-setup/figures/usertype3.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 57 KiB |
BIN
book/installation-and-setup/figures/usertype4.jpg
Normal file
BIN
book/installation-and-setup/figures/usertype4.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 55 KiB |
BIN
book/installation-and-setup/figures/usertype5.jpg
Normal file
BIN
book/installation-and-setup/figures/usertype5.jpg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 61 KiB |
|
|
@ -2,24 +2,76 @@
|
|||
|
||||
Different types of users will interact with the website or the Jupyter Books differently and will therefore need to know more or less about the composition of the book. For now we will differentiate 5 types of users.
|
||||
|
||||
1. **Students providing feedback on the published website**.<br>
|
||||
<img src="figures/type 1.jpg" alt="Example Image" align="right" width="130" style="margin: 20px;"><br>There are multiple tools of providing feedback in the built book:<br>a) using the issue button in the top-right corner to directly create issues visible to the editor team.<br>b) Using the [hypothesis](https://jupyterbook.org/en/stable/interactive/comments/hypothesis.html)-extension which allows public/private highlighting and annotating parts of the book. An example can be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html).<br>c) Using the [Utterances](https://jupyterbook.org/en/stable/interactive/comments/utterances.html)-extension which allows commenting on pages for books which are hosted on GitHub visible for everyone. Those comments are converted to issues on GitHub for the editors to handle.
|
||||
## User type 1: Students providing feedback via the book website
|
||||
|
||||
2. **Colleague providing feedback on the draft website**. <br>
|
||||
In a similar manner as students, colleages and team members can leave content-related comments on the website through extensions. In this way, multiple teachers can give input in the draft of the textbook and course material without requiring and exact understanding of Jupyter Books or GitLab/GitHub. The responsible teacher (or student assistants) can then make the adaptations to the book as recommended by their colleagues.
|
||||
```{figure} figures/usertype1.jpg
|
||||
---
|
||||
name: usertype1
|
||||
width: 300px
|
||||
align: center
|
||||
---
|
||||
|
||||
3. **Colleague making adjustments to single files in GitLab/GitHub using single text editor**. <br>
|
||||
This type of user requires only very basic knowledge in GitLab/GitHub in order to make changes to the website themselves without needing to install any software! Making adjustments using single text editor only requires the user to be able to login into GitLab/GitHub and edit .md or .ipynb files. The changes can be done directly in the main or publish branch and if a new branch is needed for the changes then the set-up and merging can be taken care of by someone more familiar in GitLab/GitHub.
|
||||
```
|
||||
|
||||
4. **Colleague making text adjustments to multiple files at the same time locally**. <br>
|
||||
User 4 is a hybrid between type 3 and 5. Basically this user is making changes by editing the .md files locally using, for example, VS Code. Therefore, this user requires a little bit more knowledge on git (think of pulling and pushing changes) but their main focus remains to make adjustments to the content of the book by editing .md files whereas user type 5 has more knowledge to make changes to python files the book as well. This user can build the book online.
|
||||
There are multiple tools of providing feedback in the built book:
|
||||
|
||||
5. **Colleague making text and code (especially Python) adjustments to multiple files at the same time locally**. <br>
|
||||
<img src="figures/type 5.jpg" alt="Example Image" align="right" width="120" style="margin: 20px;"><br>This user has more knowledge in GitLab/GitHub than the previous user and can basically take care of branching and merging by themselves. They know how to work with software for editing .md and .ipynb files. They can use the draft book online to view their changed in the book, or build the book locally.
|
||||
1. using the issue button in the top-right corner to directly create issues visible to the editor team.
|
||||
2. Using the [hypothesis](../basic-features/hypothesis.md)-extension which allows public/private highlighting and annotating parts of the book.
|
||||
3. Using the [Utterances](../basic-features/utterances.md)-extension which allows commenting on pages for books which are hosted on GitHub visible for everyone. Those comments are converted to issues on GitHub for the editors to handle.
|
||||
|
||||
<br style="clear:both;">
|
||||
## User type 2: Colleague providing feedback on a draft website
|
||||
|
||||
```{figure} figures/usertype2.jpg
|
||||
---
|
||||
name: usertype2
|
||||
width: 300px
|
||||
align: center
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
In a similar manner as students, colleagues and team members can leave content-related comments on the website through extensions or GitHub/GitLab features (e.g., Issues). In this way, multiple teachers can give input in the draft of the textbook and course material without requiring a complete understanding of Jupyter Books or GitLab/GitHub. The responsible teacher (or student assistants) can then make adaptations to the book as recommended by their colleagues.
|
||||
|
||||
## User type 3: Colleague making adjustments via the browser
|
||||
|
||||
```{figure} figures/usertype3.jpg
|
||||
---
|
||||
name: usertype3
|
||||
width: 300px
|
||||
align: center
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
This type of user requires only very basic knowledge in GitLab/GitHub in order to make changes to the website themselves. Most importantly, there is no need to install any software! Making adjustments to a file only requires the user to be able to login into GitLab/GitHub and edit .md or .ipynb files. The changes can be done directly in an existing branch, or, if unsure, a new branch can be used for the changes then the set-up and merging can be completed by someone more familiar with GitLab/GitHub. Files can be edited individually or many-at-a-time using the VS Code-style browser application.
|
||||
|
||||
## User type 4: Colleague making adjustments locally
|
||||
|
||||
```{figure} figures/usertype4.jpg
|
||||
---
|
||||
name: usertype4
|
||||
width: 300px
|
||||
align: center
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
User 4 is a hybrid between type 3 and 5. Basically this user is making changes by editing the .md files locally using, for example, VS Code. Therefore, this user requires a little bit more knowledge on git (think of pulling and pushing changes) but their main focus remains to make adjustments to the content of the book by editing .md files whereas user type 5 has more knowledge to make changes to python files the book as well. This user can build the book online and therefore does not need to have special software installed besides a text editor (e.g., Python is not required).
|
||||
|
||||
## User type 5: Colleague making adjustments and incorporating them in the book locally
|
||||
|
||||
```{figure} figures/usertype5.jpg
|
||||
---
|
||||
name: usertype5
|
||||
width: 300px
|
||||
align: center
|
||||
---
|
||||
|
||||
```
|
||||
|
||||
This user has more knowledge in GitLab/GitHub than the previous user and can take care of branching and merging directly. They know how to work with software for editing .md and .ipynb files. They can use the Deploy Book Workflow online to view their changes in the book and coordinate peer review, and/or build the book locally.
|
||||
|
||||
```{Note}
|
||||
|
||||
At this point, you might already be trying to see which user type fits you the best. We are aware that the lines between user types can be a bit blurry, especially between type 3, 4 and 5. In case you're (1) a user type 3 and want to dabble in git or (2) a user type 4/5 and want to make some quick edits with only a few clicks, then you might consider using a more advanced online editor in GitHub (GitHub Dev) as explained further on in [Collaborative book-editing > Edit](../workflows/edit_book.md) > User type 3 > GitHub > Using VS Code in your browser.
|
||||
```
|
||||
At this point, you might already be trying to see which user type fits you the best. We are aware that the lines between user types can be a bit blurry, especially between type 3, 4 and 5. If you've no experience in git and programming, we advise you to start as user type 3, if you're a bit more experienced you can consider skipping that step. In case you're (1) a user type 3 and want to dabble in git or (2) a user type 4/5 and want to make some quick edits with only a few clicks, then you might consider using a more advanced online editor in GitHub (GitHub Dev) as explained further on in [Collaborative book-editing > Edit](../workflows/edit_book.md) > User type 3 > GitHub > Using VS Code in your browser.
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
|
@ -78,45 +83,50 @@ In GitHub, you can directly make changes in the files on the remote repository.
|
|||
2. Create a new file by clicking on the button called `Add file` in the top bar. You can either create an entirely new file by clicking `Create new File` or if you already have created a file you can upload it by clicking `Upload files`.
|
||||
|
||||
```{figure} figures/HubUser3_NewFile.PNG
|
||||
---
|
||||
width: 80%
|
||||
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: `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
|
||||
```
|
||||
````
|
||||
|
|
@ -156,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>
|
||||
````
|
||||
`````
|
||||
``````
|
||||
|
|
@ -218,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">
|
||||
|
|
@ -226,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">
|
||||
|
|
@ -240,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.
|
||||
|
|
@ -297,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'
|
||||
|
|
@ -350,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
|
||||
```
|
||||
````
|
||||
`````
|
||||
``````
|
||||
|
|
@ -512,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">
|
||||
|
|
@ -520,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">
|
||||
|
|
@ -534,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">
|
||||
|
|
@ -622,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
BIN
book/workflows/figures/Push_GitHubDekstop.PNG
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
|
|
@ -4,20 +4,22 @@
|
|||
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 +28,21 @@ 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
25
book/workflows/stage_commit_push_github_desktop.md
Normal 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
|
||||
```
|
||||
31
book/workflows/stage_commit_push_vscode.md
Normal file
31
book/workflows/stage_commit_push_vscode.md
Normal file
|
|
@ -0,0 +1,31 @@
|
|||
**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
|
||||
|
||||
---
|
||||
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
|
||||
|
||||
---
|
||||
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
|
||||
---
|
||||
After committing, click the 🔄 button to push our changes to the remote repository.
|
||||
```
|
||||
|
|
@ -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]
|
||||
|
|
@ -10,3 +10,5 @@ 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue