diff --git a/book/_toc.yml b/book/_toc.yml index 071ff04..aa2a6b8 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -34,10 +34,14 @@ parts: - file: basic-features/References.md - file: basic-features/code.md - file: basic-features/Code_block_figures + - file: basic-features/banner + title: Banner or Announcement - file: basic-features/hypothesis - file: basic-features/utterances - file: features/overview sections: + - file: features/teachbooks + title: TeachBooks Package - file: external/deploy-book-workflow/README.md - file: features/remove_from_publish - file: features/custom_toc.md diff --git a/book/basic-features/banner.md b/book/basic-features/banner.md new file mode 100644 index 0000000..63db4e0 --- /dev/null +++ b/book/basic-features/banner.md @@ -0,0 +1,46 @@ +# Banners and Announcements + +A banner can be added to the top of a Jupyter Book: + +```{figure} banner_mude.png +--- +width: 70% +name: banner_mude +--- +Example of a banner in the MUDE book. +``` + +This is a commonly used feature, desribed in the [Jupyter Book manual here](https://jupyterbook.org/en/stable/web/announcements.html). However, note that if you are using the Sphinx-Thebe interactive Python feature, or other features that customize the top part of a Jupyter Book website (for example, the download page buttons), the banner does not always work. In this case, the banner should be specified using the `announcement` option in the `html_theme_options` setting in the `_config.yml` file: + +``` +sphinx: + config: + ... + html_theme_options: + ... + announcement : "This book is under construction ✍🏻; it's continuously updated from September 2024 through January 2025 📅" + ... +``` + +```{tip} +Note that you should always enclose your announcement in quotes to make it a complete string. Use a different type of quote if your announcement itself contains them (for example, `"like 'this'"`). If you are using HTML elements, it is best to make your announcement a complete HTML tag, not Markdown with HTML inside. + +Markdown links do not work in the announcement, in which case you must use HTML! +``` + +## Known Issue + +Note that there seems to be a bug if you only use the `announcement` and `launch_buttons:thebe:true` option; including additional buttons seems to fix this issue (see [Issue 65](https://gitlab.tudelft.nl/mude/book/-/issues/65) in the MUDE book), for example: + +``` +sphinx: + config: + ... + html_theme_options: + repository_url: "https://github.com/TeachBooks/mechanics-BSc" + use_repository_button: true + use_issues_button : true + announcement : "This book is under construction ✍🏻; it's continuously updated from September 2024 through January 2025 📅" + launch_buttons: + thebe: true +``` diff --git a/book/basic-features/banner_mude.png b/book/basic-features/banner_mude.png new file mode 100644 index 0000000..4c46205 Binary files /dev/null and b/book/basic-features/banner_mude.png differ diff --git a/book/features/custom_toc.md b/book/features/custom_toc.md index fe178c0..b75a238 100644 --- a/book/features/custom_toc.md +++ b/book/features/custom_toc.md @@ -1,3 +1,4 @@ +(remove-from-publish)= # Exclude parts of book from published book ```{admonition} User types @@ -5,7 +6,7 @@ This section is useful for user type 3-5. ``` -A new feature is added to enable testing of all interactive features on the web server (i.e., in the draft book) while preventing students from seeing it. Pages in the draft book (`main` branch) can be manually stripped out of the table of contents when a merge request from `main` to `publish` is made using a tag `REMOVE-FROM-PUBLISH`. Pages marked with this feature are still visible in the draft book and books build from source on personal computers. The tag is applied as follows: +A feature to enable viewing of work-in-progress (e.g., in the draft book) or testing of content (e.g., interactive programming pages) while preventing students from seeing it is available via the {ref}`teachbooks-package `. Lines of text in a `*.yml` file can be removed prior to the book build process by surrounding the lines with a tag `REMOVE-FROM-PUBLISH`. For example, pages in a draft book (e.g., `main` branch) can be manually stripped out of the table of contents when a merge request from `main` to `publish`, preventing the page being included in the published book. Pages marked with this feature are still visible in the draft book and books build from source on personal computers. Lines tagged in the configuration file `_config.yml` can be used in exactly the same manner. The tag is applied as follows: ``` format: jb-book @@ -20,8 +21,17 @@ parts: - file: files_to_remove # END REMOVE-FROM-PUBLISH ``` -There is no limit to the number of stripped sections, they can be sequential and indentation does not matter. The action is implemented in shell script `build-book.sh` and is executed at run time (see line in script [here](https://gitlab.tudelft.nl/mude/book/-/blob/main/build-book.sh#L13)). +There is no limit to the number of stripped sections, they can be sequential and indentation does not matter. + +To invoke the tag and remove content during the book build process, use the following optional argument when building the book with the `teachbooks` package: + +``` +teachbooks build --publish book +``` + +Note that `teachbooks build book` would build a book without stripping the tagged lines, just as `jupyter book build book` would. ```{note} -The `REMOVE-FROM-PUBLISH` feature was developed to retain testing of all interactive features on the web server and we recommended incorporating this in all books that rely on these features. It avoids problems associated with building the book on various platforms and virtual environments, rather than the actualy webserver where the book will be deployed. -``` \ No newline at end of file +The `REMOVE-FROM-PUBLISH` feature was originally deployed using Bash and Shell scripts in the pipeline of our book build processes. The MUDE book contained the scripts on the server, whereas the `interactivetextbooks-citg` contained this in the GitLab CI files or `*.sh` scripts. These workflows will eventually be replaced with a simplified pipeline setup (i.e., a GitLab CI file or GitHub workflow) that uses the commands `teachbooks build book` and `teachbook build --publish book` for the published and draft versions of the book, resepctively. We recommend you do the same. A working example can be found in our [Template repository workflow on GitHub](https://github.com/TeachBooks/deploy-book-workflow/blob/main/.github/workflows/deploy-book.yml) or in the [MUDE book on GitLab](https://gitlab.tudelft.nl/mude/book/-/blob/main/.gitlab-ci.yml?ref_type=heads). +``` + diff --git a/book/features/teachbooks.md b/book/features/teachbooks.md new file mode 100644 index 0000000..244f3ff --- /dev/null +++ b/book/features/teachbooks.md @@ -0,0 +1,18 @@ +(teachbooks-package)= +# TeachBooks: Our Custom Python Package + +TeachBooks has created a Python package and released it on PyPI. It can easily be used like this: +``` +pip install teachbooks +``` + +The source code is hosted in a repository on GitHub, [github.com/teachBooks/teachbooks](https://github.com/teachBooks/teachbooks), and is accompanied by a documentation website, [teachbooks.github.io/TeachBooks/](https://teachbooks.github.io/TeachBooks/). + +The features and documentation will increase with time; until then, note there are two important reasons to use the teachbooks package: +1. Use the `REMOVE-FROM-PUBLISH` feature to more easily maintain draft and published versions of your TeachBook (see {ref}`this page ` for more details). +2. Easily start and stop a local Python server to better test your book while writing (e.g., the interactive Python features require a local server to properly check certain TeachBooks features) + +For case 1, the `teachbooks` package is meant to be used instead of `jupyter book build book` to build your book (it executes `jupyter book build book` for you). + +Case 2 is meant to be used independently, for example, once you have successfully built a book, simply run `teachbooks serve` and open the resulting URL that is printed in the terminal. To stop the server use `teachbooks serve stop`; see {ref}`this page ` for additional explanation for how to use this feature and why it is needed. + diff --git a/book/installation-and-setup/jupyter-book-setup.md b/book/installation-and-setup/jupyter-book-setup.md index 811db35..b18f00a 100644 --- a/book/installation-and-setup/jupyter-book-setup.md +++ b/book/installation-and-setup/jupyter-book-setup.md @@ -28,9 +28,18 @@ Bookmark the (local) file location for easy access! ## View the book using a local webserver Some features like JupyterLite and Grasple only work when a webserver serves the HTML content for a book. Rather than building the book in your repository and updating the website on the internet, you can use a local webserver to view the book: +1. Make sure you have the TeachBooks Python package installed (e.g., `pip install teachbooks`) +2. Start a server from the command line with: `teachbooks serve` +3. The command line output will return the URL where you can access your book +4. You should reload the page if you are editing and rebuilding the book. You can try `CTRL+R` `ctrl`+`F5`. If this does not work, on Chrome try right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`. +5. All interactive features like the JupyterLite consoles, Grasple/H5p iframe exercises, Sphinx-thebe python interactivity and HTML/Javascript elements should now work as well. +6. When you no longer need the server, simply run `teachbooks serve stop` + +### How to create a local server without the TeachBooks package + +Here is how to set up a local server with only standard Python libraries: + 1. Start a server from the command line with: `python -m http.server -b 127.0.0.1` (add ` &` if you want to keep using the terminal for other tasks). 2. Port 8000 is usually used by default, but depending on your OS it will tell you in the output. 3. To visit your site, just enter the address in your web browser, followed by a colon, and then the port number. By default, that would be: `127.0.0.1:8000`. -4. You will get a website that looks like a file browser, to visit your site just navigate to `book/_build/html/` (if you've started this command from this folder you see the book immediately -5. You may need to reload the page once the rebuild is complete. You can do this on Chrome by right-clicking somewhere on the page, select \"Inspect\", open the \"Network\" tab, then reload with `CTRL+R`. Or try `ctrl`+`F5`\n" -6. All interactive features like the JupyterLite consoles, Grasple/H5p iframe exercises, Sphinx-thebe python interactivity and HTML/Javascript elements should now work as well. +4. You will get a website that looks like a file browser, to visit your site just navigate to `book/_build/html/` (if you've started this command from this folder you see the book immediately) \ No newline at end of file