diff --git a/.gitmodules b/.gitmodules index d1f5f7a..64687ac 100644 --- a/.gitmodules +++ b/.gitmodules @@ -7,3 +7,9 @@ [submodule "book/external/deploy-book-workflow"] path = book/external/deploy-book-workflow url = https://github.com/TeachBooks/deploy-book-workflow.git +[submodule "book/external/latex-to-markdown-conversion"] + path = book/external/latex-to-markdown-conversion + url = https://gitlab.tudelft.nl/opentextbooks/latex-to-markdown-conversion.git +[submodule "book/external/Useful_python_code"] + path = book/external/Useful_python_code + url = https://github.com/TeachBooks/Useful_python_code.git diff --git a/README.md b/README.md index d3d93c6..34c44ef 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,6 @@ A short introduction to Git, VSCode and Jupyter Books for teachers and TA's. Cur ## Contributing -Feedback is always welcome. If something doesn't work, or if you have suggestions, you can always make an issue on the Issue Board or make a Merge Request. +Feedback is always welcome. If something doesn't work, or if you have suggestions, you can always make an issue on the Issue Board or make a Merge Request. If you create a branch, that branch will also be visible on the mirrored repository on GitHub to ease reviewing: https://github.com/TeachBooks/mirror_teachbook_manual/actions If you've questions, contact Tom van Woudenberg, Robert Lanzafame or our TAs Julie Kirsch at TeachBooks@tudelft.nl, also for non-TU Delft account holders. TU Delft account holder can also contact us in the [MS Teams Open Interactive Textbooks Community](https://teams.microsoft.com/l/team/19%3Ah9-uRcP_yYauh-VuoPFozJVUvHVOB4a0mz1ZWvh4q4Q1%40thread.tacv2/conversations?groupId=3e88c1f3-4a4f-483a-a366-7e617de9ba99&tenantId=096e524d-6929-4030-8cd3-8ab42de0887b) \ No newline at end of file diff --git a/book/_config.yml b/book/_config.yml index c43c908..ebffffa 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -6,6 +6,8 @@ logo: images/Logo_without_background.png execute: execute_notebooks: 'off' +only_build_toc_files: true + html: favicon : "images/favicon.ico" baseurl : "https://teachbooks.tudelft.nl/jupyter-book-manual/" diff --git a/book/_toc.yml b/book/_toc.yml index f4f86e0..d867e2e 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -60,7 +60,6 @@ parts: sections: - file: features/jupyterlite/configuration - file: features/jupyterlite/including-jupyterlite - - caption: Examples chapters: @@ -70,6 +69,20 @@ parts: - file: examples/live_code.md - file: examples/example_gumbel.ipynb - file: examples/theory_questions.md - - file: examples/example_quiz_interactive.ipynb - - file: examples/coding_theory_widgets.ipynb - - file: examples/parametric_questions.ipynb \ No newline at end of file + - file: examples/interactive_templates.md + sections: + - file: examples/example_gumbel.ipynb + - file: examples/example_quiz_interactive.ipynb + - file: examples/coding_theory_widgets.ipynb + - file: examples/parametric_questions.ipynb + + - caption: Editing tools + chapters: + - file: tools/figmaker + - file: helper_code/intro.md + sections: + - file: external/latex-to-markdown-conversion/README.md + - file: external/Useful_python_code/snippit.ipynb + - file: external/Useful_python_code/extensionfildownloadreturn.ipynb + - file: external/Useful_python_code/figshrinker.ipynb + \ No newline at end of file diff --git a/book/basic-features/References.md b/book/basic-features/References.md index d48c47c..b5eeaba 100644 --- a/book/basic-features/References.md +++ b/book/basic-features/References.md @@ -2,6 +2,24 @@ To make references to figures, equations et cetera, use the following syntax: -- For figures, use: ``{numref}`` `` +- For figures, use: ``{numref}`Figure {number} ` `` - For equations, use: ``{eq}`` `` - For citations, use: ``{cite:p}`` `` for a citation between parenthesis, or ``{cite:t}`` `` for an inline citation. + +**Examples** + +Using ``{numref}`Figure {number} ` `` produces the output: {numref}`Figure {number} `. +```{figure} ../images/git-push.png +--- +width: 50% +name: fig-gitpush +--- +Some caption here +``` + +Or, the derivation results in equation {eq}``. + +$$ F = m\cdot a $$(eq:Newton) + + + diff --git a/book/basic-features/equations.md b/book/basic-features/equations.md index 5e680ce..89c5a4e 100644 --- a/book/basic-features/equations.md +++ b/book/basic-features/equations.md @@ -14,6 +14,12 @@ $$ F = m \cdot a $$ +```{tip} +The scientific rules dictate that quantities ($F$, $m$, $a$ etc.) should be printed in italics. Units, however, should not! One can use `\text{m}` in an equation to comply to this rule: + +$$ F = m \cdot a = 10 \cdot 9.81 = 98 \text{N} +``` + > **Warning** > > Make sure there is a blank line *before* the display mode equations, otherwise it will render as inline and display the outer set of $$$ symbols. Also, the Euro symbol is not included in MathJax (see note below) and must be specified using `\unicode{0x20AC}` (note that it displays incorrectly in some Markdown renderers like VS Code). @@ -24,6 +30,12 @@ To number the equations and refer in text, you need to provide a label to the eq F = m \cdot a $$ (newtons_second_law) +Resulting in: + +$$ + F = m \cdot a +$$ (newtons_second_law) + > **Note** > > The Jupyter Book uses MathJax to display equations, which provides some LaTeX-like functionality, but not all! For example, the Euro symbol is missing, and packages like `siunitx` are not available (hint, use `\textrm{}` and `\textrm{}`). When something is not working, it's useful to search for MathJax-specific solutions (hint, include "mathjax" in your Google search). diff --git a/book/basic-features/figures.md b/book/basic-features/figures.md index 1c3f562..8fcf942 100644 --- a/book/basic-features/figures.md +++ b/book/basic-features/figures.md @@ -131,13 +131,3 @@ name: demoexample4 example 4:including figclass: margin ``` -## 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/basic-features/jupyterbook.md b/book/basic-features/jupyterbook.md index 3758da2..047b3d7 100644 --- a/book/basic-features/jupyterbook.md +++ b/book/basic-features/jupyterbook.md @@ -7,7 +7,7 @@ To build a Jupyter Book, you need three things: 3. Content ## The configuration file -The configuration file of Jupyter Books is named `_config.yml`. It mainly contains settings that apply when building the book. Here is a basic example of a configuration file, taken from this book: +The configuration file of Jupyter Books is named `_config.yml`. It mainly contains settings that apply when building the book. Here is a basic example of a configuration file, taken from this book: ```yml title: Jupyter Book Manual @@ -83,4 +83,32 @@ parts: - file: section_3_1 et cetera... +``` + +## The structure of a chapter +The 'nested' structure in the TOC is one way to organize your book. Another way to do so is in the file itself. The structure is defined by the number of `#`: + +``` +# Chapter 1 title + +## Section 1.1 + +### Subsection 1.1.1 + +## Section 1.2 + +### Subsection 1.2.1 +``` + +The depth for numbered subsection can be set in the TOC file: + +``` +parts: +- caption: Part 1 + numbered: 2 + chapters: + - file: chapter_1 + sections: + - file: section_1_1 + - file: section_1_2 ``` \ No newline at end of file diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md index b2d5623..5472fda 100644 --- a/book/basic-features/overview.md +++ b/book/basic-features/overview.md @@ -2,7 +2,7 @@ ```{admonition} User types :class: tip -This section is useful for user type 3-6. +This section is useful for user type 3-5. ``` A short description on basic features is given here: diff --git a/book/external/Useful_python_code b/book/external/Useful_python_code new file mode 160000 index 0000000..c8327b3 --- /dev/null +++ b/book/external/Useful_python_code @@ -0,0 +1 @@ +Subproject commit c8327b3e2cc68d44958974a47c940bc89f4bb32b diff --git a/book/external/deploy-book-workflow b/book/external/deploy-book-workflow index d5eab25..081491b 160000 --- a/book/external/deploy-book-workflow +++ b/book/external/deploy-book-workflow @@ -1 +1 @@ -Subproject commit d5eab25a29e2cc558ec449577dab669c02758a11 +Subproject commit 081491b5f7bd0beecb5663228eaf5ab80b9dd57c diff --git a/book/external/latex-to-markdown-conversion b/book/external/latex-to-markdown-conversion new file mode 160000 index 0000000..0b9b651 --- /dev/null +++ b/book/external/latex-to-markdown-conversion @@ -0,0 +1 @@ +Subproject commit 0b9b6512da9ff9011e56897eb6837cc3ed89ee45 diff --git a/book/external/template b/book/external/template index 1d03339..2d5513d 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit 1d033396e8e38bb203c2db8210e5501b7099fcb1 +Subproject commit 2d5513da0a53b606f870890237ef4417dc18b398 diff --git a/book/helper_code/intro.md b/book/helper_code/intro.md new file mode 100644 index 0000000..8268cf1 --- /dev/null +++ b/book/helper_code/intro.md @@ -0,0 +1,10 @@ +# Scripts for automating workflow + +This chapter contains a few scripts which can be useful in the book-editing process: + - [LaTeX to markdown conversion](../external/latex-to-markdown-conversion/README.md) to convert a LaTeX file into jupyter-book compatible markdown. + - [Snippitall](Snippitall) to insert the same code snippet at a certain point in each md file in a specific folder and all subfolder. + - [Snippitonce](Snippitonce) to insert the same code snippet at a certain point in each md file only in a specific folder. + - [Extensionchecker](extensionchecker) to identify the kind of files present in subfolder + - [Filedownloader](filedownloader) to return the downloadlink for markdown for all files with a specified extension + - [Figreturner](figreturner) to return the markdown code for a figure in a specific extension + - [Figshrinker](../external/Useful_python_code/figshrinker.ipynb) to compress JPEG images. \ No newline at end of file diff --git a/book/installation-and-setup/organize-team.md b/book/installation-and-setup/organize-team.md index fee8b8d..4da66bc 100644 --- a/book/installation-and-setup/organize-team.md +++ b/book/installation-and-setup/organize-team.md @@ -19,12 +19,14 @@ If you want to create a collaborative book for students, there's a few agreement ## Tools - Choose between GitHub and GitLab, as explained below +- Choose whether to host your git repository in your private account or from a share teams (groups in GitLab, organization in GitHub). For GitHub this influences your book web url as well, as it hold your username or organization name. For courses we therefore advise you to create a organization with the course name. Furthermore, on GitHub a private repository has a limited amount of actions-minutes required for published your book. On GitLab, the choice for private or public doesn't influence your web url and the amount of computing power available as that requires you to set up a server yourself. +- Choose whether to have your git repository public or private (independent of whether your book website is public or private). If you'd like a private repo on GitHub, apply for a GitHub Team (free as a teacher as described in the [github documentation](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers)). If you've a organization for your book on github, link your GitHub team rights to your organization as described on the [github website](https://github.com/team#organizations) - If you've chosen for GitHub, start with our [template](../external/template/README.md) - Define branches in GitHub/GitLab. We advise the following branches: - - A published branch which contains the students' version of this year. This could be called ie. `publish` or `main` or `` - - A development branch which contains all the new content combined but not yet published to students. This could be called `dev` or `main` (depending on whether you prefer having the most recent published version as main or the development branch). - - Branches which will be created during the editing process which contain edits ie. single chapters - - Branches for previous study years which contain each year's version of the book. These could be called `` + - A published branch which contains the students' version of this year. This could be called ie. `publish` or `main` or ``. Add this branch as the `PRIMARY BRANCH` when making use of the [github workflow](gh-workflow-settings), this will make sure students are redirected to this URL which doesn't move when adding new versions of the book later on. If you plan on keeping only one public version, it's advised to set `BEHAVIOR_PRIMARY` from the default `redirect` to `copy` which makes sure the primary branch is copied to root so that the URL is compact. + - A development branch which contains all the new content combined but not yet published to students. This could be called ie. `dev` or `main`. `dev` is advised when you prefer git's default branch to be the most recent published version (as `main` is expected to be the default branch by many). + - Branches which will be created during the editing process, which is probably something which you want to allow. As long as `BRANCHES_TO_DEPLOY` is set to the default `*`, all branches are build and your fellow editors can review their own and each other's versions online. Once every while, it doesn't hurt to go through the list of branches and delete any branches which are merged but not deleted. + - (future) branches for previous study years which contain each year's version of the book. These could be called `` which ends up in their url too. Add these branches to the list of `BRANCHES_ARCHIVED` when making use of the [github workflow](gh-workflow-settings) to add a banner to the page indicating it's archived state. - Setup protected branches in GitHub/GitLab to prevent accidental changes - Add people with GitHub/GitLab permission matching their role and the protected branches. - Add a readme explaining the way you organized branches and permissions diff --git a/book/installation-and-setup/user_types.md b/book/installation-and-setup/user_types.md index 0a92d71..3cf1168 100644 --- a/book/installation-and-setup/user_types.md +++ b/book/installation-and-setup/user_types.md @@ -1,6 +1,6 @@ # User types -Different types of users will interact with the website or the Jupyter Books differently and will therefore need to know more or less about the composition of the book. For now we will differentiate 6 types of users. +Different types of users will interact with the website or the Jupyter Books differently and will therefore need to know more or less about the composition of the book. For now we will differentiate 5 types of users. 1. **Students providing feedback on the published website**.
Example Image There are multiple tools of providing feedback in the built book: a) using the issue button in the top-right corner to directly create issues visible to the editor team. b) Using the [hypothesis](https://jupyterbook.org/en/stable/interactive/comments/hypothesis.html)-extension which allows public/private highlighting and annotating parts of the book. An example can be seen on the [MUDE website](https://mude.citg.tudelft.nl/book/intro.html). c) Using the [Utterances](https://jupyterbook.org/en/stable/interactive/comments/utterances.html)-extension which allows commenting on pages for books which are hosted on GitHub visible for everyone. Those comments are converted to issues on GitHub for the editors to handle. diff --git a/book/intro.md b/book/intro.md index 290839f..b1ff072 100644 --- a/book/intro.md +++ b/book/intro.md @@ -3,6 +3,11 @@ This is an introduction to Git, VS Code and Jupyter Books for teachers and teaching assistants involved in TeachBooks, our platform easing the process of making a Jupyter book. This book is still work in progress, so feel free to contribute https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual! For more information about teachbooks, visit [https://teachbooks.tudelft.nl/](https://teachbooks.tudelft.nl/). ## Contact -If you encounter any issues and you've a TU Delft account, report it by clicking --> {fa}`lightbulb` on the top right corner of this page. Or contribute directly by creating a merge request in the [repository](https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual). +If you encounter any issues and you have a TU Delft account, report it by clicking --> {fa}`lightbulb` on the top right corner of this page. Or contribute directly by creating a merge request in the [repository](https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual). -If you've questions, contact Tom van Woudenberg, Robert Lanzafame or our TAs Julie Kirsch at TeachBooks@tudelft.nl, also for non-TU Delft account holders. TU Delft account holder can also contact us in the [MS Teams Open Interactive Textbooks Community](https://teams.microsoft.com/l/team/19%3Ah9-uRcP_yYauh-VuoPFozJVUvHVOB4a0mz1ZWvh4q4Q1%40thread.tacv2/conversations?groupId=3e88c1f3-4a4f-483a-a366-7e617de9ba99&tenantId=096e524d-6929-4030-8cd3-8ab42de0887b) \ No newline at end of file +If you have questions, contact Tom van Woudenberg, Robert Lanzafame or our TA Julie Kirsch at TeachBooks@tudelft.nl, also for non-TU Delft account holders. TU Delft account holder can also contact us in the [MS Teams Open Interactive Textbooks Community](https://teams.microsoft.com/l/team/19%3Ah9-uRcP_yYauh-VuoPFozJVUvHVOB4a0mz1ZWvh4q4Q1%40thread.tacv2/conversations?groupId=3e88c1f3-4a4f-483a-a366-7e617de9ba99&tenantId=096e524d-6929-4030-8cd3-8ab42de0887b) + +## Feedback +We really value your feedback on this manual so we can keep improving it. Please keep using the manual as you build your own Jupyter Book and come back to fill out this short [survey](https://forms.gle/hXbFUQgN95H8ftxt9). + +Happy book building! \ No newline at end of file diff --git a/book/tools/figmaker.md b/book/tools/figmaker.md new file mode 100644 index 0000000..534a57d --- /dev/null +++ b/book/tools/figmaker.md @@ -0,0 +1,15 @@ +# Figure syntax maker + +```{admonition} User types +:class: tip +This section is useful for user type 3-5. +``` + +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: + +
+ +
+
+ +
\ No newline at end of file diff --git a/book/workflows/branches.md b/book/workflows/branches.md index f32c2f0..904f05d 100644 --- a/book/workflows/branches.md +++ b/book/workflows/branches.md @@ -48,7 +48,7 @@ The circled menu is the branch selection menu. ``````{tab-item} ... GitHub -How to branch is demonstrated in the figure below, followed by a step-by-step tutorial. +How to branch is demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial. ```{figure} figures/branching-github-ezgif.com-optimize.gif --- diff --git a/book/workflows/edit_book.md b/book/workflows/edit_book.md index 7b7af0e..0858182 100644 --- a/book/workflows/edit_book.md +++ b/book/workflows/edit_book.md @@ -49,6 +49,15 @@ You can edit it and commit the changes in the same manner as with markdown (.md) ```` ````{tab-item} ... GitHub +How to make an edit and make a commit is demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial. + +```{figure} figures/user3-collaboration.gif +--- +name: user3_edit_demo +--- +Demonstration, video available [here](https://youtu.be/LG1vzrOLQHA) +``` + In GitHub, you can directly make changes in the files on the remote repository. You can make changes to the files already in the repository using the text editor but you can also upload new files! 1. Navigate to the repository you want to work in and make sure you're in the correct branch. @@ -100,6 +109,14 @@ You can edit it and commit the changes in the same manner as with markdown (.md) `````{tab-set} ````{tab-item} ... Git in VS Code +How to make an edit and make a commit using VS Code is demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial. + +```{figure} figures/User4_updated-ezgif.com-optimize.gif +--- +name: user4_clone_edit_demo +--- +Demonstration, video available [here](https://youtu.be/bThimdDRXTc) + 1. Make some changes to a file in for example VS Code and save them. 2. Select the files ready to be added to Git-timeline (staging) @@ -290,6 +307,14 @@ Alternatively, you can also click on `Push origin` in the top bar. `````{tab-set} ````{tab-item} ... Git in VS Code +The steps above are demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial. + +```{figure} figures/User5_wholeshabang-ezgif.com-optimize.gif +--- +name: user5_demo +--- +Demonstration, video available [here](https://youtu.be/2ttjBevkEP8) + 1. Make some changes to a file in for example VS Code and save them. 2. Once all the changes are made, it can be useful to check the changes locally on your device in order to see how it will look on the website. If all the required environments and packages are downloaded, checking changes locally is fairly easy! diff --git a/book/workflows/figures/User4_updated-ezgif.com-optimize.gif b/book/workflows/figures/User4_updated-ezgif.com-optimize.gif new file mode 100644 index 0000000..4889908 Binary files /dev/null and b/book/workflows/figures/User4_updated-ezgif.com-optimize.gif differ diff --git a/book/workflows/figures/User5_wholeshabang-ezgif.com-optimize.gif b/book/workflows/figures/User5_wholeshabang-ezgif.com-optimize.gif new file mode 100644 index 0000000..d8c8121 Binary files /dev/null and b/book/workflows/figures/User5_wholeshabang-ezgif.com-optimize.gif differ diff --git a/book/workflows/figures/user3-collaboration.gif b/book/workflows/figures/user3-collaboration.gif new file mode 100644 index 0000000..611bb23 Binary files /dev/null and b/book/workflows/figures/user3-collaboration.gif differ diff --git a/dummy.txt b/dummy.txt new file mode 100644 index 0000000..2995a4d --- /dev/null +++ b/dummy.txt @@ -0,0 +1 @@ +dummy \ No newline at end of file