From 683a8f1bae75d8cc302629c782e978e14bedcc00 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Wed, 30 Apr 2025 23:06:18 +0200 Subject: [PATCH 1/3] Update 008.md --- book/syntax_exercises/008.md | 74 ++++++++++++++++++++++++++++++++---- 1 file changed, 67 insertions(+), 7 deletions(-) diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md index c363da7..7cbd25a 100644 --- a/book/syntax_exercises/008.md +++ b/book/syntax_exercises/008.md @@ -1,15 +1,18 @@ # 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). +To help you illustrate your content, it can be useful to add some type of visual media such as figures, gifs or videos. If you want to add a figure/gif to your 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? +Can you add figures and videos 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!). ``` +## Adding figures + 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). @@ -51,13 +54,69 @@ align: center ``` ```` -6. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button. -7. Add a commit message. +## Adding videos -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). +7. You can also embed videos (e.g., from YouTube) into your book using the [`sphinx-iframes`](https://github.com/TeachBooks/sphinx-iframes) extension. Firstly the extension needs to be installed. If you're working locally, install the module using pip: + +```bash +pip install sphinx-iframes +``` + +8. After installation, add the package in your `requirements.txt` to track the dependency: + +``` +sphinx-iframes +``` + +9. Now the extension needs to be enabled. Do this by adding the extension to the list of Sphinx extra extensions in your `_config.yml` file (**important**: underscore, not dash): + +```yaml +sphinx: + extra_extensions: + . + . + . + - sphinx_iframes + . + . + . +``` + +10. You can also configure several values which can be added to `_config.yml`, such as default video sizes. Add the following: + +```yaml +sphinx: + config: + iframe_blend: true + iframe_width: calc(100% - 2.8rem) + iframe_aspectratio: auto 2 / 1 +``` + +11. Let's test out this extension! Use the `{video}` directive to embed a video. Here’s an example you can try using a public YouTube video: + +````md +```{video} https://www.youtube.com/watch?v=x2eonqw5M6o +:width: 80% +:height: 400px +:class: blend +``` +```` + +```{tip} +The blend class helps the video look good in dark mode! +``` + +12. Try to change the `width`and `height` of the video in the previous example to customise the display. + +13. When you're ready, commit your changes to the repository by clicking the green `Commit changes` button. + +14. Add a commit message. + +15. To see your changes, go to {octicon}`play;1em` `Actions` – The most recent workflow run (`overview.md` / your commit message) – Wait for it to finish – In the summary, click on the link under `Branches deployed` and under `Primary book at root`. + +16. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. -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 @@ -67,5 +126,6 @@ Before moving on to the next exercise, make sure you understand the following: - 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? - +- What extension must be added to embed videos in the book? +``` ``` \ No newline at end of file From 32dbabff4d50065db63dadece2fabd478058dfb9 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sun, 4 May 2025 23:37:21 +0200 Subject: [PATCH 2/3] Update 008.md --- book/syntax_exercises/008.md | 56 ++++-------------------------------- 1 file changed, 6 insertions(+), 50 deletions(-) diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md index 7cbd25a..b29b68a 100644 --- a/book/syntax_exercises/008.md +++ b/book/syntax_exercises/008.md @@ -57,65 +57,21 @@ align: center ## Adding videos -7. You can also embed videos (e.g., from YouTube) into your book using the [`sphinx-iframes`](https://github.com/TeachBooks/sphinx-iframes) extension. Firstly the extension needs to be installed. If you're working locally, install the module using pip: +7. You can also embed videos (e.g., from YouTube) into your book using the [`sphinx-iframes`](https://github.com/TeachBooks/sphinx-iframes) extension, which is already part of the TeachBooks template. Try the example below using the `video` directive with a regular YouTube URL: -```bash -pip install sphinx-iframes -``` - -8. After installation, add the package in your `requirements.txt` to track the dependency: - -``` -sphinx-iframes -``` - -9. Now the extension needs to be enabled. Do this by adding the extension to the list of Sphinx extra extensions in your `_config.yml` file (**important**: underscore, not dash): - -```yaml -sphinx: - extra_extensions: - . - . - . - - sphinx_iframes - . - . - . -``` - -10. You can also configure several values which can be added to `_config.yml`, such as default video sizes. Add the following: - -```yaml -sphinx: - config: - iframe_blend: true - iframe_width: calc(100% - 2.8rem) - iframe_aspectratio: auto 2 / 1 -``` - -11. Let's test out this extension! Use the `{video}` directive to embed a video. Here’s an example you can try using a public YouTube video: ````md -```{video} https://www.youtube.com/watch?v=x2eonqw5M6o -:width: 80% -:height: 400px -:class: blend +```{video} https://www.youtube.com/watch/B1J6Ou4q8vE ``` ```` -```{tip} -The blend class helps the video look good in dark mode! -``` +8. When you're ready, commit your changes to the repository by clicking the green `Commit changes` button. -12. Try to change the `width`and `height` of the video in the previous example to customise the display. +9. Add a commit message. -13. When you're ready, commit your changes to the repository by clicking the green `Commit changes` button. +10. To see your changes, go to {octicon}`play;1em` `Actions` – The most recent workflow run (`overview.md` / your commit message) – Wait for it to finish – In the summary, click on the link under `Branches deployed` and under `Primary book at root`. -14. Add a commit message. - -15. To see your changes, go to {octicon}`play;1em` `Actions` – The most recent workflow run (`overview.md` / your commit message) – Wait for it to finish – In the summary, click on the link under `Branches deployed` and under `Primary book at root`. - -16. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. +11. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. ```{admonition} Check your understanding From 7f767329c17c29f3305fb9c3701e1255364f42d0 Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Sun, 4 May 2025 23:42:59 +0200 Subject: [PATCH 3/3] Update 008.md --- book/syntax_exercises/008.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/book/syntax_exercises/008.md b/book/syntax_exercises/008.md index b29b68a..2ca453f 100644 --- a/book/syntax_exercises/008.md +++ b/book/syntax_exercises/008.md @@ -82,6 +82,4 @@ Before moving on to the next exercise, make sure you understand the following: - 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? -- What extension must be added to embed videos in the book? ``` -``` \ No newline at end of file