diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 7eb347c..333f76d 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -2,18 +2,15 @@ stages: - test - build - deploy - variables: PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip" REGISTRY_HOST: localhost:5000 TAG_LATEST: $REGISTRY_HOST/$CI_PROJECT_NAME/$CI_COMMIT_REF_NAME:latest TAG_DRAFT: $REGISTRY_HOST/$CI_PROJECT_NAME-draft/$CI_COMMIT_REF_NAME:latest GIT_SUBMODULE_STRATEGY: recursive # For submodules - cache: paths: - .cache/pip - # This job tests if the book compiles gracefully after a new addition test-build: stage: test @@ -24,13 +21,12 @@ test-build: - pip install -r requirements.txt - jupyter-book clean book/ - jupyter-book build book/ - # This job builds the Docker container build-book: stage: build image: docker rules: - - if: $CI_COMMIT_BRANCH == "publish" && $CI_PIPELINE_SOURCE == "push" + - if: $CI_COMMIT_BRANCH == "release" && $CI_PIPELINE_SOURCE == "push" variables: TAG: $TAG_LATEST - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push" @@ -42,13 +38,12 @@ build-book: - if [ "$TAG" = "$TAG_LATEST" ]; then sed --in-place=".bak" '/# START DRAFT/,/# END DRAFT/{//!d}' book/_config.yml; fi - docker build -t $TAG . - docker push $TAG - # This job takes down the existing container and starts the new one deploy-book: stage: deploy image: docker rules: - - if: $CI_COMMIT_BRANCH == "publish" && $CI_PIPELINE_SOURCE == "push" + - if: $CI_COMMIT_BRANCH == "release" && $CI_PIPELINE_SOURCE == "push" before_script: - docker info - docker stop $CI_PROJECT_NAME || exit_code=$? @@ -58,7 +53,6 @@ deploy-book: environment: name: production url: https://interactivetextbooks.citg.tudelft.nl/jupyter-book-manual - # Deploy the draft version of the book deploy-draft: stage: deploy @@ -73,4 +67,4 @@ deploy-draft: - docker run -d --restart always -p 8018:8000 --name $CI_PROJECT_NAME-draft $TAG_DRAFT environment: name: draft - url: https://interactivetextbooks.citg.tudelft.nl/jupyter-book-manual-draft + url: https://interactivetextbooks.citg.tudelft.nl/jupyter-book-manual-draft \ No newline at end of file diff --git a/.gitmodules b/.gitmodules index 64687ac..80ce81d 100644 --- a/.gitmodules +++ b/.gitmodules @@ -13,3 +13,6 @@ [submodule "book/external/Useful_python_code"] path = book/external/Useful_python_code url = https://github.com/TeachBooks/Useful_python_code.git +[submodule "book/external/TeachBooks"] + path = book/external/TeachBooks + url = https://github.com/TeachBooks/TeachBooks.git diff --git a/book/_toc.yml b/book/_toc.yml index aa2a6b8..1c03d88 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -36,11 +36,11 @@ parts: - file: basic-features/Code_block_figures - file: basic-features/banner title: Banner or Announcement - - file: basic-features/hypothesis - - file: basic-features/utterances + - file: basic-features/hypothesis.md + - file: basic-features/utterances.md - file: features/overview sections: - - file: features/teachbooks + - file: external/TeachBooks/README.md title: TeachBooks Package - file: external/deploy-book-workflow/README.md - file: features/remove_from_publish @@ -55,20 +55,14 @@ parts: sections: - file: features/adding_HTML_elements.md - file: features/creating_basic_HTML_elements.md - - file: features/python_interactivity.md + - file: features/live_code sections: - - file: features/live_code - sections: - - file: features/widgets.ipynb - - file: features/exercise_checking.ipynb - - file: features/jupyterlite/jupyterlite - sections: - - file: features/jupyterlite/configuration - - file: features/jupyterlite/including-jupyterlite + - file: features/widgets.ipynb + - file: features/exercise_checking.ipynb - caption: Examples chapters: - - file: examples/overview + - file: examples/overview.md - file: examples/book_structure.md - file: examples/h5p_examples.md - file: examples/live_code.md diff --git a/book/basic-features/overview.md b/book/basic-features/overview.md index 5472fda..7b9e4d4 100644 --- a/book/basic-features/overview.md +++ b/book/basic-features/overview.md @@ -5,14 +5,4 @@ This section is useful for user type 3-5. ``` -A short description on basic features is given here: -- Figures -- Videos -- Equations -- Code blocks to produce figures -- References -- Code -- Notebooks - -This page will provide a list of some commonly used book features which are all available in the original Jupyter book package. However, this page includes best-practises on how to use them. -``` \ No newline at end of file +A short description on basic features is given here. These pages will provide a list of some commonly used book features which are all available in the original Jupyter book package. However, this page includes best-practices on how to use them. diff --git a/book/external/Nested-Books b/book/external/Nested-Books index 7ce10eb..4f72481 160000 --- a/book/external/Nested-Books +++ b/book/external/Nested-Books @@ -1 +1 @@ -Subproject commit 7ce10eb625c878f1fbd008b67bd266d61461541b +Subproject commit 4f72481f6a9b65c9b3bd22d0351b58b562f4802c diff --git a/book/external/TeachBooks b/book/external/TeachBooks new file mode 160000 index 0000000..c802630 --- /dev/null +++ b/book/external/TeachBooks @@ -0,0 +1 @@ +Subproject commit c802630d700f579eff2ac990496503bdda57ca3b diff --git a/book/external/latex-to-markdown-conversion b/book/external/latex-to-markdown-conversion index 0b9b651..f71092b 160000 --- a/book/external/latex-to-markdown-conversion +++ b/book/external/latex-to-markdown-conversion @@ -1 +1 @@ -Subproject commit 0b9b6512da9ff9011e56897eb6837cc3ed89ee45 +Subproject commit f71092bfdb2e3d5d2f580bac5e31ff695806e7d3 diff --git a/book/external/template b/book/external/template index 2d5513d..1ea4faf 160000 --- a/book/external/template +++ b/book/external/template @@ -1 +1 @@ -Subproject commit 2d5513da0a53b606f870890237ef4417dc18b398 +Subproject commit 1ea4faffd395342b79b0bc995526ba254c2c4b63 diff --git a/book/features/HTML_javascript.md b/book/features/HTML_javascript.md index 633fcc4..491ce51 100644 --- a/book/features/HTML_javascript.md +++ b/book/features/HTML_javascript.md @@ -13,4 +13,6 @@ This could be for example interactive 3d figures: Or other interactive graphs: - \ No newline at end of file + + + \ No newline at end of file diff --git a/book/features/custom_toc.md b/book/features/custom_toc.md index b75a238..77cbae7 100644 --- a/book/features/custom_toc.md +++ b/book/features/custom_toc.md @@ -6,7 +6,7 @@ This section is useful for user type 3-5. ``` -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: +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` is made. This prevents 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 @@ -29,7 +29,7 @@ To invoke the tag and remove content during the book build process, use the foll 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 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 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/h5p.md b/book/features/h5p.md index 463dcab..853b822 100644 --- a/book/features/h5p.md +++ b/book/features/h5p.md @@ -6,7 +6,7 @@ This section is useful for user type 3-5. ``` ## Instruction -H5p elements are interactive HTML-blocks which can be imbeded in a Jupyter Book using an iframe. 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: +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: ```html diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb index 9d900a8..a2dfb95 100644 --- a/book/features/live_code.ipynb +++ b/book/features/live_code.ipynb @@ -4,9 +4,16 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "# Sphinx-thebe\n", + "# Run Python inside your book with Sphinx-thebe\n", "\n", - "Our book has been enable to run Python code live in the browser (thanks Max!). This page contains some installation instructions and the other sections show how to use this functionality to create interactive figures and feedback on code\n", + "```{admonition} User types\n", + ":class: tip\n", + "This section is useful for user type 5.\n", + "```\n", + "\n", + "Our book has been enable to run Python code live in the browser (thanks Max!). This extension makes code cells in your `.ipynb` book pages editable and executable by the reader! Opposed to the original sphinx-thebe extensions, our extension runs python in the reader's browser and doesn't rely on an external webserver for the python kernel. We highly recommend this extension as it allows you to use the strength of combining text/figures and code of a jupyter book with interactivity!\n", + "\n", + "This page contains some installation instructions and the other sections show how to use this functionality to create interactive figures and feedback on code\n", "\n", "To see this happening, click {fa}`rocket` --> {guilabel}`Live Code` on the top right corner of this page" ] @@ -29,7 +36,7 @@ "metadata": {}, "source": [ "## Setting up Python live coding\n", - "To set up the Python live coding you need to add our [own sphinx-thebe extension](https://gitlab.tudelft.nl/interactivetextbooks-citg/extensions/sphinx-thebe) to your book. This extensions doesn't rely on a 3rd party like Binder and it supports local python execution and custom features. Therefore, you need to add some lines to `requirements.txt` and `_config.yml`\n", + "To set up the Python live coding you need to add our [own sphinx-thebe extension](https://github.com/TeachBooks/Sphinx-Thebe) to your book. This extensions doesn't rely on a 3rd party like Binder and it supports local python execution and custom features. Therefore, you need to add some lines to `requirements.txt` and `_config.yml`\n", "\n", "For `requirements.txt` add the following lines:\n", "```\n", @@ -37,7 +44,7 @@ "sphinx-thebe ~= 0.9.9\n", "```\n", "\n", - "This will download the correct version of the sphinx extension when the book is build on the server (which loads the required packages from `requirements.txt`)\n", + "This will download the correct version of the sphinx extension when the book is built on the server (which loads the required packages from `requirements.txt`)\n", "\n", "If you want to build the book locally, you need to install this version of sphinx-thebe in your environment as well with:\n", "```\n", @@ -123,11 +130,25 @@ "%pip install package_name\n", "```\n" ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Alternative with JupyterLite (less well integrated)\n", + "Another option to use python in your browser is to use JupyterLite. However, this doesn't give a similar seamless interface. You could create 'iframe-like' Ipython consoles / jupyterbook / jupyter lab environments in your book. As these 'iframes' are separate modules added to your page, the integration with the other content in your book is less flexible as with our sphinx-thebe extension. Furthermore, the best way to use a JupyterLite session would be a separate repo with the jupyter lab interface anyway, so you get the full browser experience. Alternatively, the ipython REPL better can be usefull, as shown here: https://teachbooks.github.io/learn-python/main/Python_Toolbox.html." + ] } ], "metadata": { + "kernelspec": { + "display_name": "base", + "language": "python", + "name": "python3" + }, "language_info": { - "name": "python" + "name": "python", + "version": "3.9.18" } }, "nbformat": 4, diff --git a/book/features/overview.md b/book/features/overview.md index bb0cecd..ea508a4 100644 --- a/book/features/overview.md +++ b/book/features/overview.md @@ -1,6 +1,6 @@ # TeachBooks Features -We collect a suite of existing open-source software and keep our books up-to-date 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. By deploying these tools from a central location we can prevent common problems before they arise, and fix them quickly when they do occur. As the open-source software landscape changes rapidly, it is esential 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! +As TeachBooks, we collect a suite of existing open-source software and keep our books up-to-date 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. By deploying these tools from a central location we can prevent common problems before they arise, and fix them quickly when they do occur. 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! This chapter provides a list of commonly used book features together with sub-pages that provide additional information on: - the purpose @@ -8,18 +8,5 @@ This chapter provides a list of commonly used book features together with sub-pa - how to use them - where to find the source code -Overview of features covered: -- Interaction on the website: Adding comments and feedback to content on the website -- Grasple Questions: Explanation how to embed Grasple questions in the book. -- Adding interactive h5p elements: Embedding interactive HTML-blocks in the book -- Exclude parts of book from published book -- Page download options -- Python-enabled interactivity: Run Python code live in the browser - - Widgets - - Exercise checking using check-answer button -- JupyterLite-Sphinx: Including interactive pieces of content in the book. - - Configuration - - How to add `JupyterLite` to a page - -To see examples for these features, go to the Example chapter. +To see examples for these features, go to the [Examples chapter](/book/examples/overview.md). diff --git a/book/features/python_interactivity.md b/book/features/python_interactivity.md deleted file mode 100644 index adfc5a6..0000000 --- a/book/features/python_interactivity.md +++ /dev/null @@ -1,10 +0,0 @@ -# Python-enabled interactivity - -```{admonition} User types -:class: tip -This section is useful for user type 5-6. -``` - -In general, there are two option to include python-enabled interactivity embedded in your book: - - Using our [own sphinx-thebe extension](./live_code.md) which makes code cells in your `.ipynb` book pages editable and executable by the reader! Opposed to the original sphinx-thebe extensions, our extension runs python in the reader's browser and doesn't rely on an external webserver for the python kernel. We highly recommend this extension as it allows you to use the strength of combining text/figures and code of a jupyter book with interactivity! - - Using [JupyterLite](jupyterlite/jupyterlite.md) to create 'iframe-like' Ipython consoles / jupyterbook / jupyter lab environments in your book. As these 'iframes' are separate modules added to your page, the integration with the other content in your book is less flexible as with our sphinx-thebe extension. \ No newline at end of file diff --git a/book/installation-and-setup/creating_content.md b/book/installation-and-setup/creating_content.md index b1524f4..08c8dc2 100644 --- a/book/installation-and-setup/creating_content.md +++ b/book/installation-and-setup/creating_content.md @@ -1,38 +1,33 @@ -# Creating Content +# Content & Copyright -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. TeachBooks provides a [template](https://teachbooks.tudelft.nl/jupyter-book-manual/external/template/README.html) you can use to create your book on GitHub, ensuring that your repository contains all the files you may need. Now it's time to create your own content. This section will provide an overview of these components and help you get started on your content. +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! -```{Important} -Please ensure you respect copy right laws when creating and including content! Don't forget to go through our checklist. -``` +## Checklist -# Checklist - Copy Right - -Although the focus of TeachBooks is mostly to help the teaching staff create interactive textbooks for their students, it can be attractive to spread ones wings a bit and reach a wider audience. The following section will be all about what you have to keep in mind in terms of copy right and what you should know to avoid major legal issues and make your life easier later on when/if you decide to publish your book with an open license, especially via TU Delft Open. For more information you can find everything on the [TU Delft website](https://www.tudelft.nl/library/support/copyright) +Although the focus of TeachBooks is mostly to help the teaching staff create interactive textbooks for their students, it can be attractive to spread ones wings a bit and reach a wider audience. The following section will be all about what you have to keep in mind in terms of copy right and what you should know to avoid major legal issues and make your life easier later on when/if you decide to publish your book with an open license, especially via TU Delft Open. For more information you can find everything on the [TU Delft Copyright website](https://www.tudelft.nl/library/support/copyright) -1) Your own new content +**1) Your own new content** If you have created the content yourself, you are allowed to use it if there are no other agreements in place -2) Somebody else's content +**2) Somebody else's content** If you want to re-use someone else’s work, you need to ask for permission. When you ask for permission please do it in a written format and let the copyright holders know that you are going to use their work in an open licensed work. If they give you permission, exclude the work from the open licensed conditions applicability, by stating that in the attribution/footnote/caption. Exclude it as well in the colophon of the work. If you have asked for permission and you received no answer back, please consider it as a negative response and abstain using the work you were intended to. - If you really need to re-use someone else’s work, please alsio check whether the copyright exception right to quote is applicable to you. + If you really need to re-use someone else’s work, please also check whether the copyright exception right to quote is applicable to you. More info: [Citations](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131017) , [Use copyrighted multimedia](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131031) , [Use copyrighted text](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131032) - -3) Your own old content +**3) Your own old content** Always attribute the works that are not created by you. Even if created by you, you need to attribute yourself in order to avoid self-plagiarism. Read how to [here](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131032) Even if you have created the work yourself but years ago, please check whether you have the right to re-use it. If you have created it while you were under the employment of your previous employer, then you will need to ask permission from them. -4) Open licensed work +**4) Open licensed work** - If you want to re-use someone else’s work, please check whether you can find an open licensed work, which can replace the work you wanted to re-use in the first place. More info: [Open licensed work platforms](https://www.tudelft.nl/library/collecties/open-educational-resources) + If you want to re-use someone else’s work, please check whether you can find an open licensed work, which can replace the work you wanted to re-use in the first place. More info: [Open licensed work platforms](https://www.tudelft.nl/en/library/collections/open-educational-resources) If you use open licensed work, you need to attribute the license under which the work is licensed and you need to check the compatibility of the licenses. This means you need to check the license that the work you want to reuse has and the license that your TeachBook will be licensed with. More info [here](https://wiki.creativecommons.org/wiki/Wiki/cc_license_compatibility) diff --git a/book/installation-and-setup/creating_content_backup.md b/book/installation-and-setup/creating_content_backup.md deleted file mode 100644 index 5d5b11c..0000000 --- a/book/installation-and-setup/creating_content_backup.md +++ /dev/null @@ -1,65 +0,0 @@ - -```{Notes Robert} - -- the creating content page can be more like an overview/jumping off point (for example, it can point out that a book is 3 things: toc+config+content), then link to existing JB manual, example books, etc, but have a really big colorful box that warns about copyright -- on this main page it would be important to have a checklist for "what to do when starting a book" that includes choosing a license and how to avoid copyright issues, with links to supbages -- creating content subpages: -open source licenses: a short overview of types, pointing out that some are oriented on creative work, others on software. mostly pointing out we don't know the right answer but listing examples of what others have done so far -copyright page (this is where paschalis' bullet points should go) - -``` - -# Creating Content - -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. TeachBooks provides a [template](https://teachbooks.tudelft.nl/jupyter-book-manual/external/template/README.html) you can use to create your book on GitHub, ensuring that your repository contains all the files you may need. Now it's time to create your own content. This section will provide an overview of these components and help you get started on your content. - -# Building Blocks - -Creating content for your Jupyter Book involves assembling several key components: the table of contents (`_toc.yml`), the configuration settings (`_config.yml`) and the actual content. - -## Table of Contents - -## Configuration - -## Content - -```{Important} -Please ensure you respect copy right laws when creating and including content! Don't forget to go through our checklist. -``` - -Markdown Files: Write your content in Markdown (.md) files. Markdown is a lightweight markup language with plain text formatting syntax. -Chapters and Sections: Organize your content into chapters and sections, with each chapter being a separate Markdown file. - - -# Checklist - Copy Right - -Although the focus of TeachBooks is mostly to help the teaching staff create interactive textbooks for their students, it can be attractive to spread ones wings a bit and reach a wider audience. The following section will be all about what you have to keep in mind in terms of copy right and what you should know to avoid major legal issues and make your life easier later on when/if you decide to publish your book with an open license, especially via TU Delft Open. For more information you can find everything on the [TU Delft website](https://www.tudelft.nl/library/support/copyright) - - -1) Your own new content - - If you have created the content yourself, you are allowed to use it if there are no other agreements in place - -2) Somebody else's content - - If you want to re-use someone else’s work, you need to ask for permission. When you ask for permission please do it in a written format and let the copyright holders know that you are going to use their work in an open licensed work. If they give you permission, exclude the work from the open licensed conditions applicability, by stating that in the attribution/footnote/caption. Exclude it as well in the colophon of the work. If you have asked for permission and you received no answer back, please consider it as a negative response and abstain using the work you were intended to. - - If you really need to re-use someone else’s work, please alsio check whether the copyright exception right to quote is applicable to you. - - More info: [Citations](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131017) , [Use copyrighted multimedia](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131031) , [Use copyrighted text](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131032) - - -3) Your own old content - - Always attribute the works that are not created by you. Even if created by you, you need to attribute yourself in order to avoid self-plagiarism. Read how to [here](https://www.tudelft.nl/library/support/copyright/researcher-copyright-answers#c1131032) - - Even if you have created the work yourself but years ago, please check whether you have the right to re-use it. If you have created it while you were under the employment of your previous employer, then you will need to ask permission from them. - -4) Open licensed work - - If you want to re-use someone else’s work, please check whether you can find an open licensed work, which can replace the work you wanted to re-use in the first place. More info: [Open licensed work platforms](https://www.tudelft.nl/library/collecties/open-educational-resources) - - If you use open licensed work, you need to attribute the license under which the work is licensed and you need to check the compatibility of the licenses. This means you need to check the license that the work you want to reuse has and the license that your TeachBook will be licensed with. More info [here](https://wiki.creativecommons.org/wiki/Wiki/cc_license_compatibility) - - When you want to adapt previously published work you need to ask permission for it. Otherwise please check whether you can find an open licensed work that you can adapt if their license it permits it. - diff --git a/book/installation-and-setup/figures/Terminal.PNG b/book/installation-and-setup/figures/Terminal.PNG new file mode 100644 index 0000000..d015e08 Binary files /dev/null and b/book/installation-and-setup/figures/Terminal.PNG differ diff --git a/book/installation-and-setup/figures/type 2.jpg b/book/installation-and-setup/figures/type 2.jpg deleted file mode 100644 index e214936..0000000 Binary files a/book/installation-and-setup/figures/type 2.jpg and /dev/null differ diff --git a/book/installation-and-setup/jupyter-book-setup.md b/book/installation-and-setup/jupyter-book-setup.md index b18f00a..7f90828 100644 --- a/book/installation-and-setup/jupyter-book-setup.md +++ b/book/installation-and-setup/jupyter-book-setup.md @@ -5,28 +5,54 @@ This page is useful for user type 5. ``` -Jupyter book 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. +Jupyter book 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](/book/features/overview.md). One of those additional features, for example, is the workflow to GitHub Pages. + +Concretely, this means that the teachbooks package can be used to replace the Jupyter book package when calling these features. You could think of it as `jupyter-book` being a dependency of `teachbooks`. + +```{admonition} Note +:class: tip +Don't forget to add the package `teachbooks` in the `requirements.txt` files in your book repository and to have it installed in your working environment (`pip install teachbooks`). +``` ## Build a book -As soon as you've installed your book environment with jupyter-book you can build your book locally. The official Jupyter book documentation is quite extensive. Only two notes: first navigate to the directory where your book is to leave out the `path-to-book` and use `--all` whenever building a book to make sure the table of contents fully updates: +As soon as you've installed your book environment with jupyter-book you can build your book locally. The official Jupyter book documentation is quite extensive. You can navigate to the directory where your book is to leave out the `path-to-book`. +``` +teachbooks build --all +``` +Alternatively: ``` jupyter-book build --all ``` +Note: use `--all` for the jupyter-book whenever building a book to make sure the table of contents fully updates. Or alternatively, delete the old `_build` folder before building the new book. + ## View the book locally -Once the build process is completed successfully, you will see the file location in your terminal output. Simply open this in the browser (you may have to copy/paste). +Once the build process is completed successfully, you will see the file location in your terminal output. Your terminal will look something like this. Simply open this in the browser (you may have to copy/paste). + +```{figure} ./figures/Terminal.PNG +--- +width: 80% +name: terminal +align: center +--- +Terminal +``` ```{admonition} Tip :class: tip, dropdown Bookmark the (local) file location for easy access! ``` - (setup-local-server)= ## View the book using a local webserver +```{admonition} Note +:class: tip +If your book consists only of markdown files the local python server is not necessary and you can just view the book locally. +``` + 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` diff --git a/book/installation-and-setup/user_types.md b/book/installation-and-setup/user_types.md index 3cf1168..3fa687d 100644 --- a/book/installation-and-setup/user_types.md +++ b/book/installation-and-setup/user_types.md @@ -2,7 +2,8 @@ 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. +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. 2. **Colleague providing feedback on the draft website**.
In a similar manner as students, colleages and team members can leave content related comments on the website through extensions. In this way, multiple teachers can give input in the draft of the textbook and course material without requiring and exact understanding of Jupyter Books or GitLab/GitHub. The responsible teacher (or student assistants) can then make the adaptations to the book as recommended by their colleagues. @@ -11,12 +12,9 @@ Different types of users will interact with the website or the Jupyter Books dif This type of user requires only very basic knowledge in GitLab/GitHub in order to make changes to the website themselves without needing to install any software! Making adjustments using single text editor only requires the user to be able to login into GitLab/GitHub and edit .md or .ipynb files. The changes can be done directly in the main or publish branch and if a new branch is needed for the changes then the set-up and merging can be taken care of by someone more familiar in GitLab/GitHub. 4. **Colleague making text adjustments to multiple files at the same time locally**.
- User 4 is a hybrid between type 3 and 5. Basically this user is making changes by editing the .md files locally using, for example, VS Code. Therefore, this user requires a little bit more knowledge on git (think of pulling and pushing changes) but their main focus remains to make adjustments to the content of the book by editing .md files whereas user type 4 has more knowledge to make changes to python files the book as well. This user can build the book online. + User 4 is a hybrid between type 3 and 5. Basically this user is making changes by editing the .md files locally using, for example, VS Code. Therefore, this user requires a little bit more knowledge on git (think of pulling and pushing changes) but their main focus remains to make adjustments to the content of the book by editing .md files whereas user type 5 has more knowledge to make changes to python files the book as well. This user can build the book online. 5. **Colleague making text and code (especially Python) adjustments to multiple files at the same time locally**.
-Example Image + Example Image
This user has more knowledge in GitLab/GitHub than the previous user and can basically take care of branching and merging by themselves. They know how to work with software for editing .md and .ipynb files. They can use the draft book online to view their changed in the book, or build the book locally. - This user has more knowledge in GitLab/GitHub than the previous user and can basically take care of branching and merging by themselves. They know how to work with software for editing .md and .ipynb files. They can use the draft book online to view their changed in the book, or build the book locally. - -
diff --git a/book/installation-and-setup/vscode-setup.md b/book/installation-and-setup/vscode-setup.md index feeea49..a2e76d7 100644 --- a/book/installation-and-setup/vscode-setup.md +++ b/book/installation-and-setup/vscode-setup.md @@ -15,10 +15,10 @@ VS Code can be downloaded from [here](https://code.visualstudio.com). The instal When working with Jupyter Book (or Notebooks in general), these extensions are highly recommended: -- User type 4-6: +- User type 4-5: - [MyST-Markdown](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) - adds support for MyST markdown, including previews. - [Spell checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) - Spelling checker for source code and text -- User type 5-6 +- User type 5 - [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) - enables validation of `.yml` files (the format of the Jupyter Book configuration files). - [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) - for obvious reasons. Also includes Jupyter Notebook rendering. - [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) - Your AI pair progammer diff --git a/requirements.txt b/requirements.txt index d42b694..2efce34 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,9 +2,8 @@ jupyter-book teachbooks sphinx-inline-tabs jupyterlite-sphinx +jupyterbook_patches --extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple sphinx-thebe ~= 0.9.9 ---extra-index-url https://gitlab.tudelft.nl/api/v4/projects/17983/packages/pypi/simple -jupyterbook_patches ~= 0.1.4 download_link_replacer @ git+https://gitlab.tudelft.nl/mude/sphinx-download-link-replacer