diff --git a/book/_toc.yml b/book/_toc.yml index 24db80b..257e1e3 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -26,7 +26,8 @@ parts: - file: installation-and-setup/creating_content.md - caption: Features chapters: - - file: basic-features/overview + - file: features/overview.md + - file: basic-features/overview.md sections: - file: basic-features/jupyterbook.md - file: basic-features/figures.md @@ -37,18 +38,19 @@ parts: - file: basic-features/Code_block_figures - file: basic-features/banner title: Banner or Announcement + - file: basic-features/external-features.md + sections: - file: basic-features/hypothesis.md - file: basic-features/utterances.md - - file: features/overview.md + - file: features/easy-editing.md sections: - file: external/TeachBooks/README.md - file: external/deploy-book-workflow/README.md - file: external/Nested-Books/README.md + - file: features/sphinx_extensions.md + sections: - file: external/Download-Link-Replacer/README.md - - file: external/Sphinx-Image-Inverter/README.md - - file: external/JupyterBook-Patches/README.md - - file: external/Sphinx-TUDelft-theme/README.md - - file: external/teachbooks-sphinx-tippy/README.md + - file: features/custom-launch-button.md - file: features/interactive_element.ipynb sections: - file: external/Sphinx-Grasple-public/README.md @@ -61,6 +63,12 @@ parts: sections: - file: features/widgets.ipynb - file: features/exercise_checking.ipynb + - file: features/visuals.md + sections: + - file: external/Sphinx-Image-Inverter/README.md + - file: external/JupyterBook-Patches/README.md + - file: external/Sphinx-TUDelft-theme/README.md + - file: external/teachbooks-sphinx-tippy/README.md - file: features/students sections: - file: external/annotater/README.md diff --git a/book/basic-features/external-features.md b/book/basic-features/external-features.md new file mode 100644 index 0000000..d574b30 --- /dev/null +++ b/book/basic-features/external-features.md @@ -0,0 +1,8 @@ +# Externally Developed Features + +```{admonition} User types +:class: tip +This section is useful for user type 1-5. +``` + +This chapter includes features useful for books in the educational context, developed by various parties. \ No newline at end of file diff --git a/book/basic-features/hypothesis.md b/book/basic-features/hypothesis.md index a22302c..1d490ce 100644 --- a/book/basic-features/hypothesis.md +++ b/book/basic-features/hypothesis.md @@ -1,5 +1,7 @@ # Making comments on the website: Hypothesis +{bdg-warning}`Javascript overlay` {bdg-success}`Chrome Extension` + Hypothesis is a third-party application that allows anyone to make publicly visible comments on a website (once you create a free account). This section explains how to use and install the extension. As this tool requires an account with a third-party, we advise to use our [local-annotator](../external/annotater/README.md) with similar capabilities but which store annotations locally. By default Hypothesis stores annotations publicly, which might confuse other students. ```{admonition} Be careful of changing website URL's! diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md index e7bdc24..df68f69 100644 --- a/book/basic-features/overview.md +++ b/book/basic-features/overview.md @@ -1,8 +1,8 @@ -# Original Jupyter Book Features +# Original Jupyter Book and Sphinx Features ```{admonition} User types :class: tip This section is useful for [user type 3-5](../installation-and-setup/user_types.md). ``` -These pages will provide a list of some common, basic book features which are all available in the original Jupyter book package. However, this page includes also best-practices. +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 6ce641b..5bd350b 100644 --- a/book/basic-features/utterances.md +++ b/book/basic-features/utterances.md @@ -1,5 +1,7 @@ # Discussions in your book: Utterances +{bdg-white}`GitHub app and Javascript script` + [Utterances 🔮](https://utteranc.es/) is a lightweight open-source widget which allows you, your colleages and your students to discuss stuff in a blog post in your book. It is build on GitHub issues, so requires a GitHub repository, although the book can be hosted anywhere (so also on GitLab). The [utterances website](https://utteranc.es/) clearly explains the required steps. One thing to take care of is how you want to do the issue-mapping with respect to multiple deployed versions (draft version, student version, archived versions): diff --git a/book/external/Download-Link-Replacer b/book/external/Download-Link-Replacer index e220538..66952b5 160000 --- a/book/external/Download-Link-Replacer +++ b/book/external/Download-Link-Replacer @@ -1 +1 @@ -Subproject commit e2205387f4446e736a89d6f5e70e0bddfa955a98 +Subproject commit 66952b5f23af2f0106eb24e56f186d729b5a1ca8 diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches index 8d97cb2..5c129f2 160000 --- a/book/external/JupyterBook-Patches +++ b/book/external/JupyterBook-Patches @@ -1 +1 @@ -Subproject commit 8d97cb21d7d5f67cc19d35768c5e257d36cc0e69 +Subproject commit 5c129f2447bb4b30100c136d94b5bee9e51e2921 diff --git a/book/external/Nested-Books b/book/external/Nested-Books index c0aab87..ced5cde 160000 --- a/book/external/Nested-Books +++ b/book/external/Nested-Books @@ -1 +1 @@ -Subproject commit c0aab87a87c97e2c643c4e905a0065a49d925616 +Subproject commit ced5cdefa1b1b6c4fdba3fc42a94e812db4892f0 diff --git a/book/external/Sphinx-Grasple-public b/book/external/Sphinx-Grasple-public index 4158a9c..c29b4a0 160000 --- a/book/external/Sphinx-Grasple-public +++ b/book/external/Sphinx-Grasple-public @@ -1 +1 @@ -Subproject commit 4158a9c5cc5b299496066fa3fe36b569814c5f2b +Subproject commit c29b4a03351c88fa5cdd09475f99a1b486a0e247 diff --git a/book/external/Sphinx-Image-Inverter b/book/external/Sphinx-Image-Inverter index 95fccf0..c9c9d2f 160000 --- a/book/external/Sphinx-Image-Inverter +++ b/book/external/Sphinx-Image-Inverter @@ -1 +1 @@ -Subproject commit 95fccf09f2c9d42ae473b3ed6033ebcb948792b1 +Subproject commit c9c9d2f6953b5a57ff4763976840ec3bb281dbcf diff --git a/book/external/Sphinx-TUDelft-theme b/book/external/Sphinx-TUDelft-theme index 9356dac..0f47585 160000 --- a/book/external/Sphinx-TUDelft-theme +++ b/book/external/Sphinx-TUDelft-theme @@ -1 +1 @@ -Subproject commit 9356dac16e04935cfa92924856f652d5653e8793 +Subproject commit 0f4758586bebb1db4da0738b66d02d883ff7b54d diff --git a/book/external/TeachBooks b/book/external/TeachBooks index ba87520..eb5f90c 160000 --- a/book/external/TeachBooks +++ b/book/external/TeachBooks @@ -1 +1 @@ -Subproject commit ba8752053a5a4c70d8dacc77e65433f5bfb5a318 +Subproject commit eb5f90c86e6f9dd368c513b2d958f77fb941cae0 diff --git a/book/external/annotater b/book/external/annotater index 22d2efa..7cd38db 160000 --- a/book/external/annotater +++ b/book/external/annotater @@ -1 +1 @@ -Subproject commit 22d2efac5bf175f8173b9accae21e7270c977b03 +Subproject commit 7cd38dbba9ab50eebc5dbba6c61b9cb4f46d3cf0 diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow index 29f9f4a..71dd5f2 160000 --- a/book/external/deploy-book-workflow +++ b/book/external/deploy-book-workflow @@ -1 +1 @@ -Subproject commit 29f9f4a690d0f0af49d04d062bf468de7fecc790 +Subproject commit 71dd5f2f56c8540fa45ce713adf44cab9d85c36e diff --git a/book/external/teachbooks-sphinx-tippy b/book/external/teachbooks-sphinx-tippy index 304a1dc..546f58f 160000 --- a/book/external/teachbooks-sphinx-tippy +++ b/book/external/teachbooks-sphinx-tippy @@ -1 +1 @@ -Subproject commit 304a1dcd6bdf6ce3501eb46d55fcc9216db0d334 +Subproject commit 546f58fe01a556130f06cdc95524efd922362f83 diff --git a/book/features/HTML_javascript.md b/book/features/HTML_javascript.md index 491ce51..f103638 100644 --- a/book/features/HTML_javascript.md +++ b/book/features/HTML_javascript.md @@ -5,6 +5,8 @@ This section is useful for user type 5. ``` +{bdg-danger}`iframe` + In this section, we will discuss how to [create](creating_basic_HTML_elements.md) and [embed](adding_HTML_elements.md) interactive HTML/Javascript elements created in HTML/JavaScript in a TeachBook. These HTML/Javascript element work very fluently and don't require a python kernel running in the background. This could be for example interactive 3d figures: diff --git a/book/features/adding_HTML_elements.md b/book/features/adding_HTML_elements.md index 41f3a9c..b241964 100644 --- a/book/features/adding_HTML_elements.md +++ b/book/features/adding_HTML_elements.md @@ -1,5 +1,7 @@ # Adding interactive HTML/JavaScript elements +{bdg-danger}`iframe` + In this section, we will discuss how to embed interactive elements created in HTML/JavaScript in a TeachBook. If you are interested in learning how to create these elements yourself, we will discuss an example in the [next article](creating_basic_HTML_elements.md). As an example, let us discuss how to embed an interactive 3D model of a subsurface environment I created: diff --git a/book/features/custom-launch-button.md b/book/features/custom-launch-button.md new file mode 100644 index 0000000..8df830b --- /dev/null +++ b/book/features/custom-launch-button.md @@ -0,0 +1,102 @@ +# Multilingual book + +```{admonition} User types +:class: tip +This page is useful for user type 4 and 5. +``` +{bdg-primary}`Sphinx Extension` + +The custom launch button extension allows you to create a customizable button in the top right of your jupyter book. +This may have many applications, one of them being that you can create different language versions of the book available for the user. + +This section will explain how to create a "Languages" or " + + " button, like you might be used to seeing on just about any website. The use of the button, however, is completey customizable and may be used in many different ways. + +## Installation + +1. Install the Sphinx Launch Buttons extension from the GitHub repository. Paste the following line, in your terminal. Make sure you activated your book building environment. + +``` +pip install git+https://github.com/TeachBooks/Sphinx-launch-buttons.git +``` + +2. To use the extension in your book, you need to include it in your `_config.yml` file. + +``` +sphinx: + extra_extensions: + - custom-launch-buttons +``` + +3. Then you need to include a `_launch_buttons.yml` file in the same location as your `_config.yml` file. The following code cell shows the main structure of that file. + +``` +buttons: + - type : dropdown + + - type : button +``` + +Here, `buttons` is an array of launch buttons, each can be identified using 2 types: 'dropdown' or 'button'. The cell above shows 2 buttons, one of type `dropdown` and one of type `button`. + +The button/dropdown can be visualised using either an [svg icon](https://icons.getbootstrap.com/#icons) or text. + +``` +buttons: + - type : dropdown + label: Language + - type : button + icon : ... + +``` +4. Lastly you need to specifiy the items of your button. So assuming you want to have different language versions, each item will be one of the languages. + +``` +buttons: + - type : dropdown + label: Language + + - type : button + icon : ... + + items: + - label: English + url: url of branch + - label: Nederlands + url: url of branch +``` +As you can see in the `items:` line, each dropdown option links to the branch of the repository in the respective language. + +## Setting up your repository + +For the implementation to your book, it is handy to create a branch for each language version you want to offer. Make a new branch using for example main as a source. Assuming we want to create a dutch version of you can call this branch `Dutch` or `Nederlands`. + +You will then need to translate the content in the dutch branch to dutch which can take some time. From experience, [DeepL](https://www.deepl.com/en/translator) is a good tool for this but any AI chatbot might be helpful as well. Make sure to proofread the translation. + +You'll need to add (merge) the updated `_config.yml` and the new `_launch_buttons.yml` to all of your branches. + +## Example + +``` +buttons: + - type: dropdown + icon: + + + items: + - label: English + url: https://teachbooks.github.io/files-and-folders/EN + - label: Nederlands + url: https://teachbooks.github.io/files-and-folders/NL +``` + +The code in the above cell is the `_launch_buttons.yml` file of a repository called "files-and-folders". The buttons created look like this: + +```{figure} figures/language_button.PNG +--- +width: 50% +name:language_button +--- +Custom Button +``` diff --git a/book/features/easy-editing.md b/book/features/easy-editing.md new file mode 100644 index 0000000..418f55b --- /dev/null +++ b/book/features/easy-editing.md @@ -0,0 +1,8 @@ +# Easy Editing Process + +```{admonition} User types +:class: tip +This section is useful for user type 3-5. +``` + +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/figures/language_button.PNG b/book/features/figures/language_button.PNG new file mode 100644 index 0000000..9330422 Binary files /dev/null and b/book/features/figures/language_button.PNG differ diff --git a/book/features/h5p.md b/book/features/h5p.md index 853b822..cdb10c7 100644 --- a/book/features/h5p.md +++ b/book/features/h5p.md @@ -5,6 +5,8 @@ This section is useful for user type 3-5. ``` +{bdg-danger}`iframe` + ## 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: diff --git a/book/features/interactive_element.ipynb b/book/features/interactive_element.ipynb index 75bd000..f5fecce 100644 --- a/book/features/interactive_element.ipynb +++ b/book/features/interactive_element.ipynb @@ -9,7 +9,7 @@ "source": [ "# Interactive content: Elements not including Python\n", "\n", - "To add interactivity to the book, you can make use of interactive elements which are embedded in the book. You've four options:\n", + "To add interactivity to the book, you can make use of interactive elements which are embedded in the book. You've a few options:\n", "\n", " - Admonition: question provided in normal markdown language with answers in a drowdown menu. There's no feedback delivered to the student, only the correct answer no matter what the student's thinking/work.\n", " - JupyterQuiz: 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.\n", diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb index d553b43..a923219 100644 --- a/book/features/live_code.ipynb +++ b/book/features/live_code.ipynb @@ -11,6 +11,8 @@ "This section is useful for user type 5.\n", "```\n", "\n", + "{bdg-primary}`Sphinx Extension`\n", + "\n", "Our book has been enable to run Python code live in the browser (thanks Max!). This extension makes code cells in your `.ipynb` book pages editable and executable by the reader! Opposed to the original sphinx-thebe extensions, our extension runs python in the reader's browser and doesn't rely on an external webserver for the python kernel. We highly recommend this extension as it allows you to use the strength of combining text/figures and code of a jupyter book with interactivity!\n", "\n", "This page contains some installation instructions and the other sections show how to use this functionality to create interactive figures and feedback on code\n", diff --git a/book/features/overview.md b/book/features/overview.md index a9a4bc4..30d40b8 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -1,12 +1,19 @@ -# TeachBooks Authoring Features +# Overview As TeachBooks, we collect a suite of existing open-source software and keep our books up-to-date so you don't have to! Some of the software is developed with our TA's to improve the learning experience of our students and ease the book-development process for our teachers. By deploying these tools from a central location we can prevent common problems before they arise, and fix them quickly when they do occur. As the open-source software landscape changes rapidly, it is essential to keep in contact and share resources amongst ourselves to minimize maintenance and downtime for our book websites and focus on what really matters: teaching! -This chapter provides a list of commonly used book features together with sub-pages that provide additional information on: -- the purpose -- how to install them -- how to use them -- where to find the source code +Since the list of TeachBook features is getting quite long, we have grouped them in categories: -To see examples for these features, go to the [Examples chapter](../examples/overview.md). +Additionally, not all features are built using the same type of sourcecode. For transparency, tags will help differentiate between the different backgrounds of the features: +- {bdg-warning}`Javascript overlay` +- {bdg-success}`Chrome Extension` +- {bdg-white}`GitHub App and Javascript script` +- {bdg-secondary}`Python Package` +- {bdg-light}`GitHub Reusable Action` +- {bdg-dark}`Git Workflow` +- {bdg-primary}`Sphinx Extension` +- {bdg-danger}`iframe` +Finally, the purpose, installation process and usage of each features is elaborated on in the respective sub-sections. + +To see examples for these features, go to the [Examples chapter](../examples/overview.md). \ No newline at end of file diff --git a/book/features/sphinx_extensions.md b/book/features/sphinx_extensions.md new file mode 100644 index 0000000..fa53945 --- /dev/null +++ b/book/features/sphinx_extensions.md @@ -0,0 +1,8 @@ +# Additional functionality + +```{admonition} User types +:class: tip +This section is useful for user type 4-5. +``` + +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 a9a1abf..46a6993 100644 --- a/book/features/students.md +++ b/book/features/students.md @@ -1,3 +1,8 @@ # 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. +```{admonition} User types +:class: tip +This section is useful for user type 1-5. +``` + +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/visuals.md b/book/features/visuals.md new file mode 100644 index 0000000..3ae37b8 --- /dev/null +++ b/book/features/visuals.md @@ -0,0 +1,8 @@ +# Book styling + +```{admonition} User types +:class: tip +This section is useful for user type 1-5. +``` + +TeachBooks developed a few improvements of the book which improve the visual book styling. \ No newline at end of file