diff --git a/book/_config.yml b/book/_config.yml index 1f98a0a..488fa6d 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -1,50 +1,49 @@ -Title: TeachBooks template -author: TeachBooks Team, built with TeachBooks and Jupyter Book, CC BY 4.0 #add your own name here +title: TeachBooks template # Replace this with your own book title +author: TeachBooks Team, built with TeachBooks and Jupyter Book, CC BY 4.0 + # Replace TeachBooks Teams with your own name in the line above execute: - execute_notebooks: "off" + execute_notebooks: "off" # Replace this if you want don't have notebooks with output and you want to add notebook output during build -only_build_toc_files: true +only_build_toc_files: true # Replace this with false if you want to build all files in the book, allowing you to refer to pages which are not included in the table of contents -html: - favicon : "figures/TB_favicon.ico" - baseurl : "https://.io/" #Replace this with your own URL - -sphinx: +sphinx: # Options passed on to the underlying sphinx-parser config: html_js_files: - - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js + - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js # Required for live code: https://teachbooks.io/manual/features/live_code.html thebe_config: - use_thebe_lite: true - exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"] + use_thebe_lite: true # Required for live code: https://teachbooks.io/manual/features/live_code.html + exclude_patterns: ["**/_*.yml", "**/*.md", "**/*.ipynb"] #exclude files which should not be accessible for live code: https://teachbooks.io/manual/features/live_code.html html_theme_options: logo: - text: Template - image_light: TeachBooks_logo.svg # Put your logo for the light mode here (can be the same as image_dark) - image_dark: TeachBooks_logo_inverted.svg # Put your logo for the dark mode here (can be the same as image_light) - repository_url: "https://github.com/user/repo" #add your own repo URL here - path_to_docs: "book" - repository_branch: "main" - use_edit_page_button: true - use_repository_button: true - use_issues_button : true + text: Template # Replace this with your own book title + image_light: TeachBooks_logo.svg # Put your logo for the light mode here (can be the same as image_dark) + image_dark: TeachBooks_logo_inverted.svg # Put your logo for the dark mode here (can be the same as image_light) + repository_url: "https://github.com/user/repo" # Add your own repo URL here + path_to_docs: "book" # Required for edit_page_button, should be book if you're using TeachBooks package (https://github.com/TeachBooks/TeachBooks) or the TeachBooks deploy book workflow (https://teachbooks.io/manual/external/deploy-book-workflow/README.html) + repository_branch: "main" # Replace when you change the name of your published branch (required for edit_page_button) + use_edit_page_button: true # Replace with false if you don't want the edit page button (i.e. if you don't user to propose changes themselves or have a private repo) + use_repository_button: true # Replace with false if you don't want the repository button (i.e. if you have a private repo) + use_issues_button : true # Replace with false if you don't want the issues button (i.e. if you don't want to use GitHub issues or have a private repo) launch_buttons: - thebe: true - html_show_copyright: false - html_last_updated_fmt: '%B %-d, %Y' - html_static_path: ["figures"] # add folders that contain files that need to be included, such as the location of the logo(s) + thebe: true # Required for live code: https://teachbooks.io/manual/features/live_code.html + favicon : "figures/TB_favicon.ico" # Replace this with your own favicon + baseurl : "https://teachbooks.io/" # Replace this with your own URL + html_show_copyright: false # As the copyright is included in the author field + html_last_updated_fmt: '%B %-d, %Y' # Adds the date of the last update to the footer + html_static_path: ["figures"] # Add folder that contain files that need to be included, such as the location of the logo(s) mathjax3_config: chtml: { - mtextInheritFont: true # To typeset text within math prettier + mtextInheritFont: true # To typeset text within math prettier } - extra_extensions: - - sphinx.ext.imgconverter - - jupyterbook_patches - - download_link_replacer - - sphinx.ext.extlinks - - sphinx_image_inverter - - sphinx_exercise - - teachbooks_sphinx_tippy + extra_extensions: # Gives you a starter package of extensions to use in your book + - jupyterbook_patches # Patches by TeachBooks https://github.com/TeachBooks/JupyterBook-Patches + - download_link_replacer # Allows you to replace and add downloadable files to a page header https://teachbooks.io/manual/external/Download-Link-Replacer/README.html + - sphinx_image_inverter # Inverts images for dark mode https://teachbooks.io/manual/external/Sphinx-Image-Inverter/README.html + - sphinx_iframes # Eases the embedding of iframes https://teachbooks.io/manual/external/sphinx-iframes/README.html + - sphinx_exercise # Allows you to add exercise boxes to your book https://ebp-sphinx-exercise.readthedocs.io/en/latest/ + - teachbooks_sphinx_tippy # Enables hoover over tips https://teachbooks.io/manual/external/teachbooks-sphinx-tippy/README.html + - sphinx_named_colors # Allows you to use custom colors in your book https://teachbooks.io/manual/external/Sphinx-Named-Colors/README.html bibtex_bibfiles: - - references.bib + - references.bib # Required for references diff --git a/book/_toc.yml b/book/_toc.yml index bcbd396..ad5003f 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -7,7 +7,7 @@ parts: - file: some_content/overview.md sections: - file: some_content/text_and_code.ipynb - - file: exercises + - file: exercises.md sections: - file: exercises/001.md - file: exercises/002.md @@ -16,6 +16,10 @@ parts: - file: exercises/005.md - file: exercises/006.md - file: exercises/summary + - file: syntax_exercises.md + sections: + - file: syntax_exercises/007.md + - file: syntax_exercises/008.md - file: references.md - file: changelog.md - file: credits.md diff --git a/book/changelog.md b/book/changelog.md index 729bf67..b9de8fa 100644 --- a/book/changelog.md +++ b/book/changelog.md @@ -1,4 +1,11 @@ # Changelog -## `` [``](<`link to release on GitHub>`) +## ``: `` - `` [](``) +- ... +- Full Changelog: `[...]()` + +## ``: <...> +- <...> + +<...> diff --git a/book/credits.md b/book/credits.md index 89b23d8..4363c3f 100644 --- a/book/credits.md +++ b/book/credits.md @@ -3,11 +3,11 @@ You can refer to this book as: -> `` (``) _``_. `<url to book website>`. Source files at `<link to github repo` +> `<editors>` (`<year>`) _`<title>`_. `<url to book website>`. Source files at `<link to github repo`. CC BY 4.0. You can refer to individual chapters or pages within this book as: -> `<Title of Chapter or Page>`. In `<editors>` (`<year>`) _`<title>`_. `<url to specific page on book website>`. Source files at `<link to specific commit / file in github repo` +> `<Title of Chapter or Page>`. In `<editors>` (`<year>`) _`<title>`_. `<url to specific page on book website>`. Source files at `<link to specific commit / file in github repo`. CC BY 4.0. We anticipate that the content of this book will change significantly. Therefore, we recommend using the source code directly with the citation above 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. However, we make no guarantee, so if it is important for you to reference a specific location/commit within the book. @@ -16,7 +16,7 @@ We anticipate that the content of this book will change significantly. Therefore This book is created using open source tools: it is a JupyterBook that is written using Markdown and Jupyter notebooks. Additional tooling is used from the [TeachBooks initiative](https://teachbooks.io/) to enhance the editing and reading experience. The files are stored on a [public GitHub repository](`<link to GitHub repo>`). The website can be viewed at `<link to book website url>`. View the repository README file or contact the authors for additional information. ## License -This manual is [CC BY 4.0 licensed](https://creativecommons.org/licenses/by/4.0/) allowing you to share and adapt the material, as long as the source is named. External resources that are reused in this manual are listed below. +This book is [CC BY 4.0 licensed](https://creativecommons.org/licenses/by/4.0/) allowing you to share and adapt the material, as long as the source is named. External resources that are reused in this book are listed below. (external_resources)= ### External resources @@ -24,10 +24,10 @@ This manual is [CC BY 4.0 licensed](https://creativecommons.org/licenses/by/4.0/ Parts of this book are taken from other external resources and reused in various ways. If an author is not listed on a particular page, it is by the Authors, except as follows: The following pages are included directly from an external resource and is not edited by `<Editor>`: -- page [](). Original content licensed under CC BY 4.0 License +- page `[](<relative_link_to_page>)`. Original content licensed under CC BY 4.0 License The following pages contain content written by others, part of has been reused and/or modified by `<Editor>` -- Page []() include text from {cite:t}`jason_moore`. Original content licensed under CC BY. +- Page `[](<relative_link_to_page>)` include text from {cite:t}`jason_moore`. Original content licensed under CC BY. (editor)= diff --git a/book/exercises.md b/book/exercises.md index e885fe5..491c7a4 100644 --- a/book/exercises.md +++ b/book/exercises.md @@ -1,4 +1,4 @@ -# Exercises +# Exercises TeachBooks workflow Getting used to the syntax of writing in a Jupyter Book can be a bit daunting at the start, not to mention becoming familiar with the various tools and workflows required. To help make the learning curve somewhat easier to travel, a number of exercises have been prepared for you as part. The exercises are designed such that no prior experience with any tools or programming is required, as long as you have read the preceding introductory pages. We welcome you to work through the exercises attached to this page (you can find them in the left sidebar). diff --git a/book/exercises/001.md b/book/exercises/001.md index 49a8240..cf25ea8 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -1,3 +1,4 @@ +(exercise_1)= # Exercise 1: First file edit Let's start with the most basic edit: add some text to a file and see that the website is updated. @@ -15,17 +16,23 @@ Can you add some content to the intro page? 7. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update intro.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` 8. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page (your browser keeps a cached version of website you recently visit, but we actually want the most up-to-date version!). -```{hint} Watch the steps in action below -:class: dropdown -![First file edit guide](https://github.com/TeachBooks/template_figures/blob/main/excercise1.gif?raw=true) +````{hint} Watch the steps in action below +class: dropdown -[Or watch the video here](https://youtu.be/gn1zBmmunco) +```{figure} https://github.com/TeachBooks/template_figures/blob/main/excercise1.gif?raw=true +--- +name: template_demo_public +--- +Demonstration of all steps of this exercise, video available [here](https://youtu.be/gn1zBmmunco) ``` +```` -:::{card} Check your understanding -<iframe src="https://home.teachbooks.io/wp-admin/admin-ajax.php?action=h5p_embed&id=2" width="624" height="324" frameborder="0" allowfullscreen="allowfullscreen" title="Testing your knowledge"></iframe><script src="https://home.teachbooks.io/wp-content/plugins/h5p/h5p-php-library/js/h5p-resizer.js" charset="UTF-8"></script> -::: +::::{card} Check your understanding +```{h5p} https://home.teachbooks.io/wp-admin/admin-ajax.php?action=h5p_embed&id=2 +``` +:::: -:::{card} Check your understanding -<iframe src="https://home.teachbooks.io/wp-admin/admin-ajax.php?action=h5p_embed&id=1" width="959" height="502" frameborder="0" allowfullscreen="allowfullscreen" title="Testing more Teachbooks knowledge"></iframe> -::: \ No newline at end of file +::::{card} Check your understanding +```{h5p} https://home.teachbooks.io/wp-admin/admin-ajax.php?action=h5p_embed&id=1 +``` +:::: diff --git a/book/exercises/004.md b/book/exercises/004.md index 8f2c172..d08c451 100644 --- a/book/exercises/004.md +++ b/book/exercises/004.md @@ -9,8 +9,8 @@ Can you make a new branch of your book with an additional file `file_on_new_vers 1. Add a new Issue to let people know you're working on something by going to your repository - {octicon}`issue-opened;1em` `Issues` - `New issue` (note that is not required for making your own version, but it's good practice so that people know where you're working on) 2. Add a title and description, eg. `Added some content` 3. On `Assignees`, click `Assign yourself` to make clear that you feel responsible for this issue. -4. Click `Submit new issue` -5. In the new window, under `Development`, click `Create a branch` (note that you could also make branches in other ways, but in this way it's directly linked to the issue). A 'branch' is a separate version of the book which keeps the link with the original book. +4. Click `Create` +5. In the new window (inside your just created issue), under `Development`, click `Create a branch` (note that you could also make branches in other ways, but in this way it's directly linked to the issue). A 'branch' is a separate version of the book which keeps the link with the original book. 6. Use the default options and click `Create branch` 7. Ignore the `checkout in your local repository`- popup for now (later on you'll know what this is and how to use it) 8. Go to `Code` - {octicon}`git-branch;1em` `main` and click on `1-<your_issue_title>` to open your branch. @@ -25,4 +25,4 @@ Before moving on to the next exercise, make sure you understand the following: - What is the purpose of creating a new branch in your repository? - Why is it good practice to create an issue before starting work on a new feature or change? - How can you view the changes made in your new branch online? -``` \ No newline at end of file +``` diff --git a/book/exercises/summary.md b/book/exercises/summary.md index 866137e..25bc7d6 100644 --- a/book/exercises/summary.md +++ b/book/exercises/summary.md @@ -1,6 +1,6 @@ # Summary of exercises: All Exercises -With the exercises, you did all the steps of our TeachBooks workflow! +With the simple exercises, you did all the steps of our TeachBooks workflow! ```{figure} https://github.com/TeachBooks/logos_and_visualisations/blob/main/TB_flowchart/TeachBooks_flowchart.svg?raw=true --- @@ -9,7 +9,7 @@ align: center --- ``` -Here is how the exercises relate to the workflow. +Here is how these exercises relate to the workflow. | Step No. | Name | Exercise | Description | | :---: | :---: | :---: | :---: | @@ -18,4 +18,9 @@ Here is how the exercises relate to the workflow. | 3 | Edit the book | 1, 2, 3| Editing `.md`-files, the `_toc.yml` and the `_config.yml` | | 4 | Check changes online | 1, 2, 3 | Workflows and Actions Summary | | 5 | Repeat edit and checking | 1, 2, 3, 4, 5 | Keep on doing all the steps until it's ready| -| 6 | Submit for review | 5, 6 | Open and merge a Pull Request, from a branch or forks | \ No newline at end of file +| 6 | Submit for review | 5, 6 | Open and merge a Pull Request, from a branch or forks | + +## Keep practicing + +For additional practice, there are more exercises relating to the capacities of each user type. +Have a look in the [manual](https://teachbooks.io/manual/installation-and-setup/user_types.html) to see which user type you are! \ No newline at end of file diff --git a/book/syntax_exercises.md b/book/syntax_exercises.md new file mode 100644 index 0000000..b8b49ef --- /dev/null +++ b/book/syntax_exercises.md @@ -0,0 +1,7 @@ +# Syntax exercises + +The previous exercise guide you through making your own book following the TeachBooks workflow. Now lets get specific and dive into the possibilities of the syntax used! + +As user type 3 you will work primarily in `.md` (Markdown) or `.ipynb`(Jupyter Notebook) files. In Jupyter Book, `.md` files contain text-based content with formatting, while `ipynb` files contain both text and executable code cells. `.md` files are much easier to edit online, so let's start with those! + +The more you write, the more different types of content you'll want to use. [JupyterBook itself provides a cheatsheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html) which will come in handy! \ No newline at end of file diff --git a/book/syntax_exercises/007.md b/book/syntax_exercises/007.md new file mode 100644 index 0000000..bb12b9e --- /dev/null +++ b/book/syntax_exercises/007.md @@ -0,0 +1,66 @@ +# Exercise 7: File structure by titles + +In this exercise you will learn how to structure your chapters. + +::::::{topic} Exercise objective +Can you structure your page with a title and (sub)sections? +:::::: + +```{tip} + +More useful Markdown syntax is explained in the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html). + +``` + +1. Let's add a new file by going to a directory of your choice within `/book` and make sure you're in the correct branch. When you've arrived there, click `Add file` - {octicon}`plus;1em` `Create new file`. + +2. Name your file and end it with the file extension `.md` (e.g. `my_new_file.md`), your filename preferable shouldn't include spaces. + +3. Now let's create the structure of your chapter. You need to start with a title on the top of this page. The title is always defined in one of the first lines of the file after the hashtag `#`. So your file should look like: + +```md +# Chapter title + +``` + +4. Now let's add some more text and subsections as needed. You're only allowed to use one chapter title `#`, but there's no limit for the amount of sections, subsections, etc: + +```md +# Chapter Title +text + +## Section Title 1 +text + +## Section Title 2 +text + +### Subsection Title 1 +text + +### Subsection Title 2 +text + +#### Heading +##### Smaller Heading +###### Smallest Heading +``` + +5. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +6. Add a commit message. + +7. Now let's add your new file tot the table of contents, as explained in [](../exercises/002.md). + +8. To see you changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? Soon, there'll be exercising on doing this locally which prevents you from waiting). + +9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. Please not that the name of the page in the table of contents is identical to the title of the page, while the URL corresponds to the directory structure of the source files. + +```{admonition} Check your understanding +:class: note + +Before moving on to the next exercise, make sure you understand the following: +- What is the correct way to define a title in a Markdown file? +- How many chapter titles (`#`) are allowed in a single Markdown file? +- What file type are you using? +``` diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md new file mode 100644 index 0000000..59c792b --- /dev/null +++ b/book/syntax_exercises/008.md @@ -0,0 +1,71 @@ +# Exercise 8: Add visual media + +To help you illustrate your content, it can be useful to add some type of visual media such as figures or gifs. If you want to add a figure/gif to you book, you can refer to the URL to that image directly. This is quite handy but it does carry the risk that this figure file will no longer be visible if the location is changed, or if the website is down. Therefore, sometimes it can be better to add the source directly to the book (if done on small scale). + +::::::{topic} Exercise objective +Can you add figures to your page? +:::::: + +```{note} +Unless you are using a file format like `*.svg`, the raw contents of a visual media file typically are not human-readable or have a binary file format. This is not an ideal file type to use with Git. When just beginning to learn about all the tools associated with a TeachBook, we recommend you keep things simple and do whatever is easiest for you. Note, however, that as your book grows, especially if you use a lot of non-svg images, you may want to find a different way to store them (guidance will be provided on this soon in the TeachBooks Manual---stay tuned!). +``` + + +1. You will first need to upload your media to the repository. Navigate to the folder called figures (`book/figures`) and make sure you are in the right branch. On the right top, click on `Add file` - {octicon}`upload;1em` `Upload new file`. Note that you can store your files in another folder within the book directory too. However it's good practice to store figures in a separate folder (eventually per chapter). + +2. Choose the visual media you want to upload. Remember its file name, including its file extension as you will need it later. + +3. Commit your changes. + +4. Now let's add the figure to a chapter. Navigate to the file you want to work in (for example `book/some_content/overview.md`) and make sure you're in the same branch as where you've added your figure. + +5. Copy this syntax and adjust the file name, width, alignment and caption (for more options see the [JupyterBook documentation](https://jupyterbook.org/en/stable/content/figures.html#figure-parameters)): + +````md +```{figure} figures/<new_figure>.png +--- +width: 80% +align: center +--- +<caption text> +``` +```` + +```{Warning} +Make sure the file extension of your figure is correct because markdown differentiates capital letters! +``` + +```{Warning} +If your figure is in a different directory than your chapter, you'll need to refer it using relative parts. If your figure is in a subdirectory of the directory of the chapter, go deeper with `subdirectory/` (e.g. `figures/<figure in figures-subdirectory>.png`). If your figure is in another directory, move upwards with `../` (e.g. `../../figure/<figure in figures-subdirectory which is located two folders above the current page>` ) +``` + +6. To link and display an online figure, you can use the same `{figure}` directive. Just past in the : + +````md +```{figure} https://town-n-country-living.com/wp-content/uploads/2023/06/craftsman-exterior.jpg +--- +width: 80% +align: center +--- +<caption> +``` +```` + +6. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. + +7. Add a commit message. + +8. To see you changes, go to {octicon}`play;1em` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting). + +9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. + +```{admonition} Check your understanding +:class: note + +Before moving on to the next exercise, make sure you understand the following: +- Where should you upload your visual media files in the repository? +- What is the recommended practice for storing figures in the book directory? +- What should you be cautious about when specifying the file extension of your figure? +- How do you refer to a figure located in a different directory than your chapter? + +``` \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 4d6bb6c..fc577ed 100644 --- a/requirements.txt +++ b/requirements.txt @@ -5,7 +5,8 @@ sphinx-image-inverter download_link_replacer sphinx-exercise teachbooks-sphinx-tippy +sphinx-iframes +sphinx-named-colors -# now list the packages (and the respective url) you wish to download from the GitLab package registry ---extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple -sphinx-thebe ~= 0.9.9 +# Now list the packages you want to download directly from GitHub +git+https://github.com/TeachBooks/Sphinx-Thebe