diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index a086873..7eb347c 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -8,6 +8,7 @@ variables: REGISTRY_HOST: localhost:5000 TAG_LATEST: $REGISTRY_HOST/$CI_PROJECT_NAME/$CI_COMMIT_REF_NAME:latest TAG_DRAFT: $REGISTRY_HOST/$CI_PROJECT_NAME-draft/$CI_COMMIT_REF_NAME:latest + GIT_SUBMODULE_STRATEGY: recursive # For submodules cache: paths: @@ -72,4 +73,4 @@ deploy-draft: - docker run -d --restart always -p 8018:8000 --name $CI_PROJECT_NAME-draft $TAG_DRAFT environment: name: draft - url: https://interactivetextbooks.citg.tudelft.nl/jupyter-book-manual-draft \ No newline at end of file + url: https://interactivetextbooks.citg.tudelft.nl/jupyter-book-manual-draft diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..d1f5f7a --- /dev/null +++ b/.gitmodules @@ -0,0 +1,9 @@ +[submodule "book/external/Nested-Books"] + path = book/external/Nested-Books + url = https://github.com/TeachBooks/Nested-Books.git +[submodule "book/external/template"] + path = book/external/template + url = https://github.com/TeachBooks/template.git +[submodule "book/external/deploy-book-workflow"] + path = book/external/deploy-book-workflow + url = https://github.com/TeachBooks/deploy-book-workflow.git diff --git a/book/_config.yml b/book/_config.yml index 6a3e5a7..4322295 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -1,12 +1,18 @@ -title: Intro to Git, VS Code and Jupyter Books -author: Caspar Jungbacker -logo: images/TUDelft_logo_rgb.png +title: TeachBooks Manual +author: TeachBooks Team, built with Jupyter Book, CC BY 4.0 + +logo: images/Logo_without_background.png execute: execute_notebooks: 'off' -launch_buttons: - thebe: true +html: + favicon : "images/favicon.ico" + baseurl : "https://teachbooks.tudelft.nl/jupyter-book-manual/" +# START DRAFT + comments: + hypothesis: true +# END DRAFT sphinx: extra_extensions: @@ -21,4 +27,11 @@ sphinx: - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js thebe_config: use_thebe_lite: true - exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"] \ No newline at end of file + exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"] + html_theme_options: + repository_url: "https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual" + use_repository_button: true + use_issues_button : true + launch_buttons: + thebe: true + html_show_copyright: false \ No newline at end of file diff --git a/book/_toc.yml b/book/_toc.yml index 6991f20..7589782 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -6,6 +6,7 @@ parts: chapters: - file: installation-and-setup/user_types - file: installation-and-setup/git + - file: installation-and-setup/choose_platforms.md - file: installation-and-setup/overview sections: - file: installation-and-setup/vscode-setup @@ -13,7 +14,7 @@ parts: - file: installation-and-setup/anaconda - file: installation-and-setup/git_bash_conda_vs-code.md - file: installation-and-setup/jupyter-book-setup - - file: workflows/githubtemplate + - file: external/template/README.md - file: workflows/collaboration sections: - file: workflows/milestones_issues @@ -27,12 +28,15 @@ parts: - file: basic-features/overview sections: - file: basic-features/recipes.md - - file: installation-and-setup/extension + - file: basic-features/hypothesis + - file: basic-features/utterances - file: features/overview sections: + - file: external/deploy-book-workflow/README.md - file: features/remove_from_publish - file: features/custom_toc.md - file: features/custom_download.md + - file: external/Nested-Books/README.md - file: features/interactive_element.ipynb sections: - file: features/grasple.md diff --git a/book/basic-features/hypothesis.md b/book/basic-features/hypothesis.md new file mode 100644 index 0000000..b438ae3 --- /dev/null +++ b/book/basic-features/hypothesis.md @@ -0,0 +1,50 @@ +# 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. + +```{admonition} Be careful of changing website URL's! +:class: warning + +Annotations created using the Hypothesis feature are linked to the specific URL of a website, so keep this in mind if you move a book, or change the file name, as you could lose track of your work! Note that while changing the URL may make a page invisible, you can still find the annotations using the _View group activity_ feature. + +For example, if there is no annotation visible on this page, the URL probably changed! +``` + +## Set up Hypothesis in your book +Add this to `_config.yml`. Need to create an account. + +``` +html: + comments: + hypothesis: true +``` +## Using Hypothesis + +In this case it is easier to learn by doing! Hypothesis has been enabled for this book, but only in the _draft_ version. + +````{admonition} How to View the Draft Site +:class: tip, dropdown +You can access the draft version by adding `draft/` at the end of the main book (but before the current page). For example: + +``` +https://teachbooks.tudelft.nl/jupyter-book-manual/draft/basic-features/hypothesis.html +``` + +You can find out more about the draft and publish feature on {ref}`this page `. +```` + +Once on the draft version of this page, look at the top right corner: you will see three icons, an arrow, an eye and a note-pad. Clicking on the arrow will open the extension and allow you to view the annotations. Create an account and log in if you would like to reply or make your own annotations. You can also highlight text, but this is not publicly visible, it is only for your own reference. + +Note that the annotations are only visible for the page that you are currently viewing. You can see all the Annotations on a website by opening the "Public" menu at the top of the dialog pane, selecting "Public" again in the drop-down, then "View group activity." Make sure you type in the URL to search (e.g., `teachbooks.tudelft.nl/jupyter-book-manual`). + +```{admonition} Tips +:class: tip + +- use the {ref}`remove_from_publish` feature to enable Hypothesis in the draft book only +``` + +## Student-controller with browser extension +As an alternative to activating this for everyone, you can also advise your students to use the [hypothesis browser extension](https://web.hypothes.is/start/). In this way, students are not distracted by potential unnecessary public annotation and comments by fellow students and teachers. + +% THIS IS ADDED TO PAGE AS ANNOTATION: +% This is an example Annotation. Note that annotations are publicly visible, but you must create an account and be logged in to reply or make your own. You can make highlights, but they are only visible to you, not everyone. You can also see all the Annotations on a website by opening the "Public" menu at the top of this dialog pane, selecting "Public" again in the drop-down, then "View group activity." Make sure you type in the URL to search (e.g., `teachbooks.tudelft.nl/jupyter-book-manual`). diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md index 7f650d4..5fa3b30 100644 --- a/book/basic-features/overview.md +++ b/book/basic-features/overview.md @@ -7,7 +7,7 @@ This section is useful for user type 3-6. ```{warning} Under Construction! -This page will provide a list of some commonly used book features which are all available in the original jupyter book package. However, this page includes best-practises on how to use them. +This page will provide a list of some commonly used book features which are all available in the original Jupyter book package. However, this page includes best-practises on how to use them. ``` Things to include somewhere: diff --git a/book/basic-features/utterances.md b/book/basic-features/utterances.md new file mode 100644 index 0000000..aba227a --- /dev/null +++ b/book/basic-features/utterances.md @@ -0,0 +1,25 @@ +# 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). + +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 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`. + +Users need to have a GitHub-account to post a message. Although this might be a burden, it allows students to track their previous posts and set up notifications on follow-up posts. + +If you'd like notifications on new posts in your book, which end up as issues in your GitHub repository, you can configure the GitHub `watch` settings to do so as [explained here](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository). + +Below you see an example of this feature! + +## Example discussion + \ No newline at end of file diff --git a/book/external/Nested-Books b/book/external/Nested-Books new file mode 160000 index 0000000..324e657 --- /dev/null +++ b/book/external/Nested-Books @@ -0,0 +1 @@ +Subproject commit 324e657ae2261761677e4b0c72256e1e85685ad2 diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow new file mode 160000 index 0000000..32e1eb8 --- /dev/null +++ b/book/external/deploy-book-workflow @@ -0,0 +1 @@ +Subproject commit 32e1eb8725fe4c63612a13f7467491cc9765d95e diff --git a/book/external/template b/book/external/template new file mode 160000 index 0000000..1f74f5f --- /dev/null +++ b/book/external/template @@ -0,0 +1 @@ +Subproject commit 1f74f5f2cf71a282e29b9a96a61bb8a140b9c6ab diff --git a/book/features/HTML_javascript.md b/book/features/HTML_javascript.md index d62ed0e..633fcc4 100644 --- a/book/features/HTML_javascript.md +++ b/book/features/HTML_javascript.md @@ -1,5 +1,10 @@ # Interactive HTML/JavaScript elements +```{admonition} User types +:class: tip +This section is useful for user type 5. +``` + 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 c8fcd2d..41f3a9c 100644 --- a/book/features/adding_HTML_elements.md +++ b/book/features/adding_HTML_elements.md @@ -25,7 +25,7 @@ What does this code do? In HTML, certain active parts of the code are defined as Let's take a closer look at the source. Since this project uses a local file structure, we can make use of relative paths such as `../_static/element_render box.html`. What does this path do? In this project, the markdown file for this article is located in the directory `book/features/adding_HTML_elements.md`. The HTML element we want to embed is located in the directory `book/_static/element_render_box.html`. The relative path thus works as follows: - We start in the markdown file's directory `book/features/adding_HTML_elements.md` - - The string `"../"` tells the iframe to move up one folder to `book` + - The string `"../"` tells the iframe to move up one folder to `book`. If you need to move up more subdirectories, use it recursively, eg. `../../` moves up two directories. - The following string `"_static/"` tells the iframe to navigate into the `_static` folder. We are now in `book/_static/`. - Finally, the string `"element_render_box.html"` selects the HTML file we want to embed. We are now in `book/_static/element_render_box.html`. diff --git a/book/features/creating_basic_HTML_elements.md b/book/features/creating_basic_HTML_elements.md index a73fe7e..3d44023 100644 --- a/book/features/creating_basic_HTML_elements.md +++ b/book/features/creating_basic_HTML_elements.md @@ -1,20 +1,7 @@ # Creating basic interactive HTML/JavaScript elements -## Embedding HTML files -A straightforward way to create interactive web-based elements is to code them directly using HTML with JavaScript. This allows us to build elements such as the one below, which shows the connection between a probability density function (pdf) and the associated cumulative density function (cdf): - -If we want to embed such figures in the teachbook, you can do so via an iframe which references a html file in the _static folder: - -```html - -``` - -Here, the src path moves up one subdirectory, then enters the `_static` folder, and loads the `element_pdf_and_cdf.html` file. So how do we create this figure? - -## Creating a basic interactive HTML/JavaScript element - At the bottom of this page, I will provide the full code for the interactive element above. In this section, let us go through the code one piece at a time. Let us begin from the top. In the first line, we specify that this file is a HTML file. In the header (``), we can load packages we need later on. Within the `