From ae4f209be2f67375328ede3bafae4e922dc2fbca Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 1 Apr 2025 15:00:43 +0200 Subject: [PATCH] user types in margins --- book/basic-features/hypothesis.md | 6 ++-- book/basic-features/overview.md | 6 ++-- book/basic-features/utterances.md | 6 ++-- book/features/HTML_javascript.md | 5 ++- book/features/adding_HTML_elements.md | 6 ++-- book/features/apa.md | 8 +++-- book/features/custom-launch-button.md | 6 ++-- book/features/easy-editing.md | 6 ++-- book/features/external_toc.md | 8 +++-- book/features/github_deploy.md | 33 ------------------- book/features/h5p.md | 6 ++-- book/features/jupyterquiz.ipynb | 8 +++-- book/features/live_code.ipynb | 6 ++-- book/features/local_server.md | 8 +++-- book/features/plotly.ipynb | 6 ++-- book/features/pull_request_build.md | 6 ++-- book/features/sphinx_extensions.md | 6 ++-- book/features/students.md | 7 ++-- book/features/teachbooks.md | 8 +++-- book/features/update_env.md | 6 ++-- book/features/versioning.md | 8 +++-- book/features/visuals.md | 6 ++-- book/installation-and-setup/anaconda.md | 6 ++-- book/installation-and-setup/collab.md | 6 ++-- .../installation-and-setup/git-setup_local.md | 6 ++-- book/installation-and-setup/git.md | 6 ++-- .../git_bash_conda_vs-code.md | 6 ++-- .../jupyter-book-setup.md | 6 ++-- book/installation-and-setup/overview.md | 6 ++-- book/installation-and-setup/tools.md | 6 ++-- book/installation-and-setup/versioning.md | 6 ++-- book/installation-and-setup/vscode-setup.md | 6 ++-- book/tools/figmaker.md | 6 ++-- book/workflows/collaboration.md | 6 ++-- 34 files changed, 141 insertions(+), 102 deletions(-) delete mode 100644 book/features/github_deploy.md diff --git a/book/basic-features/hypothesis.md b/book/basic-features/hypothesis.md index 0f42e79..49ebe28 100644 --- a/book/basic-features/hypothesis.md +++ b/book/basic-features/hypothesis.md @@ -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. diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md index df68f69..a37acfb 100644 --- a/book/basic-features/overview.md +++ b/book/basic-features/overview.md @@ -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 Jupyter book package. Additionally, this page includes also best-practices. diff --git a/book/basic-features/utterances.md b/book/basic-features/utterances.md index f82a44f..cbdc82e 100644 --- a/book/basic-features/utterances.md +++ b/book/basic-features/utterances.md @@ -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). diff --git a/book/features/HTML_javascript.md b/book/features/HTML_javascript.md index dc1abdc..d579423 100644 --- a/book/features/HTML_javascript.md +++ b/book/features/HTML_javascript.md @@ -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. diff --git a/book/features/adding_HTML_elements.md b/book/features/adding_HTML_elements.md index 3e46b49..e9cbc59 100644 --- a/book/features/adding_HTML_elements.md +++ b/book/features/adding_HTML_elements.md @@ -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: diff --git a/book/features/apa.md b/book/features/apa.md index 1a91714..49bdf3f 100644 --- a/book/features/apa.md +++ b/book/features/apa.md @@ -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. diff --git a/book/features/custom-launch-button.md b/book/features/custom-launch-button.md index b935a7c..b83e67d 100644 --- a/book/features/custom-launch-button.md +++ b/book/features/custom-launch-button.md @@ -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. diff --git a/book/features/easy-editing.md b/book/features/easy-editing.md index 418f55b..d06734b 100644 --- a/book/features/easy-editing.md +++ b/book/features/easy-editing.md @@ -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). \ No newline at end of file diff --git a/book/features/external_toc.md b/book/features/external_toc.md index c0a2a50..a55ec7d 100644 --- a/book/features/external_toc.md +++ b/book/features/external_toc.md @@ -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 diff --git a/book/features/github_deploy.md b/book/features/github_deploy.md deleted file mode 100644 index 8908f66..0000000 --- a/book/features/github_deploy.md +++ /dev/null @@ -1,33 +0,0 @@ -# Publish online with GitHub Pages - -```{admonition} User types -:class: tip -This page is useful for user type 3, 4 and 5. -``` - -We developed a workflow which builds the Jupyter books in your repository for all branches, and publishes them online via GitHub Pages. The [GitHub template book](../workflows/githubtemplate.md) uses this functionality for example. - -To use this feature, add the workflow [`call-deploy-book.yml`](https://github.com/TeachBooks/deploy-book-workflow/blob/main/.github/workflows/call-deploy-book.yml) to the `/.github/workflows` folder in your repository. Furthermore, set source for GitHub pages to GitHub Actions under `Settings` - `Pages` - `Build and deployment` - `Source` - `GitHub Actions`. Additional tip: set repository website as your GitHub Pages website under `Code`- `About` - - `Website` - `Use your GitHub Pages Website` - -This workflow requires a `requirements.txt` file with `teachbooks` in your root folder, and all the book files (including `_config.yml` and `_toc.yml`) should be in a subdirectory `book/`. - -You can adapt the behaviour by setting repository variables in GitHub as explained [here](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository). Define the following repository variables: -- `PRIMARY_BRANCH` which is set to `main` whenever it's not defined in the repository variables. - - This sets the branch which is hosted on root. - - It is advised to make it `published` to start using draft-publish-workflow -- `BRANCH_ALIASES` which is set to `draft:main` whenever it's not defined in the repository variables. - - This defines aliases for branches - - It should be a space-separated list of alias-rules, e.g. 'draft:main alias:really-long-branch-name` - - It is advised to link `book` to `publish`. - - If no aliases are wanted, BRANCH_ALIASES may be set to ' ' (space). -- `BRANCHES_TO_DEPLOY` which is set to `*` (all branches) whenever it's not defined in the repository variables. - - This defines the branches to deploy. - - It should be a space-separated list of branch names, e.g. 'main second third'.- - -In `call-deploy-book.yml` itself you can specify the trigger for this workflow. By default, a push to any branch trigger the workflow. You can limit the branches or subdirectories. - -Whenever the workflow is triggered, progress can be seen under the `Actions` tab in GitHub. From this tab, you can also initiate it without any trigger commits. - -When the workflow has finished, visit your build book at `https://.github.io/` (case sensitive). Eg. for the [template book](https://github.com/TeachBooks/template) it is [https://teachbooks.github.io/template](https://teachbooks.github.io/template). diff --git a/book/features/h5p.md b/book/features/h5p.md index fab49f2..3934544 100644 --- a/book/features/h5p.md +++ b/book/features/h5p.md @@ -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): diff --git a/book/features/jupyterquiz.ipynb b/book/features/jupyterquiz.ipynb index 20f73e3..c4ee03e 100644 --- a/book/features/jupyterquiz.ipynb +++ b/book/features/jupyterquiz.ipynb @@ -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", diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb index a4703a7..55b620f 100644 --- a/book/features/live_code.ipynb +++ b/book/features/live_code.ipynb @@ -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", diff --git a/book/features/local_server.md b/book/features/local_server.md index fcdbbc1..db13af7 100644 --- a/book/features/local_server.md +++ b/book/features/local_server.md @@ -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. diff --git a/book/features/plotly.ipynb b/book/features/plotly.ipynb index ec889da..6852a21 100644 --- a/book/features/plotly.ipynb +++ b/book/features/plotly.ipynb @@ -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." ] diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md index 1ce4265..f6f94f2 100644 --- a/book/features/pull_request_build.md +++ b/book/features/pull_request_build.md @@ -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! diff --git a/book/features/sphinx_extensions.md b/book/features/sphinx_extensions.md index fa53945..d957b74 100644 --- a/book/features/sphinx_extensions.md +++ b/book/features/sphinx_extensions.md @@ -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. \ No newline at end of file diff --git a/book/features/students.md b/book/features/students.md index 46a6993..e16a668 100644 --- a/book/features/students.md +++ b/book/features/students.md @@ -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. diff --git a/book/features/teachbooks.md b/book/features/teachbooks.md index 2561e70..1349331 100644 --- a/book/features/teachbooks.md +++ b/book/features/teachbooks.md @@ -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 `, which builds our TeachBooks). ```{admonition} Why is this useful? diff --git a/book/features/update_env.md b/book/features/update_env.md index 442512a..8f7000c 100644 --- a/book/features/update_env.md +++ b/book/features/update_env.md @@ -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. diff --git a/book/features/versioning.md b/book/features/versioning.md index c769c82..a84aa27 100644 --- a/book/features/versioning.md +++ b/book/features/versioning.md @@ -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.```` +```` -> This page reuses adapted CC BY 3.0 content from Tom Preston-Werner {cite:t}`semver`. {fa}`quote-left`{ref}`Find out more here.` +# 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: diff --git a/book/features/visuals.md b/book/features/visuals.md index 3ae37b8..249de89 100644 --- a/book/features/visuals.md +++ b/book/features/visuals.md @@ -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. \ No newline at end of file diff --git a/book/installation-and-setup/anaconda.md b/book/installation-and-setup/anaconda.md index 502ffe9..967a376 100644 --- a/book/installation-and-setup/anaconda.md +++ b/book/installation-and-setup/anaconda.md @@ -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! diff --git a/book/installation-and-setup/collab.md b/book/installation-and-setup/collab.md index 201c1c9..f63cba5 100644 --- a/book/installation-and-setup/collab.md +++ b/book/installation-and-setup/collab.md @@ -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. diff --git a/book/installation-and-setup/git-setup_local.md b/book/installation-and-setup/git-setup_local.md index b765577..b2d7e62 100644 --- a/book/installation-and-setup/git-setup_local.md +++ b/book/installation-and-setup/git-setup_local.md @@ -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. diff --git a/book/installation-and-setup/git.md b/book/installation-and-setup/git.md index 4434739..90489d5 100644 --- a/book/installation-and-setup/git.md +++ b/book/installation-and-setup/git.md @@ -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? diff --git a/book/installation-and-setup/git_bash_conda_vs-code.md b/book/installation-and-setup/git_bash_conda_vs-code.md index b11dd01..fb00ae9 100644 --- a/book/installation-and-setup/git_bash_conda_vs-code.md +++ b/book/installation-and-setup/git_bash_conda_vs-code.md @@ -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: diff --git a/book/installation-and-setup/jupyter-book-setup.md b/book/installation-and-setup/jupyter-book-setup.md index a947a77..066c6d8 100644 --- a/book/installation-and-setup/jupyter-book-setup.md +++ b/book/installation-and-setup/jupyter-book-setup.md @@ -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 Jupyter book 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. diff --git a/book/installation-and-setup/overview.md b/book/installation-and-setup/overview.md index eb209c9..48e90c2 100644 --- a/book/installation-and-setup/overview.md +++ b/book/installation-and-setup/overview.md @@ -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! diff --git a/book/installation-and-setup/tools.md b/book/installation-and-setup/tools.md index 1314325..a58e536 100644 --- a/book/installation-and-setup/tools.md +++ b/book/installation-and-setup/tools.md @@ -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). diff --git a/book/installation-and-setup/versioning.md b/book/installation-and-setup/versioning.md index e265115..a2597ea 100644 --- a/book/installation-and-setup/versioning.md +++ b/book/installation-and-setup/versioning.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. diff --git a/book/installation-and-setup/vscode-setup.md b/book/installation-and-setup/vscode-setup.md index a2e76d7..089633e 100644 --- a/book/installation-and-setup/vscode-setup.md +++ b/book/installation-and-setup/vscode-setup.md @@ -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. diff --git a/book/tools/figmaker.md b/book/tools/figmaker.md index 534a57d..9e9be86 100644 --- a/book/tools/figmaker.md +++ b/book/tools/figmaker.md @@ -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: diff --git a/book/workflows/collaboration.md b/book/workflows/collaboration.md index 1453a39..02cd9f0 100644 --- a/book/workflows/collaboration.md +++ b/book/workflows/collaboration.md @@ -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.