From f0bd518db54c297cc55445b39da9f983c5889884 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sun, 9 Mar 2025 22:45:45 +0000 Subject: [PATCH 01/41] Bump jupyterbook-patches from 1.3.0 to 1.4.1 Bumps [jupyterbook-patches](https://github.com/TeachBooks/JupyterBook-Patches) from 1.3.0 to 1.4.1. - [Release notes](https://github.com/TeachBooks/JupyterBook-Patches/releases) - [Commits](https://github.com/TeachBooks/JupyterBook-Patches/compare/v1.3.0...v1.4.1) --- updated-dependencies: - dependency-name: jupyterbook-patches dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 1d686bb..8c1505e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,6 @@ teachbooks == 0.1.0 sphinx-inline-tabs == 2023.4.21 -jupyterbook_patches==1.3.0 +jupyterbook_patches==1.4.1 download_link_replacer == 1.0.4 teachbooks-sphinx-grasple == 1.0.5 sphinx-image-inverter == 1.1.2 From 682f6a9aefa3615e510b05d2fcfb630a59040f71 Mon Sep 17 00:00:00 2001 From: Sander Renes Date: Tue, 11 Mar 2025 12:05:16 +0100 Subject: [PATCH 02/41] Update licenses.md changed a typo and added a sentence on copyleft licences --- book/installation-and-setup/copyright/licenses.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/book/installation-and-setup/copyright/licenses.md b/book/installation-and-setup/copyright/licenses.md index b29aeb7..40fb5d7 100644 --- a/book/installation-and-setup/copyright/licenses.md +++ b/book/installation-and-setup/copyright/licenses.md @@ -72,11 +72,12 @@ The "ND" license prohibits derivative works: in other words, the material cannot The "NC" license prohibits commercial use. It sounds nice, right? > Great, I can guarantee that big for-profit companies can't use my work for their own gain. This is important to me at a public or non-profit institution. -To be honest, it is more trouble than it's worth, primarily because the law seems to be vague on what constitutes commercial use. Many universities require tuition to cover operating expenses, which is often broken down into by nubmer of students, credits, courses, etc. This could be interpreted as a form of commercial use and thus prevent other educators from using your work, which is precisely the opposite of what you were trying to facilitate! +To be honest, it is more trouble than it's worth, primarily because the law seems to be vague on what constitutes commercial use. Many universities require tuition to cover operating expenses, which is often broken down into by number of students, credits, courses, etc. This could be interpreted as a form of commercial use and thus prevent other educators from using your work, which is precisely the opposite of what you were trying to facilitate! ### Why is SA not preferred? The "SA" license requires that any derivative works be released under the same license. If you have two sources, each of which has a different SA license, how can you include your work that incorporates that content under the same license? You can't! Once again, if your goal is to convince others to share your work in a responsible way, your effort is thwarted. As with NC, this type of license seems to be more trouble than it's worth. +A similar story holds for the other 'copyleft' lincenses, as all copyleft licences require that the original license is perserved in derivative work to some degree. ### Summary of License Type Compatibility @@ -104,4 +105,4 @@ What if your _content_ includes code. This happens in many science and engineeri For example, the [MUDE Team](https://mude.citg.tudelft.nl) is working towards releasing the files associated with assignments under an open license. Since the majority of the content is written in a storytelling style in Jupyter notebooks, a CC BY license is probably the best choice if only one license is applied to a single file. However, if released in bulk it may be better to follow the advice of [Matt Hall](https://agilescientific.com/blog/2021/2/17/which-open-licence-should-i-choose): -> You have to be practical; maybe it depends on whether you consider your notebooks to be 'content' or 'source code'. I sometimes put at the bottom of a notebook something like **Open source content. Text is CC-BY, code is Apache 2.0** and I think this makes my intent clear. \ No newline at end of file +> You have to be practical; maybe it depends on whether you consider your notebooks to be 'content' or 'source code'. I sometimes put at the bottom of a notebook something like **Open source content. Text is CC-BY, code is Apache 2.0** and I think this makes my intent clear. From f2deda3f88ca6d19e63f57180581c5921576d5f5 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 12 Mar 2025 08:13:28 +0100 Subject: [PATCH 03/41] moved examples h5p to explanation itself --- book/_toc.yml | 3 ++- book/examples/h5p_examples.md | 38 +++++++++++++++++++---------------- book/features/h5p.md | 22 +++++++++----------- 3 files changed, 32 insertions(+), 31 deletions(-) diff --git a/book/_toc.yml b/book/_toc.yml index 0219d36..f87daa6 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -74,6 +74,8 @@ parts: - file: basic-features/utterances.md - file: features/jupyterquiz.ipynb - file: features/h5p.md + sections: + - file: examples/h5p_examples.md - file: features/plotly.ipynb - file: external/Sphinx-Grasple-public/README.md - file: features/HTML_javascript.md @@ -103,7 +105,6 @@ parts: chapters: - file: examples/overview.md - file: examples/book_structure.md - - file: examples/h5p_examples.md - file: examples/live_code.md - file: examples/example_gumbel.ipynb - file: examples/theory_questions.md diff --git a/book/examples/h5p_examples.md b/book/examples/h5p_examples.md index 2fb9df5..4c08839 100644 --- a/book/examples/h5p_examples.md +++ b/book/examples/h5p_examples.md @@ -1,14 +1,4 @@ -# Types of H5p Quizzes - -This page will show some examples of H5p quizzes built into a variety of TeachBooks to allow the students to test their understanding of the content as they read. H5p quizzes can be used to create a set of Multiple Choice, Drag and Drop, Fill in the blanks, True/False and Image choice questions so the applications are quite versitile and your imagination can be used in creating the questions. - -## Getting started with H5p - -Some best-practices on the use of H5p: - - To startup your H5p-account, first login to H5p via Brightspace. You can follow instructions as under [https://www.tudelft.nl/teaching-support/educational-tools/h5p](https://www.tudelft.nl/teaching-support/educational-tools/h5p). - - After that, direct login is possible via [tudelft.h5p.com](https://tudelft.h5p.com) - - Place your H5p-elements in a shared folder in H5p. - - Disable the display options "Toolbar Below Content" and "Display author's name to public (anonymous users) (only relevant when content's status is set to Public )" for each +# Examples of H5p Quizzes ## Dialog cards @@ -48,7 +38,8 @@ Dialoge Card **Try it out!** - +```{h5p} https://tudelft.h5p.com/content/1292050206829217497/embed +``` ## Question Set @@ -96,7 +87,8 @@ Tips Have a look at the following 7 questions. - +```{h5p} https://tudelft.h5p.com/content/1292062157562749767/embed +``` ## Complex fill in the blanks @@ -125,7 +117,7 @@ Wrong Answer + Feedback **MUDE - Optimization** -Since the cells can be used to evaluate numerical answers, they are an easy way to quiz the student on matrices and evaluate the result of each position indidependently. The optimization team of MUDE took this a step further and used this set-up to quiz the students on the SIMPLEX method. This method automates the solving of the augmented form of a linear programing problem with continuous variables. It makes use of tables and the manipulation of equations to find the optimal vaues. Unfortunately, with a large number of variables this tables tend to get quite big and filling in the cells becomes laborous. +Since the cells can be used to evaluate numerical answers, they are an easy way to quiz the student on matrices and evaluate the result of each position independently. The optimization team of MUDE took this a step further and used this set-up to quiz the students on the SIMPLEX method. This method automates the solving of the augmented form of a linear programming problem with continuous variables. It makes use of tables and the manipulation of equations to find the optimal values. Unfortunately, with a large number of variables this tables tend to get quite big and filling in the cells becomes laborious. ```{figure} figures/blanks3.PNG --- @@ -134,9 +126,20 @@ align: center --- SIMPLEX Method ``` -**Try it out!** +**Truss structure** - +Truss structures are modelled as rigid bars (so elements which cannot deform) connected by hinges (so elements can rotate with respect to one each other). In our model, hinges are indicate with a circle, and bars with a line. For example, the structure you've seen in the second example (with two diagonal bars removed) is modelled as follows: + +```{figure} ../images/Truss1.svg +:name: truss structure + +Bars and hinges in truss structure +``` + +Now that you've been introduced to truss structures, answer the following question: + +```{h5p} https://tudelft.h5p.com/content/1291910926067816717/embed +``` ## True or False @@ -165,7 +168,8 @@ The small circles below the question indicates that there are more questions in **Try it out!** - +```{h5p} https://tudelft.h5p.com/content/1292061623388939257/embed +``` ## Drag and Drop diff --git a/book/features/h5p.md b/book/features/h5p.md index bf244c0..fab49f2 100644 --- a/book/features/h5p.md +++ b/book/features/h5p.md @@ -27,18 +27,14 @@ A full list of all available interactive elements is available on the website of - Interactive video - Image hotspot -More information on H5p: [Teaching Support - Educational Tools - H5P](https://www.tudelft.nl/teaching-support/educational-tools/h5p) +Some best-practices on the use of H5p: +- H5p requires its own hosting. TU Delft provides this for TU Delft employees. +- To startup your H5p-account, first login to H5p via Brightspace. You can follow instructions as under [https://www.tudelft.nl/teaching-support/educational-tools/h5p](https://www.tudelft.nl/teaching-support/educational-tools/h5p). +- After that, direct login is possible via [tudelft.h5p.com](https://tudelft.h5p.com) +- Place your H5p-elements in a shared folder in H5p. +- Disable the display options "Toolbar Below Content" and "Display author's name to public (anonymous users) (only relevant when content's status is set to Public )" for each element for a smooth experience. On the other hand, the options 'Toolbar below content' in combination with 'Allow users to download content' allow people to reuse your questions, making them more open. +- Use it in combination with [](../external/sphinx-iframes/README.md) to allow for a proper dark mode, dynamic scaling and a transparent background. -## Example -Truss structures are modelled as rigid bars (so elements which cannot deform) connected by hinges (so elements can rotate with respect to one each other). In our model, hinges are indicate with a circle, and bars with a line. For example, the structure you've seen in the second example (with two diagonal bars removed) is modelled as follows: +In the next subpage, these exampled are shown. -```{figure} ../images/Truss1.svg -:name: truss structure - -Bars and hinges in truss structure -``` - -Now that you've been introduced to truss structures, answer the following question: - -```{h5p} https://tudelft.h5p.com/content/1291910926067816717/embed -``` \ No newline at end of file +More information on H5p using the TU Delft provided hosting: [Teaching Support - Educational Tools - H5P](https://www.tudelft.nl/teaching-support/educational-tools/h5p) \ No newline at end of file From 9ff4e4f03fd6c21ccb3f06e21d8e8af0fb798707 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 12 Mar 2025 08:34:01 +0100 Subject: [PATCH 04/41] update --- book/_static/power.html | 178 ++++++++++++++++++++++++++++++++++ book/examples/h5p_examples.md | 70 ++++--------- 2 files changed, 195 insertions(+), 53 deletions(-) create mode 100644 book/_static/power.html diff --git a/book/_static/power.html b/book/_static/power.html new file mode 100644 index 0000000..69524a9 --- /dev/null +++ b/book/_static/power.html @@ -0,0 +1,178 @@ + + + + CO2 vs Power + + + + + +
+
+ + + + diff --git a/book/examples/h5p_examples.md b/book/examples/h5p_examples.md index 4c08839..cac42d0 100644 --- a/book/examples/h5p_examples.md +++ b/book/examples/h5p_examples.md @@ -18,29 +18,18 @@ Problem Statement As can be seen on the right-hand-side menu, the sub-chapter includes the problem statement, the elaboration on the model and solution method and finally an exercise for the student. The code in the page is activated by pressing the live code button which will make the code cells editable and executable. Additionally, interactive figures are included into the text with movable sliders to directly see the effect of the changes made. -```{figure} figures/Live_code2.PNG ---- -width: 600 -align: center ---- -Interactive Graph +```{iframe} ../_static/power.html ``` The H5p quizzes can shine in the section on questions, discussions and comments. Next to many multiple choice questions (which are discussed later) there are dialog cards which can ask more conceptual and open ended questions. Pressing on the blue button `Turn` will flip around the card and reveal the model answer. The great thing about the integration of both interactive aspects (coding and questions) helps the student to play around with the code and understand the topic from a less theoretical point-of-view. -```{figure} figures/cards1.PNG ---- -width: 700 -align: center ---- -Dialoge Card +```{h5p} https://tudelft.h5p.com/content/1292260184374358717/embed ``` -**Try it out!** - -```{h5p} https://tudelft.h5p.com/content/1292050206829217497/embed +```{h5p} https://tudelft.h5p.com/content/1292260188487459217/embed ``` + ## Question Set Question sets consist of a question and one or more possible answers to that question. @@ -49,20 +38,10 @@ Question sets consist of a question and one or more possible answers to that que The following question sets are taken from chapter 3.3. Weighted least-squares estimation of the MUDE 23/24 book. The chapter builds on the previous chapter on simple least-squares estimation and dwelves into the importance and properties of the weight matrix. The student is primarily quizzed using multiple choice questions to check their understanding. The answers can be provided in the shape of text, figures, equations, matrices and probably much more. -```{figure} figures/Question_set_1.PNG ---- -width: 600 -align: center ---- -Text Answers +```{h5p} https://tudelft.h5p.com/content/1292060781042105617/embed ``` -```{figure} figures/Question_set_2.PNG ---- -width: 600 -align: center ---- -Equations Answers +```{h5p} https://tudelft.h5p.com/content/1292046737060674407/embed ``` Since these questions are meant to develop the understanding of the students, feedback is vital! Feedback can be built into the questions to explain the reasoning behind a correct answer. @@ -98,12 +77,7 @@ The complex fill in the blanks can be used to evaluate numerical answers. Chapter 3.7. Non-linear least-squares estimation from the MUDE 23/24 book makes use of the complex fill in the blanks quiz in order to check that the students understood the composition of the Jacobian Matrix specifically used in deriving the linearized functional model. This model is essential for accurately estimating values and assessing system behavior of complex processes that arent linear. -```{figure} figures/blanks1.PNG ---- -width: 600 -align: center ---- -Answer Boxes +```{h5p} https://tudelft.h5p.com/content/1292064774866067777/embed ``` As you can see, the precision of the answer sought for is specified and the figure below shows again the incorporation of feedback. @@ -119,12 +93,7 @@ Wrong Answer + Feedback Since the cells can be used to evaluate numerical answers, they are an easy way to quiz the student on matrices and evaluate the result of each position independently. The optimization team of MUDE took this a step further and used this set-up to quiz the students on the SIMPLEX method. This method automates the solving of the augmented form of a linear programming problem with continuous variables. It makes use of tables and the manipulation of equations to find the optimal values. Unfortunately, with a large number of variables this tables tend to get quite big and filling in the cells becomes laborious. -```{figure} figures/blanks3.PNG ---- -width: 600 -align: center ---- -SIMPLEX Method +```{h5p} https://tudelft.h5p.com/content/1292131432784432037/embed ``` **Truss structure** @@ -157,14 +126,10 @@ align: center Problem Statement ``` -```{figure} figures/truefalse1.PNG ---- -width: 600 -align: center ---- -True or False +The small circles below the question indicates that there are more questions in this series which can be viewed by clicking on the blue arrow pointing towards the left or right. Open the second, fourth and fifth question: + +```{h5p} https://tudelft.h5p.com/content/1292120485436114287/embed ``` -The small circles below the question indicates that there are more questions in this series which can be viewed by clicking on the blue arrow pointing towards the left or right. **Try it out!** @@ -177,16 +142,15 @@ Drag and Drop questions are useful to make the distinction between different con **MUDE - Optimization** -In this chapter, it was important that the students made the distinction between the terminology and mathematical meaning between different elements of the graphical solution method. A drag and drop question was used to link the term to its definition. The answer boxes can be dragged to the correct title in a playful manner.jup +In this chapter, it was important that the students made the distinction between the terminology and mathematical meaning between different elements of the graphical solution method. A drag and drop question was used to link the term to its definition. The answer boxes can be dragged to the correct title in a playful manner. -```{figure} figures/drag1.PNG ---- -width: 600 -align: center ---- -Drag and Drop +The fourth question in this question set is a drag and drop question: + +```{h5p} https://tudelft.h5p.com/content/1292121213033110307/embed ``` +The correct answer leads to: + ```{figure} figures/drag2.PNG --- width: 600 From de6e00b1514c4ae5fd9e7a15e7badca7396454ec Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 12 Mar 2025 08:35:29 +0100 Subject: [PATCH 05/41] Update example_gumbel.ipynb --- book/examples/example_gumbel.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/examples/example_gumbel.ipynb b/book/examples/example_gumbel.ipynb index b366c19..3bf3019 100644 --- a/book/examples/example_gumbel.ipynb +++ b/book/examples/example_gumbel.ipynb @@ -6,7 +6,7 @@ "tags": [] }, "source": [ - "# Programming assignment\n", + "# Programming assignment with checks\n", "\n", "This page shows how you can recreate the classical Jupyter Notebook assignments that are given in many courses to a Jupyter Book format with live coding. A widget has been implemented to check the answers, of which the data is included in a separate python file. The page automatically loads and a custom download page has been added\n", "\n", From 9847050bd6854ed60a84649afe70a74c35a5f325 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 12 Mar 2025 08:51:14 +0100 Subject: [PATCH 06/41] Update h5p_examples.md --- book/examples/h5p_examples.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/book/examples/h5p_examples.md b/book/examples/h5p_examples.md index cac42d0..763cd81 100644 --- a/book/examples/h5p_examples.md +++ b/book/examples/h5p_examples.md @@ -19,6 +19,8 @@ Problem Statement As can be seen on the right-hand-side menu, the sub-chapter includes the problem statement, the elaboration on the model and solution method and finally an exercise for the student. The code in the page is activated by pressing the live code button which will make the code cells editable and executable. Additionally, interactive figures are included into the text with movable sliders to directly see the effect of the changes made. ```{iframe} ../_static/power.html +:height: 580 +:width: 100% ``` The H5p quizzes can shine in the section on questions, discussions and comments. Next to many multiple choice questions (which are discussed later) there are dialog cards which can ask more conceptual and open ended questions. Pressing on the blue button `Turn` will flip around the card and reveal the model answer. The great thing about the integration of both interactive aspects (coding and questions) helps the student to play around with the code and understand the topic from a less theoretical point-of-view. From 9e34a2e08cde625d4e039d6d7e2636d8b6142880 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Wed, 12 Mar 2025 08:56:38 +0100 Subject: [PATCH 07/41] set height --- book/examples/h5p_examples.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/examples/h5p_examples.md b/book/examples/h5p_examples.md index 763cd81..f0dafa3 100644 --- a/book/examples/h5p_examples.md +++ b/book/examples/h5p_examples.md @@ -19,7 +19,7 @@ Problem Statement As can be seen on the right-hand-side menu, the sub-chapter includes the problem statement, the elaboration on the model and solution method and finally an exercise for the student. The code in the page is activated by pressing the live code button which will make the code cells editable and executable. Additionally, interactive figures are included into the text with movable sliders to directly see the effect of the changes made. ```{iframe} ../_static/power.html -:height: 580 +:height: 580px :width: 100% ``` From 66ddef3612c9b133e4ccabffbcc446c62cb5dac5 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sun, 16 Mar 2025 22:05:34 +0000 Subject: [PATCH 08/41] Bump sphinx-proof from 0.2.0 to 0.2.1 Bumps [sphinx-proof](https://github.com/executablebooks/sphinx-proof) from 0.2.0 to 0.2.1. - [Release notes](https://github.com/executablebooks/sphinx-proof/releases) - [Changelog](https://github.com/executablebooks/sphinx-proof/blob/main/CHANGELOG.md) - [Commits](https://github.com/executablebooks/sphinx-proof/compare/v0.2.0...v0.2.1) --- updated-dependencies: - dependency-name: sphinx-proof dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 8c1505e..7c8559a 100644 --- a/requirements.txt +++ b/requirements.txt @@ -5,7 +5,7 @@ download_link_replacer == 1.0.4 teachbooks-sphinx-grasple == 1.0.5 sphinx-image-inverter == 1.1.2 sphinx-exercise == 1.0.1 -sphinx-proof == 0.2.0 +sphinx-proof == 0.2.1 sphinx-named-colors == 1.0.1 sphinx-iframes == 1.0.5 sphinx-prime-applets == 1.0.1 From d0d881a9c098df2f2ba03a187c4fe246d69b15fc Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sun, 16 Mar 2025 22:05:36 +0000 Subject: [PATCH 09/41] Bump jupyterbook-patches from 1.4.1 to 1.4.2 Bumps [jupyterbook-patches](https://github.com/TeachBooks/JupyterBook-Patches) from 1.4.1 to 1.4.2. - [Release notes](https://github.com/TeachBooks/JupyterBook-Patches/releases) - [Commits](https://github.com/TeachBooks/JupyterBook-Patches/compare/v1.4.1...v1.4.2) --- updated-dependencies: - dependency-name: jupyterbook-patches dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 8c1505e..f00786d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,6 @@ teachbooks == 0.1.0 sphinx-inline-tabs == 2023.4.21 -jupyterbook_patches==1.4.1 +jupyterbook_patches==1.4.2 download_link_replacer == 1.0.4 teachbooks-sphinx-grasple == 1.0.5 sphinx-image-inverter == 1.1.2 From d4e07ee2332976f55eefde0969ef5faac1a22ea7 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sun, 16 Mar 2025 22:05:39 +0000 Subject: [PATCH 10/41] Bump sphinx-prime-applets from 1.0.1 to 1.0.2 Bumps [sphinx-prime-applets](https://github.com/TeachBooks/Sphinx-PRIME-applets) from 1.0.1 to 1.0.2. - [Release notes](https://github.com/TeachBooks/Sphinx-PRIME-applets/releases) - [Commits](https://github.com/TeachBooks/Sphinx-PRIME-applets/compare/v1.0.1...v1.0.2) --- updated-dependencies: - dependency-name: sphinx-prime-applets dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 8c1505e..98499e3 100644 --- a/requirements.txt +++ b/requirements.txt @@ -8,7 +8,7 @@ sphinx-exercise == 1.0.1 sphinx-proof == 0.2.0 sphinx-named-colors == 1.0.1 sphinx-iframes == 1.0.5 -sphinx-prime-applets == 1.0.1 +sphinx-prime-applets == 1.0.2 git+https://github.com/TeachBooks/Sphinx-Thebe From 2322687660e49fd75c616c7f9df00ea60d62e50f Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Tue, 18 Mar 2025 13:09:55 +0100 Subject: [PATCH 11/41] added user types --- book/_toc.yml | 2 +- book/features/jupyterquiz.ipynb | 7 +++++++ book/features/plotly.ipynb | 5 +++++ 3 files changed, 13 insertions(+), 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index f87daa6..d841379 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -72,7 +72,6 @@ parts: - file: external/Download-Link-Replacer/README.md - file: external/Sphinx-launch-buttons/README.md - file: basic-features/utterances.md - - file: features/jupyterquiz.ipynb - file: features/h5p.md sections: - file: examples/h5p_examples.md @@ -86,6 +85,7 @@ parts: sections: - file: features/widgets.ipynb - file: features/exercise_checking.ipynb + - file: features/jupyterquiz.ipynb - file: external/sphinx-iframes/README.md - file: external/Sphinx-PRIME-applets/README.md - file: features/visuals.md diff --git a/book/features/jupyterquiz.ipynb b/book/features/jupyterquiz.ipynb index 5177224..20f73e3 100644 --- a/book/features/jupyterquiz.ipynb +++ b/book/features/jupyterquiz.ipynb @@ -9,6 +9,13 @@ "source": [ "# JupyterQuiz\n", "\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", + "\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", "A pre-fabricated bridge design is being considered for river crossings in a remote region of the world, as shown in Figure 1. Cities 1, 2 and 3 are labelled C1, C2 and C3, with bridges labelled B1-B4.\n", diff --git a/book/features/plotly.ipynb b/book/features/plotly.ipynb index b969dfb..ec889da 100644 --- a/book/features/plotly.ipynb +++ b/book/features/plotly.ipynb @@ -9,6 +9,11 @@ "source": [ "# Interactive plots: plotly\n", "\n", + "```{admonition} User types\n", + ":class: tip\n", + "This section is useful for user type 5.\n", + "```\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." ] }, From 88670064288f38fca39043cd6b85b49ccec49190 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 20 Mar 2025 11:23:21 +0100 Subject: [PATCH 12/41] add script for live code --- book/features/directories.py | 22 ++++++++++++++++++++++ book/features/live_code.ipynb | 2 +- 2 files changed, 23 insertions(+), 1 deletion(-) create mode 100644 book/features/directories.py diff --git a/book/features/directories.py b/book/features/directories.py new file mode 100644 index 0000000..02bb2a8 --- /dev/null +++ b/book/features/directories.py @@ -0,0 +1,22 @@ +import os +import json + +def list_file_types(directory): + file_types = set() + for root, _, files in os.walk(directory): + for file in files: + _, ext = os.path.splitext(file) + if ext: # Only include files with extensions + file_types.add(ext) + return sorted(file_types) + +def format_file_types(file_types): + formatted = [f"**/*{ext}" for ext in file_types] + return formatted + +if __name__ == "__main__": + book_directory = r"c:\Users\tomvanwoudenbe\Git\book\book" + file_types = list_file_types(book_directory) + formatted_file_types = format_file_types(file_types) + print("File types in the directory (formatted):") + print(json.dumps(formatted_file_types)) \ No newline at end of file diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb index 3971cac..a4703a7 100644 --- a/book/features/live_code.ipynb +++ b/book/features/live_code.ipynb @@ -85,7 +85,7 @@ "The `html_js_files` link calls for some required javascript files. `use_thebe_lite` makes sure you initiate our adapted sphinx thebe extensions. The `exclude_patterns` makes sure you import all files so that they can be accessed from your code, except for the files matching the patterns shown.\n", "\n", ":::{note}\n", - "If you've a lot of big files which are not used by the code, the build book repository might grow a lot in size. Include unnecessary filetypes like images (i.e. `\"**/*.png`) to `exclude_patterns`. Make sure you use proper markdown or MyST syntax for referencing to images. Using HTML code might lead to figures not being available in the final book.\n", + "If you've a lot of big files which are not used by the code, the build book repository might grow a lot in size. Include unnecessary filetypes like images (i.e. `\"**/*.png`) to `exclude_patterns`. Make sure you use proper markdown or MyST syntax for referencing to images. Using HTML code might lead to figures not being available in the final book. You can use [this python script](./directories.py) to list all filetypes in your book.\n", ":::\n", "\n", "By `launch_buttons` you initiate the {fa}`rocket` --> {guilabel}`Live Code` on the top right corner of every page generated from a `.ipynb` file. \n", From 9270ac543bce1b9df529377b91bd1651aa4d7c31 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 21 Mar 2025 15:12:00 +0100 Subject: [PATCH 13/41] update manual --- book/external/deploy-book-workflow | 2 +- book/external/template | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow index b9c7623..b655fb1 160000 --- a/book/external/deploy-book-workflow +++ b/book/external/deploy-book-workflow @@ -1 +1 @@ -Subproject commit b9c76239ed042eb5befb6fa47f14d44de5113c51 +Subproject commit b655fb125d39ad35b980357ed5ea20f3ed4204a4 diff --git a/book/external/template b/book/external/template index a8958fe..43f37f9 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit a8958fe48c839729226e1d1765dbf26617cf6c59 +Subproject commit 43f37f9bafcfa91f82be765302d505bc64c114ee From 25044d4c93b86869a2736f390885fe98527447e2 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 21 Mar 2025 15:25:37 +0100 Subject: [PATCH 14/41] Update Nested-Books --- book/external/Nested-Books | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/Nested-Books b/book/external/Nested-Books index a8e57da..134fcc3 160000 --- a/book/external/Nested-Books +++ b/book/external/Nested-Books @@ -1 +1 @@ -Subproject commit a8e57da25302d47806ad1fe4288950c438562199 +Subproject commit 134fcc3384f0e01591881b59265a58b4eeee849b From 2bd4db8be3588130ec214cb964bff087063f864f Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 08:18:36 +0100 Subject: [PATCH 15/41] rm submodule JupyterBook-Patches --- .gitmodules | 4 ---- book/external/JupyterBook-Patches | 1 - 2 files changed, 5 deletions(-) delete mode 100644 book/external/JupyterBook-Patches diff --git a/.gitmodules b/.gitmodules index 5cabeb7..9f77bd4 100644 --- a/.gitmodules +++ b/.gitmodules @@ -18,10 +18,6 @@ path = book/external/Sphinx-Image-Inverter url = https://github.com/TeachBooks/Sphinx-Image-Inverter.git branch = Manual -[submodule "book/external/JupyterBook-Patches"] - path = book/external/JupyterBook-Patches - url = https://github.com/TeachBooks/JupyterBook-Patches.git - branch = manual_docs [submodule "book/external/Download-Link-Replacer"] path = book/external/Download-Link-Replacer url = https://github.com/TeachBooks/Download-Link-Replacer.git diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches deleted file mode 100644 index d5efad9..0000000 --- a/book/external/JupyterBook-Patches +++ /dev/null @@ -1 +0,0 @@ -3a1ed3738693931fb735810cbc7a9a5734e85788 \ No newline at end of file From 88fd03fea5f2974e05138991f96da30e6d318745 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sat, 22 Mar 2025 08:19:57 +0100 Subject: [PATCH 16/41] add jupyterboko-patcches backin --- .gitmodules | 4 ++++ book/external/JupyterBook-Patches | 1 + 2 files changed, 5 insertions(+) create mode 160000 book/external/JupyterBook-Patches diff --git a/.gitmodules b/.gitmodules index 9f77bd4..4b36129 100644 --- a/.gitmodules +++ b/.gitmodules @@ -54,3 +54,7 @@ path = book/external/Sphinx-PRIME-applets url = https://github.com/TeachBooks/Sphinx-PRIME-applets.git branch = manual +[submodule "book/external/JupyterBook-Patches"] + path = book/external/JupyterBook-Patches + url = https://github.com/TeachBooks/JupyterBook-Patches.git + branch = manual_docs diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches new file mode 160000 index 0000000..3a1ed37 --- /dev/null +++ b/book/external/JupyterBook-Patches @@ -0,0 +1 @@ +Subproject commit 3a1ed3738693931fb735810cbc7a9a5734e85788 From a8915bfcaf3ae4a9991acbe5129dadac2c2e66de Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 22 Mar 2025 07:21:09 +0000 Subject: [PATCH 17/41] Bump book/external/template from `43f37f9` to `1a29a78` Bumps [book/external/template](https://github.com/TeachBooks/template) from `43f37f9` to `1a29a78`. - [Commits](https://github.com/TeachBooks/template/compare/43f37f9bafcfa91f82be765302d505bc64c114ee...1a29a7826bb6327347799a37a40a6b73badc5ff8) --- updated-dependencies: - dependency-name: book/external/template dependency-type: direct:production ... Signed-off-by: dependabot[bot] --- book/external/template | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/template b/book/external/template index 43f37f9..1a29a78 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit 43f37f9bafcfa91f82be765302d505bc64c114ee +Subproject commit 1a29a7826bb6327347799a37a40a6b73badc5ff8 From 3b8f143ad31e5d3f7e01b68a5ba1f86ed1dd832f Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 22 Mar 2025 07:21:11 +0000 Subject: [PATCH 18/41] Bump book/external/deploy-book-workflow from `b655fb1` to `01eef2d` Bumps [book/external/deploy-book-workflow](https://github.com/TeachBooks/deploy-book-workflow) from `b655fb1` to `01eef2d`. - [Commits](https://github.com/TeachBooks/deploy-book-workflow/compare/b655fb125d39ad35b980357ed5ea20f3ed4204a4...01eef2d619bbe8dd2558fde924e6efb2ba23c136) --- updated-dependencies: - dependency-name: book/external/deploy-book-workflow dependency-type: direct:production ... Signed-off-by: dependabot[bot] --- book/external/deploy-book-workflow | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow index b655fb1..01eef2d 160000 --- a/book/external/deploy-book-workflow +++ b/book/external/deploy-book-workflow @@ -1 +1 @@ -Subproject commit b655fb125d39ad35b980357ed5ea20f3ed4204a4 +Subproject commit 01eef2d619bbe8dd2558fde924e6efb2ba23c136 From 761b6572aec8557115a6c8e278ce35235d011e90 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sun, 23 Mar 2025 18:30:22 +0000 Subject: [PATCH 19/41] Bump book/external/deploy-book-workflow from `01eef2d` to `26afa87` Bumps [book/external/deploy-book-workflow](https://github.com/TeachBooks/deploy-book-workflow) from `01eef2d` to `26afa87`. - [Commits](https://github.com/TeachBooks/deploy-book-workflow/compare/01eef2d619bbe8dd2558fde924e6efb2ba23c136...26afa87f90a4191de0e07f89c6de674ea8b81b8d) --- updated-dependencies: - dependency-name: book/external/deploy-book-workflow dependency-type: direct:production ... Signed-off-by: dependabot[bot] --- book/external/deploy-book-workflow | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow index 01eef2d..26afa87 160000 --- a/book/external/deploy-book-workflow +++ b/book/external/deploy-book-workflow @@ -1 +1 @@ -Subproject commit 01eef2d619bbe8dd2558fde924e6efb2ba23c136 +Subproject commit 26afa87f90a4191de0e07f89c6de674ea8b81b8d From 5d7ddb270771dfd8e12ebcc5386fd2075d8bd9be Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Sun, 23 Mar 2025 19:33:08 +0100 Subject: [PATCH 20/41] Update versions_URLs.md --- book/installation-and-setup/versions_URLs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/installation-and-setup/versions_URLs.md b/book/installation-and-setup/versions_URLs.md index 836ebaf..d948409 100644 --- a/book/installation-and-setup/versions_URLs.md +++ b/book/installation-and-setup/versions_URLs.md @@ -6,7 +6,7 @@ If you plan on maintaining only one public version, it is advisable to set `BEHA To share the built book / website of old versions for your book on GitHub you have a few options: - Create a branch for each version. When doing this, [the GitHub workflow](../external/deploy-book-workflow/README.md) will build it on GitHub pages. Here's a few tips: - - It's advised to use the version as branch name. In case of versions per academic year, you can just name each branch to the current academic year, this leads to the URL with the same name. In that case. + - It's advised to use the version as branch name. In case of versions per academic year, you can just name each branch to the current academic year, this leads to the URL with the same academic year.. - It is recommended to update the primary branch as the `PRIMARY BRANCH` when using the [GitHub workflow](gh-workflow-settings) whenever a new version is considered to be the most primary one. This ensures that readers are redirected to a consistent URL, even when new versions of the book are added later. - Eventually, you can add old branches to the list of `BRANCHES_ARCHIVED` when using the [GitHub workflow](gh-workflow-settings) to include a banner on the page indicating its archived state. Alternatively, you can add a banner manually to `_config.yml`, as explained [here](../basic-features/banner.md). - If you're using tags (as will be explained in [later](./versioning_changelog.md)), you can create a branch from a tag locally by running: `git branch `. From 9cb3724878cafe5ab8de3ad9552a22e7be9ad54b Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 24 Mar 2025 09:04:17 +0100 Subject: [PATCH 21/41] Update collab.md --- book/installation-and-setup/collab.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/installation-and-setup/collab.md b/book/installation-and-setup/collab.md index 9db1239..201c1c9 100644 --- a/book/installation-and-setup/collab.md +++ b/book/installation-and-setup/collab.md @@ -13,7 +13,7 @@ Finally, ensure that team members identify themselves according to the user type ## Review process Furthermore, establish a clear editing and review process. -For the editing process, establish some practical rules on whether to use issues, branches and forks for adding content, fixing typos or making other changes. Furthermore, it can help to write down when you expect (draft) merge/pull requests and how to use the assign and review options in GitHub/GitLab. It is advisable to have at least a maintainer review each piece of content to maintain quality and consistency. Provide explanation on how you organize the book-editing and how you'd like to receive feedback in both the readme as the published book. The use of the [repository button {fa}`fa-github`, suggest edit {fa}`pencil` and issue button {fa}`lightbulb`](https://jupyterbook.org/en/stable/basics/repository.html) is advised. +For the editing process, establish some practical rules on whether to use issues, branches and forks for adding content, fixing typos or making other changes. Furthermore, it can help to write down when you expect (draft) merge/pull requests and how to use the assign and review options in GitHub/GitLab. It is advisable to have at least a maintainer review each piece of content to maintain quality and consistency. Provide explanation on how you organize the book-editing and how you'd like to receive feedback in both the readme as the published book. The use of the [repository button {fa}`github`, suggest edit {fa}`pencil` and issue button {fa}`lightbulb`](https://jupyterbook.org/en/stable/basics/repository.html) is advised. (draft_book)= ## Define draft version of book @@ -46,4 +46,4 @@ Additionally, it is advisable to document the branch protection strategy and the - Block force pushes ## Private, internally or public -Choose whether you want to share your source code and built book privately, internally or publicly. In any case, you need to obey copyright-rules. We advise public repositories and books in line with a vision on open education. \ No newline at end of file +Choose whether you want to share your source code and built book privately, internally or publicly. In any case, you need to obey copyright-rules. We advise public repositories and books in line with a vision on open education. From 9665fb50270a6b813798f414e44c84202621dcbe Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 27 Mar 2025 09:42:42 +0100 Subject: [PATCH 22/41] add script to move images --- book/_toc.yml | 1 + book/helper_code/move_images.md | 3 + book/helper_code/parse_images.py | 207 +++++++++++++++++++++++++++++++ 3 files changed, 211 insertions(+) create mode 100644 book/helper_code/move_images.md create mode 100644 book/helper_code/parse_images.py diff --git a/book/_toc.yml b/book/_toc.yml index d841379..5088086 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -118,6 +118,7 @@ parts: - file: helper_code/intro.md sections: - file: helper_code/converter.md + - file: helper_code/move_images.md - file: external/Useful_python_code/snippit.ipynb - file: external/Useful_python_code/extensionfildownloadreturn.ipynb - file: external/Useful_python_code/figshrinker.ipynb diff --git a/book/helper_code/move_images.md b/book/helper_code/move_images.md new file mode 100644 index 0000000..1657c32 --- /dev/null +++ b/book/helper_code/move_images.md @@ -0,0 +1,3 @@ +# Move images to separate hosting + +Storing big binary files like images in your git repository and book is not good practice: diffs on binary files don't make sense and blow up the size of your repository. Furthermore, the size of your book website blows up too. Therefore, you can consider hosting your binary files on a different server, as explained [here in an example for the MUDE-book](https://tudelft-mude.github.io/teacher/FTP.html). To take all the images of your existing book and update the relative links, [a Python script](./parse_images.py) has been developed. This script processes Markdown (`.md`) and Jupyter Notebook (`.ipynb`) files listed in a `_toc.yml` file. It identifies local image references (including MyST `figure` syntax) in these files, copies the images to a specified folder (`new_images`), and replaces the local image paths with a public URL (e.g., `https://files.mude.citg.tudelft.nl/`). \ No newline at end of file diff --git a/book/helper_code/parse_images.py b/book/helper_code/parse_images.py new file mode 100644 index 0000000..e72f22d --- /dev/null +++ b/book/helper_code/parse_images.py @@ -0,0 +1,207 @@ +""" +Script: parse_images.py + +Description: +This script processes Markdown (.md) and Jupyter Notebook (.ipynb) files listed in a `_toc.yml` file. +It identifies local image references (including MyST `figure` syntax) in these files, copies the images +to a specified folder (`new_images`), and replaces the local image paths with a public URL +(e.g., `https://files.mude.citg.tudelft.nl/`). + +Key Features: +- Parses `_toc.yml` to extract all Markdown and Notebook files. +- Detects image references in Markdown files (e.g., `![alt text](image.png "title")`). +- Detects MyST `figure` syntax (e.g., `{figure} /path/to/image.png`). +- Resolves image paths relative to the file or project root. +- Handles image paths with optional titles (e.g., `"title"`) in Markdown and Notebook files. +- Skips processing images that are already converted to the public URL. +- Copies images to the `new_images` folder. +- Updates the files to replace local image paths with public URLs. + +How to Use: +1. Place this script in the root directory of your project (where `_toc.yml` is located). +2. Ensure `_toc.yml` contains the list of files to process. +3. Run the script using Python: python parse_images.py +4. The script will: +- Copy referenced images to the `new_images` folder. +- Update the Markdown and Notebook files with the new image URLs. + +Dependencies: +- Python 3.x +- PyYAML (install using `pip install pyyaml`) + +Notes: +- Ensure the script is run from the project root directory. +- The `base_url` variable should be updated to match your desired public URL prefix. +- The script handles image paths in the following formats: + - Relative paths (e.g., `image.png`, `./image.png`). + - Absolute paths (e.g., `/path/to/image.png`). + - Paths with optional titles (e.g., `![alt text](image.png "title")`). +""" + +import os +import re +import shutil +import yaml +import json + +# Define the folder where images will be copied +output_folder = "new_images" +base_url = "https://files.mude.citg.tudelft.nl/" + +# Ensure the output folder exists +os.makedirs(output_folder, exist_ok=True) + +# Function to parse the _toc.yml file and extract all Markdown and Notebook files +def get_files_from_toc(toc_file): + files = [] + with open(toc_file, "r", encoding="utf-8") as f: + toc = yaml.safe_load(f) + + # Recursive function to extract file paths + def extract_files(item): + if isinstance(item, dict): + if "file" in item: + # Add the file with the appropriate extension + file_path = item["file"] + if not file_path.endswith((".md", ".ipynb")): + if os.path.isfile(file_path + ".md"): + file_path += ".md" + elif os.path.isfile(file_path + ".ipynb"): + file_path += ".ipynb" + files.append(file_path) + if "sections" in item: + for section in item["sections"]: + extract_files(section) + if "chapters" in item: + for chapter in item["chapters"]: + extract_files(chapter) + elif isinstance(item, list): + for sub_item in item: + extract_files(sub_item) + + # Start extracting files from the "parts" section + extract_files(toc.get("parts", [])) + return files + +# Function to normalize image paths +def normalize_image_path(file_dir, image_path): + # Check if the path starts with a `/` (absolute path relative to the project root) + if image_path.startswith("/"): + # Resolve the path relative to the project root + project_root = os.getcwd() # Assuming the script is run from the project root + resolved_path = os.path.join(project_root, image_path.lstrip("/")) + else: + # Resolve the path relative to the file's directory + resolved_path = os.path.normpath(os.path.join(file_dir, image_path)) + return resolved_path + +# Function to find and replace local image references +def process_file(file_path): + if file_path.endswith(".md"): + process_markdown(file_path) + elif file_path.endswith(".ipynb"): + process_notebook(file_path) + +# Process Markdown files +def process_markdown(file_path): + file_dir = os.path.dirname(file_path) # Get the directory of the file + with open(file_path, "r", encoding="utf-8") as f: + content = f.read() + + # Find all standard Markdown image references (e.g., ![alt text](path "title")) + matches = re.findall(r"!\[.*?\]\((.*?)(?:\s+\".*?\")?\)", content) + # Find all MyST figure syntax references (e.g., {figure} path) + # Handles cases where the `---` block is missing or caption follows directly + myst_matches = re.findall(r"\{figure\}\s+(.*?)\s*(?:\n|$)", content) + matches.extend(myst_matches) + + for match in matches: + # Skip if the image path is already converted to the public URL + if match.startswith(base_url): + continue + + # Normalize and resolve the image path + image_path = normalize_image_path(file_dir, match) + + if os.path.isfile(image_path): + print(f"Image found: {image_path}") # Debugging output + # Copy the image to the output folder + image_name = os.path.basename(image_path) + new_path = os.path.join(output_folder, image_name) + shutil.copy(image_path, new_path) + + # Replace the local URL with the new URL + new_url = base_url + image_name + content = content.replace(match, new_url) + else: + print(f"Warning: Image not found: {image_path}") # Debugging output + + # Write the updated content back to the file + with open(file_path, "w", encoding="utf-8") as f: + f.write(content) + +# Process Jupyter Notebook files +def process_notebook(file_path): + file_dir = os.path.dirname(file_path) # Get the directory of the file + with open(file_path, "r", encoding="utf-8") as f: + notebook = json.load(f) + + updated = False + for cell in notebook.get("cells", []): + if cell.get("cell_type") == "markdown": + # Join all lines in the cell into a single string + cell_content = "".join(cell.get("source", [])) + + # Find all standard Markdown image references (e.g., ![alt text](path "title")) + matches = re.findall(r"!\[.*?\]\((.*?)(?:\s+\".*?\")?\)", cell_content) + # Find all MyST figure syntax references (e.g., {figure} path) + myst_matches = re.findall(r"\{figure\}\s+(.*?)\s*(?:\n|$)", cell_content) + matches.extend(myst_matches) + + for match in matches: + # Skip if the image path is already converted to the public URL + if match.startswith(base_url): + continue + + # Normalize and resolve the image path + image_path = normalize_image_path(file_dir, match) + + if os.path.isfile(image_path): + print(f"Image found: {image_path}") # Debugging output + # Copy the image to the output folder + image_name = os.path.basename(image_path) + new_path = os.path.join(output_folder, image_name) + shutil.copy(image_path, new_path) + + # Replace the local URL with the new URL + new_url = base_url + image_name + cell_content = cell_content.replace(match, new_url) + updated = True + else: + print(f"Warning: Image not found: {image_path}") # Debugging output + + # Split the updated content back into lines and update the cell + cell["source"] = cell_content.splitlines(keepends=True) + + # Write the updated notebook back to the file if changes were made + if updated: + with open(file_path, "w", encoding="utf-8") as f: + json.dump(notebook, f, indent=2) + +# Main function +def main(): + toc_file = "_toc.yml" # Replace with the path to your _toc.yml file + files = get_files_from_toc(toc_file) + + print("Files extracted from TOC:", files) # Debugging output + + for file_path in files: + # Ensure the file has the correct extension and exists + if os.path.isfile(file_path): + print(f"Processing file: {file_path}") # Debugging output + process_file(file_path) + else: + print(f"Warning: File {file_path} not found or unsupported.") + +if __name__ == "__main__": + main() \ No newline at end of file From eb87bd47f58b3c01d5727064b3d0d08f52140479 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 27 Mar 2025 09:46:13 +0100 Subject: [PATCH 23/41] fix relative link --- book/basic-features/badges.md | 6 +++--- book/features/overview.md | 1 + 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/book/basic-features/badges.md b/book/basic-features/badges.md index 14fbff4..6fe1ad2 100644 --- a/book/basic-features/badges.md +++ b/book/basic-features/badges.md @@ -49,13 +49,13 @@ The basic code syntax for creating a button is as follows: :color: primary ``` ``` - -```{button-ref} ../features/overview.md +[](../features/overview.md) +```{button-ref} feature_overview :color: secondary ``` ``` - ```{button-ref} ../features/overview.md + ```{button-ref} feature_overview :color: secondary ``` ``` diff --git a/book/features/overview.md b/book/features/overview.md index 4a6cd20..35dd27f 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -1,3 +1,4 @@ +(feature_overview)= # Overview As TeachBooks, we collect a suite of existing open-source software 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. 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! From 3a08f5cf8c2fbe1dd222a9e83093ef97d45e3934 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 27 Mar 2025 09:46:56 +0100 Subject: [PATCH 24/41] fix link --- book/features/widgets.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/features/widgets.ipynb b/book/features/widgets.ipynb index cf1f593..63a0846 100644 --- a/book/features/widgets.ipynb +++ b/book/features/widgets.ipynb @@ -6,7 +6,7 @@ "source": [ "# Ipywidgets\n", "\n", - "If you publish widgets in a jupyter book they might (depending on your implementation) require an active python kernel for the output to be interactive. Using the [thebe-integration](../examples/live_code.md), this is possible. Note: You can circumvent the use of a kernel by using packages which don't need such a kernel, for example the [non-kernel-based widgets using Plotly](interactive_element).\n", + "If you publish widgets in a jupyter book they might (depending on your implementation) require an active python kernel for the output to be interactive. Using the [thebe-integration](../examples/live_code.md), this is possible. Note: You can circumvent the use of a kernel by using packages which don't need such a kernel, for example the [non-kernel-based widgets using Plotly](./plotly.ipynb).\n", "\n", "## `matplotlib` widgets\n", "When you'd like to use `ipywidgets` in combinations with a `matplotlib` figure, import the following packages:\n", From f97d42083925aec35ecdba7bd031104c498eeb6e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Thu, 27 Mar 2025 09:49:52 +0100 Subject: [PATCH 25/41] small fixes --- book/basic-features/equations.md | 8 +++++--- book/external/template | 2 +- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/book/basic-features/equations.md b/book/basic-features/equations.md index 4f6d293..5ec7a99 100644 --- a/book/basic-features/equations.md +++ b/book/basic-features/equations.md @@ -29,9 +29,11 @@ $$ F = m \cdot a = 10 \cdot 9.81 = 98 \text{N}$$ To number the equations and refer in text, you need to provide a label to the equation. Just put the label between brackets and place it after the last \$\$, like this: - $$ - F = m \cdot a - $$ (newtons_second_law) +```md +$$ + F = m \cdot a +$$ (newtons_second_law) +``` Resulting in: diff --git a/book/external/template b/book/external/template index 1a29a78..82b2de6 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit 1a29a7826bb6327347799a37a40a6b73badc5ff8 +Subproject commit 82b2de6a80b824482dd38f350a9aaf5f4a7a5fe0 From 4213bdc58739525adcf5523de47d9524167ed7ea Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 27 Mar 2025 10:24:48 +0000 Subject: [PATCH 26/41] Bump book/external/JupyterBook-Patches from `3a1ed37` to `763b59d` Bumps [book/external/JupyterBook-Patches](https://github.com/TeachBooks/JupyterBook-Patches) from `3a1ed37` to `763b59d`. - [Release notes](https://github.com/TeachBooks/JupyterBook-Patches/releases) - [Commits](https://github.com/TeachBooks/JupyterBook-Patches/compare/3a1ed3738693931fb735810cbc7a9a5734e85788...763b59d720217a29b811e2c33449832cb443180f) --- updated-dependencies: - dependency-name: book/external/JupyterBook-Patches dependency-type: direct:production ... Signed-off-by: dependabot[bot] --- book/external/JupyterBook-Patches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches index 3a1ed37..763b59d 160000 --- a/book/external/JupyterBook-Patches +++ b/book/external/JupyterBook-Patches @@ -1 +1 @@ -Subproject commit 3a1ed3738693931fb735810cbc7a9a5734e85788 +Subproject commit 763b59d720217a29b811e2c33449832cb443180f From 95134f24b4ffd119abb9d91ae62ca1d3c122070f Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 28 Mar 2025 11:04:05 +0100 Subject: [PATCH 27/41] Create CITATION.cff --- CITATION.cff | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 CITATION.cff diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 0000000..11e3ba9 --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,41 @@ +# This CITATION.cff file was generated with cffinit. +# Visit https://bit.ly/cffinit to generate yours today! + +cff-version: 1.2.0 +message: 'If you use this Book, please cite it using these metadata.' +preferred-citation: + type: book + authors: + - email: info@teachbooks.io + name: 'TeachBooks Development Team' + website: 'https://teachbooks.io/' + url: 'https://teachbooks.io/manual/' + identifiers: + - type: url + value: 'https://teachbooks.io/manual/' + description: 'Published book on GitHub Pages' + - type: url + value: 'https://github.com/TeachBooks/manual' + description: 'GitHub repository' + abstract: >- + his manual assists you in creating and collaborating on JupyterBooks + for educational purposes. Some parts are specifically aimed for + teachers at Delft University of Technology, although all material and + tools are openly available. This manual aims at providing an easy start + and advanced usages for new and existing users with or without skills + on this topic. + keywords: + - TeachBooks + - Manual + - 'Jupyter Book' + title: 'TeachBooks Manual' + institution: + name: 'TeachBooks' + license: CC-BY-4.0 + license-url: 'https://creativecommons.org/licenses/by/4.0/' + copyright: '© 2025 TeachBooks' + languages: + - en + contact: + - email: info@teachbooks.io + name: 'TeachBooks Development Team' From f95a2b4e2a9bf97ff201780486d631d4039e9a71 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 28 Mar 2025 11:32:41 +0100 Subject: [PATCH 28/41] Update CITATION.cff --- CITATION.cff | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CITATION.cff b/CITATION.cff index 11e3ba9..87c0266 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -3,6 +3,11 @@ cff-version: 1.2.0 message: 'If you use this Book, please cite it using these metadata.' +authors: + - email: info@teachbooks.io + name: 'TeachBooks Development Team' + website: 'https://teachbooks.io/' +title: 'TeachBooks Manual source code' preferred-citation: type: book authors: From 5c61c64b0e4945dd67ef82ace097878c4dac790c Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 28 Mar 2025 11:44:19 +0100 Subject: [PATCH 29/41] Update README.md --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 72d5d51..6ec7aee 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ # TeachBooks Manual +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15100848.svg)](https://doi.org/10.5281/zenodo.15100848) [![call-deploy-book](https://github.com/TeachBooks/manual/actions/workflows/call-deploy-book.yml/badge.svg)](https://github.com/TeachBooks/manual/actions/workflows/call-deploy-book.yml) This manual assists you in creating and collaborating on [JupyterBooks](https://jupyterbook.org/) for educational purposes. Some parts are specifically aimed for teachers at Delft University of Technology, although all material and tools are openly available. This manual aims at providing an easy start and advanced usages for new and existing users with or without skills on this topic. it is part of TeachBooks, for more information visit [https://teachbooks.io/](https://teachbooks.io/). From 49e396a296622366e31abd63de235b090fbb58bf Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 28 Mar 2025 11:44:34 +0100 Subject: [PATCH 30/41] Update intro.md --- book/intro.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/book/intro.md b/book/intro.md index a918590..5e9715b 100644 --- a/book/intro.md +++ b/book/intro.md @@ -1,5 +1,7 @@ # TeachBooks Manual +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15100848.svg)](https://doi.org/10.5281/zenodo.15100848) + This manual is primarily designed for and by teachers for use in education, but should be a useful resource for anyone interested in creating and collaborating on Jupyter book. Our aim is to provide a simple way to start book-making for new users (it only takes 10 clicks!) through advanced usage for experienced users. We hope you find this resource useful and refer back to it often. TeachBooks originated at Delft University of Technology in the Netherlands, and some of the material in this Manual reflects tools and resources specific to TU Delft. With the exception of a few tools for which we have educational licenses at Delft, everything in this Manual is open source. Despite this, we are happy to grow our community beyond Delft and welcome contributions from all users. @@ -16,4 +18,4 @@ There are several "parts" to the manual: - The **Features** part describes a suite of tools that are useful for teachers, many of which are developed by TeachBooks contributors specifically for use in education. Many of these tools are illustrated in the **Examples**. - A few special tools are included in the **Editing Tools** that are useful when writing content. -See the final chapters of this book (under **Miscellaneous**) for additional information about References, Credits, etc. \ No newline at end of file +See the final chapters of this book (under **Miscellaneous**) for additional information about References, Credits, etc. From 5bb1d3275c3291d25e6c88504d73fdc0223d82a4 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 28 Mar 2025 11:46:12 +0100 Subject: [PATCH 31/41] Update credits.md --- book/credits.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/book/credits.md b/book/credits.md index 64caec1..cd2a79a 100644 --- a/book/credits.md +++ b/book/credits.md @@ -3,13 +3,13 @@ You can refer to this book in its entirety as: -> TeachBooks Development Team (2024), _TeachBooks Manual_. https://github.com/TeachBooks/manual. Retreived [Month, Year]. CC BY 4.0. +> TeachBooks Development Team (2024), _TeachBooks Manual_. https://doi.org/10.5281/zenodo.15100848. Retreived [Month, Year]. CC BY 4.0. The introduction, structure and decisions on content is done under direction of the TeachBooks Development Team. The content is written by many contributors, of which there are many. -We anticipate that the content of this book will change continuously. Therefore, if you'd like to refer to a specific chapter, we recommend using the source code directly with the citation that refers to the GitHub repository and lists the date and name of the file. Although content will be added over time, chapter titles and URL's in this book are expected to remain relatively static after Spring 2025. You can refer to individual chapters or pages within this book as: +We anticipate that the content of this book will change continuously. Therefore, if you'd like to refer to a specific chapter, we recommend using the source code directly with the citation that refers to the GitHub repository and lists the date and name of the file. Although content will be added over time, chapter titles and URL's in this book are expected to remain relatively static. You can refer to individual chapters or pages within this book as: -> `` (2024), ``. In _TeachBooks Manual_. https://github.com/TeachBooks/manual (chapter `./book/intro/`, retrieved [`<date>`]). +> `<Title of Chapter or Page>`. In TeachBooks Development Team (2024), _TeachBooks Manual_. https://doi.org/10.5281/zenodo.15100848. CC BY 4.0. (chapter `./book/intro/`, retrieved [`<date>`]). Better yet, include a link to the specific commit! _If you know what this means, we assume you know how to do it._ From ffdecc307dad1117bb3b7069828107e11d17c905 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Fri, 28 Mar 2025 11:47:39 +0100 Subject: [PATCH 32/41] Update CITATION.cff --- CITATION.cff | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/CITATION.cff b/CITATION.cff index 87c0266..72d95e1 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -14,8 +14,11 @@ preferred-citation: - email: info@teachbooks.io name: 'TeachBooks Development Team' website: 'https://teachbooks.io/' - url: 'https://teachbooks.io/manual/' + url: 'https://doi.org/10.5281/zenodo.15100847' identifiers: + - type: doi + value: 10.5281/zenodo.15100848 + description: Zenodo record - type: url value: 'https://teachbooks.io/manual/' description: 'Published book on GitHub Pages' @@ -39,6 +42,8 @@ preferred-citation: license: CC-BY-4.0 license-url: 'https://creativecommons.org/licenses/by/4.0/' copyright: '© 2025 TeachBooks' + version: v1.2.1 + date-released: '2025-03-28' languages: - en contact: From 3c6620ba1a39555e429f3acb266125959af5470d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Fri, 28 Mar 2025 15:21:15 +0100 Subject: [PATCH 33/41] Create WAIVER --- WAIVER | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 WAIVER diff --git a/WAIVER b/WAIVER new file mode 100644 index 0000000..9979091 --- /dev/null +++ b/WAIVER @@ -0,0 +1,4 @@ +Technische Universiteit Delft hereby disclaims all copyright interest in the +program “TeachBooks Manual” (a book serving as documentation for various tooling +surrounding TeachBooks) written by the Author(s). +Stefan Aarninkhof, Dean of Civil Engineering & Geosciences From 3e24d222808fc608259f515c40cac4c7aec1ff53 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Fri, 28 Mar 2025 15:59:14 +0100 Subject: [PATCH 34/41] Revert "Update credits.md" This reverts commit 5bb1d3275c3291d25e6c88504d73fdc0223d82a4. --- book/credits.md | 6 ++++-- book/intro.md | 2 -- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/book/credits.md b/book/credits.md index cd2a79a..dfdef48 100644 --- a/book/credits.md +++ b/book/credits.md @@ -3,13 +3,15 @@ You can refer to this book in its entirety as: -> TeachBooks Development Team (2024), _TeachBooks Manual_. https://doi.org/10.5281/zenodo.15100848. Retreived [Month, Year]. CC BY 4.0. +> TeachBooks Development Team (2024), _TeachBooks Manual_. https://github.com/TeachBooks/manual. Retreived [Month, Year]. CC BY 4.0. + +This book is already registered on Zenodo: [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15100848.svg)](https://doi.org/10.5281/zenodo.15100848) The introduction, structure and decisions on content is done under direction of the TeachBooks Development Team. The content is written by many contributors, of which there are many. We anticipate that the content of this book will change continuously. Therefore, if you'd like to refer to a specific chapter, we recommend using the source code directly with the citation that refers to the GitHub repository and lists the date and name of the file. Although content will be added over time, chapter titles and URL's in this book are expected to remain relatively static. You can refer to individual chapters or pages within this book as: -> `<Title of Chapter or Page>`. In TeachBooks Development Team (2024), _TeachBooks Manual_. https://doi.org/10.5281/zenodo.15100848. CC BY 4.0. (chapter `./book/intro/`, retrieved [`<date>`]). +> `<Title of Chapter or Page>`. In _TeachBooks Manual_. https://github.com/TeachBooks/manual (chapter `./book/intro/`, retrieved [`<date>`]). Better yet, include a link to the specific commit! _If you know what this means, we assume you know how to do it._ diff --git a/book/intro.md b/book/intro.md index 5e9715b..f5784e3 100644 --- a/book/intro.md +++ b/book/intro.md @@ -1,7 +1,5 @@ # TeachBooks Manual -[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15100848.svg)](https://doi.org/10.5281/zenodo.15100848) - This manual is primarily designed for and by teachers for use in education, but should be a useful resource for anyone interested in creating and collaborating on <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>. Our aim is to provide a simple way to start book-making for new users (it only takes 10 clicks!) through advanced usage for experienced users. We hope you find this resource useful and refer back to it often. TeachBooks originated at Delft University of Technology in the Netherlands, and some of the material in this Manual reflects tools and resources specific to TU Delft. With the exception of a few tools for which we have educational licenses at Delft, everything in this Manual is open source. Despite this, we are happy to grow our community beyond Delft and welcome contributions from all users. From e434477333a62c81ee75e3bb07f2def48fcb4300 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sun, 30 Mar 2025 22:27:09 +0000 Subject: [PATCH 35/41] Bump book/external/JupyterBook-Patches from `763b59d` to `aa93fc5` Bumps [book/external/JupyterBook-Patches](https://github.com/TeachBooks/JupyterBook-Patches) from `763b59d` to `aa93fc5`. - [Release notes](https://github.com/TeachBooks/JupyterBook-Patches/releases) - [Commits](https://github.com/TeachBooks/JupyterBook-Patches/compare/763b59d720217a29b811e2c33449832cb443180f...aa93fc51bf95876f8034005ffcd777045ea9ddc6) --- updated-dependencies: - dependency-name: book/external/JupyterBook-Patches dependency-type: direct:production ... Signed-off-by: dependabot[bot] <support@github.com> --- book/external/JupyterBook-Patches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches index 763b59d..aa93fc5 160000 --- a/book/external/JupyterBook-Patches +++ b/book/external/JupyterBook-Patches @@ -1 +1 @@ -Subproject commit 763b59d720217a29b811e2c33449832cb443180f +Subproject commit aa93fc51bf95876f8034005ffcd777045ea9ddc6 From 7e53a8d5bb1e8ad75673cfb63f6c07c50709a29e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sun, 30 Mar 2025 22:40:07 +0000 Subject: [PATCH 36/41] Bump jupyterbook-patches from 1.4.2 to 1.4.4 Bumps [jupyterbook-patches](https://github.com/TeachBooks/JupyterBook-Patches) from 1.4.2 to 1.4.4. - [Release notes](https://github.com/TeachBooks/JupyterBook-Patches/releases) - [Commits](https://github.com/TeachBooks/JupyterBook-Patches/compare/v1.4.2...v1.4.4) --- updated-dependencies: - dependency-name: jupyterbook-patches dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 2532827..0451ff4 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,6 @@ teachbooks == 0.1.0 sphinx-inline-tabs == 2023.4.21 -jupyterbook_patches==1.4.2 +jupyterbook_patches==1.4.4 download_link_replacer == 1.0.4 teachbooks-sphinx-grasple == 1.0.5 sphinx-image-inverter == 1.1.2 From e41e6744dc8a4fc94a0927ab420d06b30c78c819 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 1 Apr 2025 13:36:53 +0200 Subject: [PATCH 37/41] update attributions --- book/_config.yml | 2 +- book/_static/attribution.css | 4 ++ book/external/Download-Link-Replacer | 2 +- book/external/JupyterBook-Patches | 2 +- book/external/Nested-Books | 2 +- book/external/Sphinx-Grasple-public | 2 +- book/external/Sphinx-Image-Inverter | 2 +- book/external/Sphinx-Named-Colors | 2 +- book/external/Sphinx-PRIME-applets | 2 +- book/external/Sphinx-TUDelft-theme | 2 +- book/external/Sphinx-launch-buttons | 2 +- book/external/Useful_python_code | 2 +- book/external/annotater | 2 +- book/external/deploy-book-workflow | 2 +- book/external/sphinx-iframes | 2 +- book/external/teachbooks-sphinx-tippy | 2 +- book/external/template | 2 +- book/installation-and-setup/copyright.md | 5 +- .../copyright/considerations.md | 5 +- .../copyright/licenses.md | 5 +- .../copyright/recommendations.md | 59 +++++++++++++++++-- book/references.bib | 16 +++++ 22 files changed, 101 insertions(+), 25 deletions(-) create mode 100644 book/_static/attribution.css diff --git a/book/_config.yml b/book/_config.yml index 03274cc..eaa1a16 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -51,7 +51,7 @@ sphinx: tex: macros: "newcolor": ['\definecolor{newcolor}{RGB}{111, 29, 119}{\color{newcolor}#1}',1] - named_colors_custom_colors: {'onlylight':[165,21,160],'lightanddark':[45,180,117,204,158,110],'hyphen-color':[45,180,117,165,21,160]} + named_colors_custom_colors: {'onlylight':[165,21,160],'lightanddark':[45,180,117,204,158,110],'hyphen-color':[45,180,117,165,21,160],'attributiongrey':[150,150,150]} local_extensions: apastyle: _ext/ bracket_citation_style: _ext/ diff --git a/book/_static/attribution.css b/book/_static/attribution.css new file mode 100644 index 0000000..3c23cc3 --- /dev/null +++ b/book/_static/attribution.css @@ -0,0 +1,4 @@ +/* Attribution */ +div.attribution > .admonition-title::after { + content: "\f10d"; +} \ No newline at end of file diff --git a/book/external/Download-Link-Replacer b/book/external/Download-Link-Replacer index f69e970..b658d1c 160000 --- a/book/external/Download-Link-Replacer +++ b/book/external/Download-Link-Replacer @@ -1 +1 @@ -Subproject commit f69e970a8da7d85e5473c7e5f58299a2ee3cf331 +Subproject commit b658d1c6e1791097b225357025ebe7267d4dccb5 diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches index aa93fc5..1a8e996 160000 --- a/book/external/JupyterBook-Patches +++ b/book/external/JupyterBook-Patches @@ -1 +1 @@ -Subproject commit aa93fc51bf95876f8034005ffcd777045ea9ddc6 +Subproject commit 1a8e9960f0a37ce210df51198e0079430f1a2c6e diff --git a/book/external/Nested-Books b/book/external/Nested-Books index 134fcc3..dcdecc4 160000 --- a/book/external/Nested-Books +++ b/book/external/Nested-Books @@ -1 +1 @@ -Subproject commit 134fcc3384f0e01591881b59265a58b4eeee849b +Subproject commit dcdecc4a7335163ce0f5a8975bfd366a17d5fb94 diff --git a/book/external/Sphinx-Grasple-public b/book/external/Sphinx-Grasple-public index f4eff8d..e13743c 160000 --- a/book/external/Sphinx-Grasple-public +++ b/book/external/Sphinx-Grasple-public @@ -1 +1 @@ -Subproject commit f4eff8d1565eaf127898f2fe216cf5208684fb27 +Subproject commit e13743c7dd2d1de8a0dd7137da2841344ea0f330 diff --git a/book/external/Sphinx-Image-Inverter b/book/external/Sphinx-Image-Inverter index 250103c..8365d4a 160000 --- a/book/external/Sphinx-Image-Inverter +++ b/book/external/Sphinx-Image-Inverter @@ -1 +1 @@ -Subproject commit 250103c723aa782bcec785ae3d241cb1ffebd3d0 +Subproject commit 8365d4a366433bbbdfe7d7d0fbd617270c0e7130 diff --git a/book/external/Sphinx-Named-Colors b/book/external/Sphinx-Named-Colors index 191c2f4..6c5a0f4 160000 --- a/book/external/Sphinx-Named-Colors +++ b/book/external/Sphinx-Named-Colors @@ -1 +1 @@ -Subproject commit 191c2f4ac1755d3b50c6a63950eb6c2e5c035d75 +Subproject commit 6c5a0f4aa9a11b0ba9d5a8f68929ba5773c3312a diff --git a/book/external/Sphinx-PRIME-applets b/book/external/Sphinx-PRIME-applets index 43ea44c..29b5b48 160000 --- a/book/external/Sphinx-PRIME-applets +++ b/book/external/Sphinx-PRIME-applets @@ -1 +1 @@ -Subproject commit 43ea44ccdc917234513fcd0ea1b9d5159a7dc81f +Subproject commit 29b5b48126fadde3839ef20a6256bdbda72d4ef9 diff --git a/book/external/Sphinx-TUDelft-theme b/book/external/Sphinx-TUDelft-theme index e4b71f8..5f26d31 160000 --- a/book/external/Sphinx-TUDelft-theme +++ b/book/external/Sphinx-TUDelft-theme @@ -1 +1 @@ -Subproject commit e4b71f810a66e302243377876f39e1dc4c4a8a6b +Subproject commit 5f26d318bf0696229041d20518900695d6ff935f diff --git a/book/external/Sphinx-launch-buttons b/book/external/Sphinx-launch-buttons index ccec26f..5acbe14 160000 --- a/book/external/Sphinx-launch-buttons +++ b/book/external/Sphinx-launch-buttons @@ -1 +1 @@ -Subproject commit ccec26fd77d3b6f1bb3415b5eb824b3155a397f1 +Subproject commit 5acbe14ac0bfa4ab532b9b7c64e6462f16a7dbda diff --git a/book/external/Useful_python_code b/book/external/Useful_python_code index 7fbdbbf..1fb335f 160000 --- a/book/external/Useful_python_code +++ b/book/external/Useful_python_code @@ -1 +1 @@ -Subproject commit 7fbdbbf720c27112fb58bcf7826225197e39357b +Subproject commit 1fb335fb81ec9b88186161352f379e315a19d2f8 diff --git a/book/external/annotater b/book/external/annotater index 9340b4e..832cee0 160000 --- a/book/external/annotater +++ b/book/external/annotater @@ -1 +1 @@ -Subproject commit 9340b4e2856b6f2de331c31d2b74bd9dc286d276 +Subproject commit 832cee034927c9a51efd328e6e1d5c9157b94e32 diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow index 26afa87..4415690 160000 --- a/book/external/deploy-book-workflow +++ b/book/external/deploy-book-workflow @@ -1 +1 @@ -Subproject commit 26afa87f90a4191de0e07f89c6de674ea8b81b8d +Subproject commit 44156900a23360478983a0920340ff2298110b78 diff --git a/book/external/sphinx-iframes b/book/external/sphinx-iframes index 077ba23..0ebb0ed 160000 --- a/book/external/sphinx-iframes +++ b/book/external/sphinx-iframes @@ -1 +1 @@ -Subproject commit 077ba23fa29ef1f0dd454f2ebf93c107923d1068 +Subproject commit 0ebb0edea5f14144c6548e417f5b79c6d7721d77 diff --git a/book/external/teachbooks-sphinx-tippy b/book/external/teachbooks-sphinx-tippy index 338ad14..e37225d 160000 --- a/book/external/teachbooks-sphinx-tippy +++ b/book/external/teachbooks-sphinx-tippy @@ -1 +1 @@ -Subproject commit 338ad14d39115c620c57476931ce8fa177cf20d8 +Subproject commit e37225de883df69e0933849dfc4880d41e7c75b0 diff --git a/book/external/template b/book/external/template index 82b2de6..17b99b2 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit 82b2de6a80b824482dd38f350a9aaf5f4a7a5fe0 +Subproject commit 17b99b2de4edbcbf4d8a92fed52c3d335431699b diff --git a/book/installation-and-setup/copyright.md b/book/installation-and-setup/copyright.md index f825244..1deaa0d 100644 --- a/book/installation-and-setup/copyright.md +++ b/book/installation-and-setup/copyright.md @@ -1,7 +1,10 @@ (copyright)= # Copyright and Licenses checklist -> This page reuses adapted CC BY content from the TU Delft Library. {cite:p}`tud_cip_24`. {fa}`quote-left`{ref}`Find out more here.<external_resources>` +```{attributiongrey} Attribution +:class: attribution +This page reuses adapted CC BY content from the TU Delft Library. {cite:p}`tud_cip_24`. {fa}`quote-left`{ref}`Find out more here.<external_resources>` +``` ```{admonition} User types :class: tip diff --git a/book/installation-and-setup/copyright/considerations.md b/book/installation-and-setup/copyright/considerations.md index b507d7f..80fa6aa 100644 --- a/book/installation-and-setup/copyright/considerations.md +++ b/book/installation-and-setup/copyright/considerations.md @@ -1,7 +1,10 @@ (copyright_considerations)= # Copyright Considerations -> This page reuses adapted CC BY content from {cite:t}`tud_cip_24`. {fa}`quote-left`{ref}`Find out more here.<external_resources>` +```{attributiongrey} Attribution +:class: attribution +This page reuses adapted CC BY content from {cite:t}`tud_cip_24`. {fa}`quote-left`{ref}`Find out more here.<external_resources>` +``` Copyright law dictates how online book material can and should be created, maintained and shared. An author should understand a few key concepts, as well as best practices, in order to create a book that not only is a useful resource, but, also fairly reuses the work of others and, if provided with an open license, enables original content to also be reused. diff --git a/book/installation-and-setup/copyright/licenses.md b/book/installation-and-setup/copyright/licenses.md index 40fb5d7..1cd3f4d 100644 --- a/book/installation-and-setup/copyright/licenses.md +++ b/book/installation-and-setup/copyright/licenses.md @@ -1,7 +1,10 @@ (copyright_licenses)= # Licenses -> This page reuses adapted CC BY content from {cite:t}`hall21`. {fa}`quote-left`{ref}`Find out more here.<external_resources>` +```{attributiongrey} Attribution +:class: attribution +This page reuses adapted CC BY content from {cite:t}`hall21`. {fa}`quote-left`{ref}`Find out more here.<external_resources>` +``` Here we present an overview of various license types, with a particular focus on the preference of TeachBooks to use Permissive Open Licenses, regardless of whether material is _content, code or data_ (described below). diff --git a/book/installation-and-setup/copyright/recommendations.md b/book/installation-and-setup/copyright/recommendations.md index 16ea6b8..118283a 100644 --- a/book/installation-and-setup/copyright/recommendations.md +++ b/book/installation-and-setup/copyright/recommendations.md @@ -52,20 +52,67 @@ Note that there are several types of pages and files that can be incorporated in (copyright_recc_content)= ### Content Pages -Make sure you show the source of your content where it is provided. We adopt a standard icon and link to help readers recognize this: {fa}`quote-left`{ref}`Find out more here.<external_resources>` +Make sure you show the source of your content where it is provided. We adopt a standard icon and link to help readers recognize this: {fa}`quote-left`{ref}`Find out more here.<external_resources>`. This can be used to provide attribution to authors for specific pages too #### How to implement this in your book -Copy the following line into your content file -```md -> This page reuses <license> content from {cite:t}`bib_id`. {fa}`quote-left`{ref}`Find out more here.<link to external resources section on credits and license page>` -``` - Some examples can be found in this manual: - [](../../external/deploy-book-workflow/README.md): a content page which is taken fully from another repository - Figure {ref}`fig_license_types`: a single licensed figure added to a page taken from another website - [](../copyright.md): a content page which adapts material from another website +##### Format as citation +Copy the following line into your content file + +```md +> Written by `<author(s)>` +> This page reuses <license> content from {cite:t}`bib_id`. {fa}`quote-left`{ref}`Find out more here.<link to external resources section on credits and license page>` +``` + +This produces + +> This page reuses CC BY content from {cite:t}`jason_moore`. {fa}`quote-left`{ref}`Find out more here.<external_resources>` + +##### Format as custom admonition +The previous syntax might be used for other purposes as well. An alternative is a custom attribution admonition: + +```{attributiongrey} Attribution +:class: attribution +This page reuses CC BY 4.0 licensed content from {cite:t}`jason_moore`. {fa}`quote-left`{ref}`Find out more here.<external_resources>` +``` + +Therefore, use the following syntax: + +`````md +```{attributiongrey} Attribution +:class: attribution +Written by <author(s)> +This page reuses <license> content from {cite:t}`bib_id`. {fa}`quote-left`{ref}`Find out more here.<link to external resources section on credits and license page>` +``` +````` + +Or to place this attribution in the margin: + +````{margin} +```{attributiongrey} Attribution +:class: attribution +Written by <author(s)> +This page reuses <license> content from {cite:t}`bib_id`. {fa}`quote-left`{ref}`Find out more here.<link to external resources section on credits and license page>` +``` +```` + +`````md +````{margin} +```{attributiongrey} Attribution +:class: attribution +Written by <author(s)> +This page reuses <license> content from {cite:t}`bib_id`. {fa}`quote-left`{ref}`Find out more here.<link to external resources section on credits and license page>` +``` +```` +````` +To make this possible we use the custom admonitions of [the custom named colors sphinx extension](https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html#admonitions) in combination with a [custom css file](../../_static/attribution.css) in `book/_static/` and the line `named_colors_custom_colors: {'attributiongrey':[150,150,150]}` in `book/_config.yml` under `sphinx: config: ` + + (copyright_recc_credits)= ### Credits and License Page diff --git a/book/references.bib b/book/references.bib index 3b54aed..fd81c05 100644 --- a/book/references.bib +++ b/book/references.bib @@ -142,3 +142,19 @@ year = {2025}, note = {Retrieved February 2025. CC BY 3.0.} } + +@misc{sphinx-iframes, + author = {{TeachBooks}}, + title = {Sphinx iframes}, + url = {https://github.com/TeachBooks/sphinx-iframes}, + year = {2025}, + note = {Retrieved April 2025. MIT.} +} + +@misc{sphinx-prime-applets, + author = {{TeachBooks}}, + title = {Sphinx PRIME applets}, + url = {https://github.com/TeachBooks/Sphinx-PRIME-applets}, + year = {2025}, + note = {Retrieved April 2025. MIT.} +} \ No newline at end of file From 0c579a229af31afb1d7391039bc1b3e1548ef4e5 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 1 Apr 2025 13:47:03 +0200 Subject: [PATCH 38/41] attribution in margin --- book/external/annotater | 2 +- book/installation-and-setup/copyright/recommendations.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/book/external/annotater b/book/external/annotater index 832cee0..ff37537 160000 --- a/book/external/annotater +++ b/book/external/annotater @@ -1 +1 @@ -Subproject commit 832cee034927c9a51efd328e6e1d5c9157b94e32 +Subproject commit ff3753731bd65f4351fb09e88327aba15383b1d2 diff --git a/book/installation-and-setup/copyright/recommendations.md b/book/installation-and-setup/copyright/recommendations.md index 118283a..0f446ca 100644 --- a/book/installation-and-setup/copyright/recommendations.md +++ b/book/installation-and-setup/copyright/recommendations.md @@ -97,7 +97,7 @@ Or to place this attribution in the margin: ```{attributiongrey} Attribution :class: attribution Written by <author(s)> -This page reuses <license> content from {cite:t}`bib_id`. {fa}`quote-left`{ref}`Find out more here.<link to external resources section on credits and license page>` +This page reuses CC BY 4.0 licensed content from {cite:t}`jason_moore`. {fa}`quote-left`{ref}`Find out more here.<external_resources>` ``` ```` From 748f68d6d9523b48bf78fb744a5f250986a26ca4 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 1 Apr 2025 13:57:19 +0200 Subject: [PATCH 39/41] attributions in margin --- book/external/Download-Link-Replacer | 2 +- book/external/JupyterBook-Patches | 2 +- book/external/Nested-Books | 2 +- book/external/Sphinx-Grasple-public | 2 +- book/external/Sphinx-Image-Inverter | 2 +- book/external/Sphinx-Named-Colors | 2 +- book/external/Sphinx-PRIME-applets | 2 +- book/external/Sphinx-TUDelft-theme | 2 +- book/external/Sphinx-launch-buttons | 2 +- book/external/Useful_python_code | 2 +- book/external/annotater | 2 +- book/external/deploy-book-workflow | 2 +- book/external/sphinx-iframes | 2 +- book/external/teachbooks-sphinx-tippy | 2 +- book/installation-and-setup/copyright.md | 9 +++++--- .../copyright/considerations.md | 10 ++++++--- .../copyright/licenses.md | 8 ++++--- .../copyright/recommendations.md | 22 ++++--------------- 18 files changed, 36 insertions(+), 41 deletions(-) diff --git a/book/external/Download-Link-Replacer b/book/external/Download-Link-Replacer index b658d1c..6318fd9 160000 --- a/book/external/Download-Link-Replacer +++ b/book/external/Download-Link-Replacer @@ -1 +1 @@ -Subproject commit b658d1c6e1791097b225357025ebe7267d4dccb5 +Subproject commit 6318fd9db4b465bf56b06085ca55c79a8a818471 diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches index 1a8e996..8346c8c 160000 --- a/book/external/JupyterBook-Patches +++ b/book/external/JupyterBook-Patches @@ -1 +1 @@ -Subproject commit 1a8e9960f0a37ce210df51198e0079430f1a2c6e +Subproject commit 8346c8c3c8be3d221a62a2f18c4ee1d4570ee003 diff --git a/book/external/Nested-Books b/book/external/Nested-Books index dcdecc4..70dfd28 160000 --- a/book/external/Nested-Books +++ b/book/external/Nested-Books @@ -1 +1 @@ -Subproject commit dcdecc4a7335163ce0f5a8975bfd366a17d5fb94 +Subproject commit 70dfd28f5f288118bb75d219b809f03474aa89a2 diff --git a/book/external/Sphinx-Grasple-public b/book/external/Sphinx-Grasple-public index e13743c..ce057a2 160000 --- a/book/external/Sphinx-Grasple-public +++ b/book/external/Sphinx-Grasple-public @@ -1 +1 @@ -Subproject commit e13743c7dd2d1de8a0dd7137da2841344ea0f330 +Subproject commit ce057a20bb234006ddebc80c9894842d125a5b1b diff --git a/book/external/Sphinx-Image-Inverter b/book/external/Sphinx-Image-Inverter index 8365d4a..573bb66 160000 --- a/book/external/Sphinx-Image-Inverter +++ b/book/external/Sphinx-Image-Inverter @@ -1 +1 @@ -Subproject commit 8365d4a366433bbbdfe7d7d0fbd617270c0e7130 +Subproject commit 573bb66332f682bdfe1d7936048780199e4a0e2d diff --git a/book/external/Sphinx-Named-Colors b/book/external/Sphinx-Named-Colors index 6c5a0f4..b4b1a2e 160000 --- a/book/external/Sphinx-Named-Colors +++ b/book/external/Sphinx-Named-Colors @@ -1 +1 @@ -Subproject commit 6c5a0f4aa9a11b0ba9d5a8f68929ba5773c3312a +Subproject commit b4b1a2e5d087336108bc15b176af1999b61dc86a diff --git a/book/external/Sphinx-PRIME-applets b/book/external/Sphinx-PRIME-applets index 29b5b48..14dc36b 160000 --- a/book/external/Sphinx-PRIME-applets +++ b/book/external/Sphinx-PRIME-applets @@ -1 +1 @@ -Subproject commit 29b5b48126fadde3839ef20a6256bdbda72d4ef9 +Subproject commit 14dc36bfdbf89d2d363ea2bdcbc30a64c0f7b00f diff --git a/book/external/Sphinx-TUDelft-theme b/book/external/Sphinx-TUDelft-theme index 5f26d31..103caec 160000 --- a/book/external/Sphinx-TUDelft-theme +++ b/book/external/Sphinx-TUDelft-theme @@ -1 +1 @@ -Subproject commit 5f26d318bf0696229041d20518900695d6ff935f +Subproject commit 103caecd4844353c68c166fa6ebed24a868c848c diff --git a/book/external/Sphinx-launch-buttons b/book/external/Sphinx-launch-buttons index 5acbe14..f6435cb 160000 --- a/book/external/Sphinx-launch-buttons +++ b/book/external/Sphinx-launch-buttons @@ -1 +1 @@ -Subproject commit 5acbe14ac0bfa4ab532b9b7c64e6462f16a7dbda +Subproject commit f6435cb0a795062a7d695a246a332ff79f3f74b9 diff --git a/book/external/Useful_python_code b/book/external/Useful_python_code index 1fb335f..81e9235 160000 --- a/book/external/Useful_python_code +++ b/book/external/Useful_python_code @@ -1 +1 @@ -Subproject commit 1fb335fb81ec9b88186161352f379e315a19d2f8 +Subproject commit 81e923516e06441fb0c04f4946819f5dae9b0a68 diff --git a/book/external/annotater b/book/external/annotater index ff37537..d1f41f9 160000 --- a/book/external/annotater +++ b/book/external/annotater @@ -1 +1 @@ -Subproject commit ff3753731bd65f4351fb09e88327aba15383b1d2 +Subproject commit d1f41f93ffe87a305956de405dac47daaad3bc69 diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow index 4415690..ea450f3 160000 --- a/book/external/deploy-book-workflow +++ b/book/external/deploy-book-workflow @@ -1 +1 @@ -Subproject commit 44156900a23360478983a0920340ff2298110b78 +Subproject commit ea450f3c0c4f9aba6438333c122543fca02c472d diff --git a/book/external/sphinx-iframes b/book/external/sphinx-iframes index 0ebb0ed..062c54a 160000 --- a/book/external/sphinx-iframes +++ b/book/external/sphinx-iframes @@ -1 +1 @@ -Subproject commit 0ebb0edea5f14144c6548e417f5b79c6d7721d77 +Subproject commit 062c54a679c6dd44b948549498e755c7c5df1d73 diff --git a/book/external/teachbooks-sphinx-tippy b/book/external/teachbooks-sphinx-tippy index e37225d..e4166e1 160000 --- a/book/external/teachbooks-sphinx-tippy +++ b/book/external/teachbooks-sphinx-tippy @@ -1 +1 @@ -Subproject commit e37225de883df69e0933849dfc4880d41e7c75b0 +Subproject commit e4166e1389ab48ea9059e6576e56d270e66199dd diff --git a/book/installation-and-setup/copyright.md b/book/installation-and-setup/copyright.md index 1deaa0d..82b60a0 100644 --- a/book/installation-and-setup/copyright.md +++ b/book/installation-and-setup/copyright.md @@ -1,6 +1,4 @@ -(copyright)= -# Copyright and Licenses checklist - +````{margin} ```{attributiongrey} Attribution :class: attribution This page reuses adapted CC BY content from the TU Delft Library. {cite:p}`tud_cip_24`. {fa}`quote-left`{ref}`Find out more here.<external_resources>` @@ -10,6 +8,11 @@ This page reuses adapted CC BY content from the TU Delft Library. {cite:p}`tud_c :class: tip This page is useful for all user types. ``` +```` + +(copyright)= +# Copyright and Licenses checklist + The previous sections have familiarized you with the necessary software for your user type, the basics of Git, and how to collaborate with your team using Git. Now it's time to create your own content. This section will provide an overview of the copy right laws which need to be taking into account when creating and including content at TU Delft! diff --git a/book/installation-and-setup/copyright/considerations.md b/book/installation-and-setup/copyright/considerations.md index 80fa6aa..4180108 100644 --- a/book/installation-and-setup/copyright/considerations.md +++ b/book/installation-and-setup/copyright/considerations.md @@ -1,10 +1,14 @@ -(copyright_considerations)= -# Copyright Considerations - +````{margin} ```{attributiongrey} Attribution :class: attribution This page reuses adapted CC BY content from {cite:t}`tud_cip_24`. {fa}`quote-left`{ref}`Find out more here.<external_resources>` ``` +```` + +(copyright_considerations)= +# Copyright Considerations + + Copyright law dictates how online book material can and should be created, maintained and shared. An author should understand a few key concepts, as well as best practices, in order to create a book that not only is a useful resource, but, also fairly reuses the work of others and, if provided with an open license, enables original content to also be reused. diff --git a/book/installation-and-setup/copyright/licenses.md b/book/installation-and-setup/copyright/licenses.md index 1cd3f4d..05033af 100644 --- a/book/installation-and-setup/copyright/licenses.md +++ b/book/installation-and-setup/copyright/licenses.md @@ -1,10 +1,12 @@ -(copyright_licenses)= -# Licenses - +````{margin} ```{attributiongrey} Attribution :class: attribution This page reuses adapted CC BY content from {cite:t}`hall21`. {fa}`quote-left`{ref}`Find out more here.<external_resources>` ``` +```` + +(copyright_licenses)= +# Licenses Here we present an overview of various license types, with a particular focus on the preference of TeachBooks to use Permissive Open Licenses, regardless of whether material is _content, code or data_ (described below). diff --git a/book/installation-and-setup/copyright/recommendations.md b/book/installation-and-setup/copyright/recommendations.md index 0f446ca..c018533 100644 --- a/book/installation-and-setup/copyright/recommendations.md +++ b/book/installation-and-setup/copyright/recommendations.md @@ -76,31 +76,16 @@ This produces ##### Format as custom admonition The previous syntax might be used for other purposes as well. An alternative is a custom attribution admonition: +````{margin} ```{attributiongrey} Attribution :class: attribution +Written by <author(s)> This page reuses CC BY 4.0 licensed content from {cite:t}`jason_moore`. {fa}`quote-left`{ref}`Find out more here.<external_resources>` ``` +```` Therefore, use the following syntax: -`````md -```{attributiongrey} Attribution -:class: attribution -Written by <author(s)> -This page reuses <license> content from {cite:t}`bib_id`. {fa}`quote-left`{ref}`Find out more here.<link to external resources section on credits and license page>` -``` -````` - -Or to place this attribution in the margin: - -````{margin} -```{attributiongrey} Attribution -:class: attribution -Written by <author(s)> -This page reuses CC BY 4.0 licensed content from {cite:t}`jason_moore`. {fa}`quote-left`{ref}`Find out more here.<external_resources>` -``` -```` - `````md ````{margin} ```{attributiongrey} Attribution @@ -110,6 +95,7 @@ This page reuses <license> content from {cite:t}`bib_id`. {fa}`quote-left`{ref}` ``` ```` ````` + To make this possible we use the custom admonitions of [the custom named colors sphinx extension](https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html#admonitions) in combination with a [custom css file](../../_static/attribution.css) in `book/_static/` and the line `named_colors_custom_colors: {'attributiongrey':[150,150,150]}` in `book/_config.yml` under `sphinx: config: ` From ae4f209be2f67375328ede3bafae4e922dc2fbca Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg <t.r.vanwoudenberg@tudelft.nl> Date: Tue, 1 Apr 2025 15:00:43 +0200 Subject: [PATCH 40/41] 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 <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. 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 <svg aria-label="Edit repository metadata" role="img" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-gear float-right"> <path d="M8 0a8.2 8.2 0 0 1 .701.031C9.444.095 9.99.645 10.16 1.29l.288 1.107c.018.066.079.158.212.224.231.114.454.243.668.386.123.082.233.09.299.071l1.103-.303c.644-.176 1.392.021 1.82.63.27.385.506.792.704 1.218.315.675.111 1.422-.364 1.891l-.814.806c-.049.048-.098.147-.088.294.016.257.016.515 0 .772-.01.147.038.246.088.294l.814.806c.475.469.679 1.216.364 1.891a7.977 7.977 0 0 1-.704 1.217c-.428.61-1.176.807-1.82.63l-1.102-.302c-.067-.019-.177-.011-.3.071a5.909 5.909 0 0 1-.668.386c-.133.066-.194.158-.211.224l-.29 1.106c-.168.646-.715 1.196-1.458 1.26a8.006 8.006 0 0 1-1.402 0c-.743-.064-1.289-.614-1.458-1.26l-.289-1.106c-.018-.066-.079-.158-.212-.224a5.738 5.738 0 0 1-.668-.386c-.123-.082-.233-.09-.299-.071l-1.103.303c-.644.176-1.392-.021-1.82-.63a8.12 8.12 0 0 1-.704-1.218c-.315-.675-.111-1.422.363-1.891l.815-.806c.05-.048.098-.147.088-.294a6.214 6.214 0 0 1 0-.772c.01-.147-.038-.246-.088-.294l-.815-.806C.635 6.045.431 5.298.746 4.623a7.92 7.92 0 0 1 .704-1.217c.428-.61 1.176-.807 1.82-.63l1.102.302c.067.019.177.011.3-.071.214-.143.437-.272.668-.386.133-.066.194-.158.211-.224l.29-1.106C6.009.645 6.556.095 7.299.03 7.53.01 7.764 0 8 0Zm-.571 1.525c-.036.003-.108.036-.137.146l-.289 1.105c-.147.561-.549.967-.998 1.189-.173.086-.34.183-.5.29-.417.278-.97.423-1.529.27l-1.103-.303c-.109-.03-.175.016-.195.045-.22.312-.412.644-.573.99-.014.031-.021.11.059.19l.815.806c.411.406.562.957.53 1.456a4.709 4.709 0 0 0 0 .582c.032.499-.119 1.05-.53 1.456l-.815.806c-.081.08-.073.159-.059.19.162.346.353.677.573.989.02.03.085.076.195.046l1.102-.303c.56-.153 1.113-.008 1.53.27.161.107.328.204.501.29.447.222.85.629.997 1.189l.289 1.105c.029.109.101.143.137.146a6.6 6.6 0 0 0 1.142 0c.036-.003.108-.036.137-.146l.289-1.105c.147-.561.549-.967.998-1.189.173-.086.34-.183.5-.29.417-.278.97-.423 1.529-.27l1.103.303c.109.029.175-.016.195-.045.22-.313.411-.644.573-.99.014-.031.021-.11-.059-.19l-.815-.806c-.411-.406-.562-.957-.53-1.456a4.709 4.709 0 0 0 0-.582c-.032-.499.119-1.05.53-1.456l.815-.806c.081-.08.073-.159.059-.19a6.464 6.464 0 0 0-.573-.989c-.02-.03-.085-.076-.195-.046l-1.102.303c-.56.153-1.113.008-1.53-.27a4.44 4.44 0 0 0-.501-.29c-.447-.222-.85-.629-.997-1.189l-.289-1.105c-.029-.11-.101-.143-.137-.146a6.6 6.6 0 0 0-1.142 0ZM11 8a3 3 0 1 1-6 0 3 3 0 0 1 6 0ZM9.5 8a1.5 1.5 0 1 0-3.001.001A1.5 1.5 0 0 0 9.5 8Z"></path> </svg>`Settings` - <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-browser"> <path d="M0 2.75C0 1.784.784 1 1.75 1h12.5c.966 0 1.75.784 1.75 1.75v10.5A1.75 1.75 0 0 1 14.25 15H1.75A1.75 1.75 0 0 1 0 13.25ZM14.5 6h-13v7.25c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25Zm-6-3.5v2h6V2.75a.25.25 0 0 0-.25-.25ZM5 2.5v2h2v-2Zm-3.25 0a.25.25 0 0 0-.25.25V4.5h2v-2Z"></path> </svg> `Pages` - `Build and deployment` - `Source` - `GitHub Actions`. Additional tip: set repository website as your GitHub Pages website under <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-code UnderlineNav-octicon d-none d-sm-inline"> <path d="m11.28 3.22 4.25 4.25a.75.75 0 0 1 0 1.06l-4.25 4.25a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L13.94 8l-3.72-3.72a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215Zm-6.56 0a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042L2.06 8l3.72 3.72a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L.47 8.53a.75.75 0 0 1 0-1.06Z"></path></svg>`Code`- `About` - <svg aria-label="Edit repository metadata" role="img" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-gear float-right"> <path d="M8 0a8.2 8.2 0 0 1 .701.031C9.444.095 9.99.645 10.16 1.29l.288 1.107c.018.066.079.158.212.224.231.114.454.243.668.386.123.082.233.09.299.071l1.103-.303c.644-.176 1.392.021 1.82.63.27.385.506.792.704 1.218.315.675.111 1.422-.364 1.891l-.814.806c-.049.048-.098.147-.088.294.016.257.016.515 0 .772-.01.147.038.246.088.294l.814.806c.475.469.679 1.216.364 1.891a7.977 7.977 0 0 1-.704 1.217c-.428.61-1.176.807-1.82.63l-1.102-.302c-.067-.019-.177-.011-.3.071a5.909 5.909 0 0 1-.668.386c-.133.066-.194.158-.211.224l-.29 1.106c-.168.646-.715 1.196-1.458 1.26a8.006 8.006 0 0 1-1.402 0c-.743-.064-1.289-.614-1.458-1.26l-.289-1.106c-.018-.066-.079-.158-.212-.224a5.738 5.738 0 0 1-.668-.386c-.123-.082-.233-.09-.299-.071l-1.103.303c-.644.176-1.392-.021-1.82-.63a8.12 8.12 0 0 1-.704-1.218c-.315-.675-.111-1.422.363-1.891l.815-.806c.05-.048.098-.147.088-.294a6.214 6.214 0 0 1 0-.772c.01-.147-.038-.246-.088-.294l-.815-.806C.635 6.045.431 5.298.746 4.623a7.92 7.92 0 0 1 .704-1.217c.428-.61 1.176-.807 1.82-.63l1.102.302c.067.019.177.011.3-.071.214-.143.437-.272.668-.386.133-.066.194-.158.211-.224l.29-1.106C6.009.645 6.556.095 7.299.03 7.53.01 7.764 0 8 0Zm-.571 1.525c-.036.003-.108.036-.137.146l-.289 1.105c-.147.561-.549.967-.998 1.189-.173.086-.34.183-.5.29-.417.278-.97.423-1.529.27l-1.103-.303c-.109-.03-.175.016-.195.045-.22.312-.412.644-.573.99-.014.031-.021.11.059.19l.815.806c.411.406.562.957.53 1.456a4.709 4.709 0 0 0 0 .582c.032.499-.119 1.05-.53 1.456l-.815.806c-.081.08-.073.159-.059.19.162.346.353.677.573.989.02.03.085.076.195.046l1.102-.303c.56-.153 1.113-.008 1.53.27.161.107.328.204.501.29.447.222.85.629.997 1.189l.289 1.105c.029.109.101.143.137.146a6.6 6.6 0 0 0 1.142 0c.036-.003.108-.036.137-.146l.289-1.105c.147-.561.549-.967.998-1.189.173-.086.34-.183.5-.29.417-.278.97-.423 1.529-.27l1.103.303c.109.029.175-.016.195-.045.22-.313.411-.644.573-.99.014-.031.021-.11-.059-.19l-.815-.806c-.411-.406-.562-.957-.53-1.456a4.709 4.709 0 0 0 0-.582c-.032-.499.119-1.05.53-1.456l.815-.806c.081-.08.073-.159.059-.19a6.464 6.464 0 0 0-.573-.989c-.02-.03-.085-.076-.195-.046l-1.102.303c-.56.153-1.113.008-1.53-.27a4.44 4.44 0 0 0-.501-.29c-.447-.222-.85-.629-.997-1.189l-.289-1.105c-.029-.11-.101-.143-.137-.146a6.6 6.6 0 0 0-1.142 0ZM11 8a3 3 0 1 1-6 0 3 3 0 0 1 6 0ZM9.5 8a1.5 1.5 0 1 0-3.001.001A1.5 1.5 0 0 0 9.5 8Z"></path> </svg> - `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 <svg aria-hidden="true" height="16" viewBox="0 0 16 16" version="1.1" width="16" data-view-component="true" class="octicon octicon-play UnderlineNav-octicon d-none d-sm-inline"> - <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"></path> -</svg>`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://<username/organization_name>.github.io/<repository_name>` (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 <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.<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: 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 <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. 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. From 19f579147113ea843e8c50cbef5366a08eee30e7 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 1 Apr 2025 19:41:54 +0000 Subject: [PATCH 41/41] Bump book/external/Sphinx-launch-buttons from `f6435cb` to `e6070de` Bumps [book/external/Sphinx-launch-buttons](https://github.com/TeachBooks/Sphinx-launch-buttons) from `f6435cb` to `e6070de`. - [Release notes](https://github.com/TeachBooks/Sphinx-launch-buttons/releases) - [Commits](https://github.com/TeachBooks/Sphinx-launch-buttons/compare/f6435cb0a795062a7d695a246a332ff79f3f74b9...e6070ded6ca77662a3a951893cafe265fa333e5e) --- updated-dependencies: - dependency-name: book/external/Sphinx-launch-buttons dependency-version: e6070ded6ca77662a3a951893cafe265fa333e5e dependency-type: direct:production ... Signed-off-by: dependabot[bot] <support@github.com> --- book/external/Sphinx-launch-buttons | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/external/Sphinx-launch-buttons b/book/external/Sphinx-launch-buttons index f6435cb..e6070de 160000 --- a/book/external/Sphinx-launch-buttons +++ b/book/external/Sphinx-launch-buttons @@ -1 +1 @@ -Subproject commit f6435cb0a795062a7d695a246a332ff79f3f74b9 +Subproject commit e6070ded6ca77662a3a951893cafe265fa333e5e