mirror of
https://github.com/TeachBooks/manual.git
synced 2026-11-12 22:35:51 +00:00
user types in margins
This commit is contained in:
Tom van Woudenberg
parent
748f68d6d9
commit
ae4f209be2
34 changed files with 141 additions and 102 deletions
|
|
@ -1,11 +1,13 @@
|
|||
# Making comments on the website: Hypothesis
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 1-5.
|
||||
```
|
||||
|
||||
{bdg-warning}`Javascript overlay` {bdg-success}`Chrome Extension`
|
||||
````
|
||||
|
||||
# Making comments on the website: Hypothesis
|
||||
|
||||
Hypothesis is a third-party application that allows anyone to make publicly visible comments on a website (once you create a free account). This section explains how to use and install the extension. As this tool requires an account with a third-party, we advise to use our [local-annotator](../external/annotater/README.md) with similar capabilities but which store annotations locally. By default Hypothesis stores annotations publicly, which might confuse other students.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,10 @@
|
|||
# Original Jupyter Book and Sphinx Features
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for [user type 3-5](../installation-and-setup/user_types.md).
|
||||
```
|
||||
````
|
||||
|
||||
# Original Jupyter Book and Sphinx Features
|
||||
|
||||
These pages will provide a list of some common, basic book features which are all available in the original <a href="https://jupyterbook.org/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book"></a> package. Additionally, this page includes also best-practices.
|
||||
|
|
|
|||
|
|
@ -1,11 +1,13 @@
|
|||
# Discussions in your book: Utterances
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 3-5.
|
||||
```
|
||||
|
||||
{bdg-white}`GitHub app and Javascript script`
|
||||
````
|
||||
|
||||
# Discussions in your book: Utterances
|
||||
|
||||
[Utterances 🔮](https://utteranc.es/) is a lightweight open-source widget which allows you, your colleages and your students to discuss stuff in a blog post in your book. It is build on GitHub issues, so requires a GitHub repository, although the book can be hosted anywhere (so also on GitLab).
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Interactive HTML/JavaScript elements
|
||||
````{margin}
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
|
|
@ -6,6 +6,9 @@ This section is useful for user type 5.
|
|||
```
|
||||
|
||||
{bdg-danger}`iframe`
|
||||
````
|
||||
|
||||
# Interactive HTML/JavaScript elements
|
||||
|
||||
In this section, we will discuss how to [create](creating_basic_HTML_elements.md) and [embed](adding_HTML_elements.md) interactive HTML/Javascript elements created in HTML/JavaScript in a TeachBook. These HTML/Javascript element work very fluently and don't require a python kernel running in the background.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
# Adding interactive HTML/JavaScript elements
|
||||
|
||||
````{margin}
|
||||
{bdg-danger}`iframe`
|
||||
````
|
||||
|
||||
# Adding interactive HTML/JavaScript elements
|
||||
|
||||
In this section, we will discuss how to embed interactive elements created in HTML/JavaScript in a TeachBook. If you are interested in learning how to create these elements yourself, we will discuss an example in the [next article](creating_basic_HTML_elements.md). As an example, let us discuss how to embed an interactive 3D model of a subsurface environment I created:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,12 +1,14 @@
|
|||
(apa)=
|
||||
# APA References
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 4 and 5.
|
||||
```
|
||||
|
||||
{bdg-primary}`(To be converted into) Sphinx Extension`
|
||||
````
|
||||
|
||||
(apa)=
|
||||
# APA References
|
||||
|
||||
```{note}
|
||||
This feature is stable but because it relies on a local extension that is part of your book files and _not_ managed as part of a computing environment (e.g., `pip` or `conda`), unknown issues may arise. We would like to convert this feature into an independent Sphinx extension and/or Pybtext plugin. Visit the [project page on GitHub](https://github.com/orgs/TeachBooks/projects/17) to learn more.
|
||||
|
|
|
|||
|
|
@ -1,11 +1,13 @@
|
|||
# Multilingual book
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 4 and 5.
|
||||
```
|
||||
{bdg-primary}`Sphinx Extension`
|
||||
|
||||
````
|
||||
|
||||
# Multilingual book
|
||||
The custom launch button extension allows you to create a customizable button in the top right of your jupyter book.
|
||||
This may have many applications, one of them being that you can create different language versions of the book available for the user.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,10 @@
|
|||
# Easy Editing Process
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 3-5.
|
||||
```
|
||||
````
|
||||
|
||||
# Easy Editing Process
|
||||
|
||||
The following tools are created by TeachBooks to ease the process of making books. We acknowledge that making books is a difficult process; it requires advanced knowledge on CLI, python packages, html-files, data-storage and website hosting. The tools in this chapter are intended for those users who lack knowledge on these topics (which includes most of the TeachBooks' community members itself).
|
||||
|
|
@ -1,12 +1,14 @@
|
|||
(external-toc)=
|
||||
# Sharing content between books in table of contents
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 3-5.
|
||||
```
|
||||
|
||||
{bdg-secondary}`Python Package: teachbooks`
|
||||
````
|
||||
|
||||
(external-toc)=
|
||||
# Sharing content between books in table of contents
|
||||
|
||||
## Introduction
|
||||
|
||||
|
|
|
|||
File diff suppressed because one or more lines are too long
|
|
@ -1,11 +1,13 @@
|
|||
# H5p interactive elements
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 3-5.
|
||||
```
|
||||
|
||||
{bdg-danger}`iframe`
|
||||
````
|
||||
|
||||
# H5p interactive elements
|
||||
|
||||
## Instruction
|
||||
H5p elements are interactive HTML-blocks which can be embedded in a Jupyter Book using an iframe. An H5p element can be created in the [TU Delft portal on the H5p website](https://tudelft.h5p.com/content) (sign in via Brightspace to H5p required first). The iframe code can be copied at Edit - Publish - Public - Embed code. This html code can be directly added to your markdown file using [](../external/sphinx-iframes/README.md):
|
||||
|
|
|
|||
|
|
@ -7,14 +7,16 @@
|
|||
"hidePrompt": true
|
||||
},
|
||||
"source": [
|
||||
"# JupyterQuiz\n",
|
||||
"\n",
|
||||
"````{margin}\n",
|
||||
"```{admonition} User types\n",
|
||||
":class: tip\n",
|
||||
"This section is useful for user type 4-5.\n",
|
||||
"```\n",
|
||||
"\n",
|
||||
"- {bdg-secondary}`Python Package: jupyterquiz`\n",
|
||||
"{bdg-secondary}`Python Package: jupyterquiz`\n",
|
||||
"````\n",
|
||||
"\n",
|
||||
"# JupyterQuiz\n",
|
||||
"\n",
|
||||
"JupyterQuiz is a code-based implementation of multiple-choiche questions and numerical answer questions. This is a basic open course tool which requires you to write your quiz questions in Python language as a `dict` or to a `.json` file. An example is given below:\n",
|
||||
"\n",
|
||||
|
|
|
|||
|
|
@ -4,12 +4,14 @@
|
|||
"cell_type": "markdown",
|
||||
"metadata": {},
|
||||
"source": [
|
||||
"# Interactive content: Run Python inside your book\n",
|
||||
"\n",
|
||||
"````{margin}\n",
|
||||
"```{admonition} User types\n",
|
||||
":class: tip\n",
|
||||
"This section is useful for user type 5.\n",
|
||||
"```\n",
|
||||
"```` \n",
|
||||
"\n",
|
||||
"# Interactive content: Run Python inside your book\n",
|
||||
"\n",
|
||||
"{bdg-primary}`Sphinx Extension`\n",
|
||||
"\n",
|
||||
|
|
|
|||
|
|
@ -1,12 +1,14 @@
|
|||
(setup-local-server)=
|
||||
# Local Server to view interactive elements locally
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 4-5.
|
||||
```
|
||||
|
||||
{bdg-secondary}`Python Package: teachbooks`
|
||||
````
|
||||
|
||||
(setup-local-server)=
|
||||
# Local Server to view interactive elements locally
|
||||
|
||||
Perhaps you have already noticed that when building a book and testing it locally on your computer, some features do not work the way you expect, or worse---do not work at all! This is because many interactive features rely on browser functionality to work properly, for example: Grasple/H5p iframe exercises, Sphinx-Thebe Python interactivity and HTML/Javascript elements. Although the website is _static_ (i.e., there is no code running on a webserver that generates the content), modern web browsers have their own internal computing environments that run processes to deliver the rich content we desire in our books.
|
||||
|
||||
|
|
|
|||
|
|
@ -7,12 +7,14 @@
|
|||
"hidePrompt": true
|
||||
},
|
||||
"source": [
|
||||
"# Interactive plots: plotly\n",
|
||||
"\n",
|
||||
"````{margin}\n",
|
||||
"```{admonition} User types\n",
|
||||
":class: tip\n",
|
||||
"This section is useful for user type 5.\n",
|
||||
"```\n",
|
||||
"````\n",
|
||||
"\n",
|
||||
"# Interactive plots: plotly\n",
|
||||
"\n",
|
||||
"The use of the [plotly](https://plotly.com/python/getting-started/) package is an example which allows you to create HTML/Javascript widgets from python code without any knowledge on HTML/Javascript."
|
||||
]
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
# Build pull requests from forks
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 3-5.
|
||||
```
|
||||
````
|
||||
|
||||
# Build pull requests from forks
|
||||
|
||||
When writing a TeachBook it is useful to automatically build and view these changes online. This exactly why we designed and build the [deploy-book-workflow](../external/deploy-book-workflow/README.md) tool, which also allows for multiple versions of your book to exist at any time with customizable URL's. However, it doesn't cover all use cases. Luckily, **Read the Docs** is a free tool that can easily be used for this purpose. It also provides a very easy way to view differences between versions on each page!
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,10 @@
|
|||
# Additional functionality
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 4-5.
|
||||
```
|
||||
````
|
||||
|
||||
# Additional functionality
|
||||
|
||||
This sections includes the features developed by TeachBooks which add functionality to the book. Most of them are implemented as sphinx extensions, which are plugins developed for the Sphinx documentation ecosystem (which Jupyter Book is built upon). They extend or modify Sphinx’s capabilities. Since Sphinx extensions are not an integral part of jupyter-book, as opposed to original jupyter-book features, they must be installed and configured explicitly, for example in the `_config.yml` file.
|
||||
|
|
@ -1,8 +1,11 @@
|
|||
# TeachBooks Student-view Features
|
||||
|
||||
````
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 1-5.
|
||||
```
|
||||
````
|
||||
|
||||
# TeachBooks Student-view Features
|
||||
|
||||
|
||||
This chapter includes some TeachBooks features which aim to improve the way students can use TeachBooks. These tools are fully student-side, they don't influence the book website and the author doesn't have to setup anything. Nevertheless, the author could point the students to the availability of these tools and use it as part of the didactical approach. These tools could also be useful for other users.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,4 @@
|
|||
(teachbooks-package)=
|
||||
# Draft-Release Workflow
|
||||
````{margin}
|
||||
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
|
|
@ -8,6 +7,11 @@ This page is useful for user type 3-5.
|
|||
|
||||
{bdg-secondary}`Python Package: teachbooks`
|
||||
|
||||
````
|
||||
|
||||
(teachbooks-package)=
|
||||
# Draft-Release Workflow
|
||||
|
||||
Often it is necessary to prepare, review and edit materials in parallel to material that is currently being used by students, or another target audience. This workflow enables an author to easily maintain separate versions of a book without having to repeatedly comment out lines of a table of contents or page when building different versions. It is also easy to implement in CI/CD settings (it is already implemented in the {ref}Deploy Book Workflow <deploy-book-workflow>`, which builds our TeachBooks).
|
||||
|
||||
```{admonition} Why is this useful?
|
||||
|
|
|
|||
|
|
@ -1,11 +1,13 @@
|
|||
# Auto-updating packages
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 4-5.
|
||||
```
|
||||
|
||||
{bdg-dark}`Git Workflow`
|
||||
````
|
||||
|
||||
# Auto-updating packages
|
||||
|
||||
When building your book, your making use of packages: the teachbooks and jupyterbook packages themselves, but also packages for extensions. These are regularly updated, while those updates are not necessarily taken into your book. This is all defined in the `requirements.txt` file, which is provided as part of the [template](../external/template/README.md). There are three options:
|
||||
1. `requirements.txt` only contains names of packages like: `download_link_replacer`. In that case, your [deploy-book-workflow](../external/deploy-book-workflow/README.md) will take the most up-to-date version when making your book website once a week (as the chache will be cleared once a week). This might lead to unexpected changes when new version come out, although new version are in general backwards compatible.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,10 @@
|
|||
# TeachBooks Versioning
|
||||
````{margin}
|
||||
```{attributiongrey} Attribution
|
||||
:class: attribution
|
||||
This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.<external_resources>````
|
||||
````
|
||||
|
||||
> This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.<external_resources>`
|
||||
# TeachBooks Versioning
|
||||
|
||||
Inspired by versioning systems in software management (i.e. semantic and CalVer versioning) TeachBooks suggests a versioning guideline in which the version number tells the reader about the impact of the change. This might more suitable for your online books than the more traditional way of versioning paper books (version 1, 2, etc.), because of the amount of edits which online books allow. We recommend TeachBooks versioning, which comes in two flavors:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,10 @@
|
|||
# Book styling
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 1-5.
|
||||
```
|
||||
````
|
||||
|
||||
# Book styling
|
||||
|
||||
TeachBooks developed a few improvements of the book which improve the visual book styling.
|
||||
|
|
@ -1,9 +1,11 @@
|
|||
# Managing code-related software: Anaconda
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 5.
|
||||
```
|
||||
````
|
||||
|
||||
# Managing code-related software: Anaconda
|
||||
|
||||
Before you can start using python in your book, you need Anaconda. 'Anaconda's conda tool simplifies package and environment management across operating systems' (Anaconda.com), such as windows or MacOS. It makes getting started with python a lot easier because it already has a lot of useful python packages pre-installed. Unfortunately, each of these packages are themselves require a number of different packages to function properly. Do you like installing all of them? You shouldn't---but where do you get them come from? Many of those packages are packages required by only a few specific packages. These packages are called _dependencies_, and are necessary to make your Python packages function as expected. When you run install a specific package, `conda` (part of Anaconda) checks all of the dependent packages that are needed and makes sure they are also provided in the `environment` (collection of software with a specific version) that is being created. In reality, this is simply a folder on your computer with all of the `*.py` files stored in it. This _package management_ is what `conda` and `pip` are really doing when you use them to install a package. It also checks that it has a suitable _version_ of each dependency; this is why it sometime takes a long time to install a package Unfortunately, this means that as you add more packages to a particular environment, it gets more and more difficult to make sure everything works well together. Luckily, there is a practical solution: create new environments for specific projects to make sure the proper packages can function properly!
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
# Organize editing team, collaboration and visibility
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 4-5.
|
||||
```
|
||||
````
|
||||
|
||||
# Organize editing team, collaboration and visibility
|
||||
|
||||
## Roles and responsibilities
|
||||
To ensure smooth collaboration, it is essential to define the roles and responsibilities within your team. Firstly, designate who will be in charge of team organization ('administrators') who should be at least user type 4. Additionally, assign 'maintainers' responsible for combining content, also requiring at least user type 4. 'Editors' should be identified for editing and reviewing content, requiring at least user type 3.
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
# Git: GitHub Desktop / Git in VS Code
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 4 and 5.
|
||||
```
|
||||
````
|
||||
|
||||
# Git: GitHub Desktop / Git in VS Code
|
||||
|
||||
In this section you will learn how to install Git locally. Courses on Git usually make use of the command line interface to do run Git, but this introduces a steep learning curve. Instead, using Git from VS Code / GitHub Desktop is much more visual (i.e., more "clicky"), and therefore easier to use for those inexperienced with the command line.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
# Collaboration tool: Git
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 3-5.
|
||||
```
|
||||
````
|
||||
|
||||
# Collaboration tool: Git
|
||||
|
||||
You will need to interact with Git to collaborate on a TeachBook, even if you are working by yourself! You've been introduced to it in the [exercises in the template](../intro/template.md) and you'll be guided through all of the steps in detail in [](../workflows/collaboration.md), but what is this "thing" that sounds suspiciously like something only a computer scientist would want to use?
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
# Combining Git Bash, VS Code and Conda
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 5.
|
||||
```
|
||||
````
|
||||
|
||||
# Combining Git Bash, VS Code and Conda
|
||||
|
||||
## Conda in Git Bash
|
||||
Git Bash is a shell (also referred to as "the terminal") that is automatically installed with git. It provides Unix-like commands on a Windows OS, and is recommended for working with open source projects like Jupyter (for example `pip install`, building Jupyter books, using Git Bash in VS Code, etc). To do this, `conda` needs to be setup properly; this is described here:
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
# Build your book: JupyterBook
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 5.
|
||||
```
|
||||
````
|
||||
|
||||
# Build your book: JupyterBook
|
||||
|
||||
<a href="https://jupyterbook.org/"><img style="display:inline-block; height:1.5em; width:auto; transform:translate(0, -0.15em)" src="../images/logo-wide.svg" alt="Jupyter book"></a> is a regular Python package which converts our content into a website. It's part of all of the `requirements.txt` files for a book repository. At TeachBooks we developed a Python package called `teachbooks` which takes over the these features and adds [additional features](../features/overview.md). One of those additional features, for example, is the workflow to GitHub Pages.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
# Install & authenticate required software
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 4-5.
|
||||
```
|
||||
````
|
||||
|
||||
# Install & authenticate required software
|
||||
|
||||
Now that the types of users have been explained, you might have an idea which type corresponds to you!
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
# Which git provider to choose
|
||||
|
||||
````
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 4-5.
|
||||
```
|
||||
````
|
||||
|
||||
# Which git provider to choose
|
||||
|
||||
The setup of tools and URLs is dependent on agreements you've made on [collaboration](./collab.md).
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
# Versioning and URLs
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 4-5.
|
||||
```
|
||||
````
|
||||
|
||||
# Versioning and URLs
|
||||
|
||||
Online books can be easily updated, however, this might confuse readers. Therefore, it's good practice to be aware of this and, where needed, provide an explicit version to the readers.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
# Editing text: VS Code
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 4 and 5.
|
||||
```
|
||||
````
|
||||
|
||||
# Editing text: VS Code
|
||||
|
||||
VS Code is a text editor with some extra features, such as integrated source control and a file browser. Moreover, extensions are available to add functionality to VS Code.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
# Figure syntax maker
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This section is useful for user type 3-5.
|
||||
```
|
||||
````
|
||||
|
||||
# Figure syntax maker
|
||||
|
||||
One might quickely forget the code for making figures, here is a useful tool to make your figures, just specify all information and the code is produced for you:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,11 @@
|
|||
# Collaborative book-editing
|
||||
|
||||
````{margin}
|
||||
```{admonition} User types
|
||||
:class: tip
|
||||
This page is useful for user type 3, 4 and 5.
|
||||
```
|
||||
````
|
||||
|
||||
# Collaborative book-editing
|
||||
|
||||
A jupyter book is composed out of many files which contain the educational content produced by you. Through the use of branches it is possible to work on the book at the same time as your team-members. Working on content for the book is mainly individual work, the beauty of Git comes in when everybody's changes are merged into the main branch.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue