diff --git a/.gitignore b/.gitignore index bb960ab..646bdab 100644 --- a/.gitignore +++ b/.gitignore @@ -139,4 +139,5 @@ book/.jupyterlite.doit.db # TeachBooks **.teachbooks/ book/_toc_with_local_paths.yml -book/_git/ \ No newline at end of file +book/_git/ +book/conf.py \ No newline at end of file diff --git a/book/_config.yml b/book/_config.yml index 7dfb1d3..7df42ac 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -2,7 +2,7 @@ title: TeachBooks Manual author: TeachBooks Development Team and TeachBooks users, built with TeachBooks, CC BY 4.0 execute: - execute_notebooks: 'off' + execute_notebooks: 'auto' only_build_toc_files: true @@ -17,8 +17,8 @@ sphinx: - teachbooks_favourites - teachbooks_sphinx_grasple - sphinx_apa_references - - sphinx_github_alerts config: + language: en html_js_files: - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js thebe_config: @@ -45,6 +45,14 @@ sphinx: macros: "newcolor": ['\definecolor{newcolor}{RGB}{111, 29, 119}{\color{newcolor}#1}',1] named_colors_custom_colors: {'onlylight':[165,21,160],'lightanddark':[45,180,117,204,158,110],'hyphen-color':[45,180,117,165,21,160],'attributiongrey':[150,150,150]} + metadata_figure_settings: + style: + placement: hide + license: + summaries: false + individual: false + nb_execution_includepatterns: "**/MANUAL.ipynb" + git_show_all_authors: true teachbooks: attribution_location: margin diff --git a/book/_static/remove_author.css b/book/_static/remove_author.css new file mode 100644 index 0000000..a99acdb --- /dev/null +++ b/book/_static/remove_author.css @@ -0,0 +1,4 @@ +/* Hide the default Jupyter Book author footer */ +.component-author { + display: none; +} diff --git a/book/_toc.yml b/book/_toc.yml index dcbfc9d..6122b8d 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -88,6 +88,10 @@ parts: - file: features/exercise.md - external: https://github.com/TeachBooks/Sphinx-ref-graph/blob/manual/README.md - external: https://github.com/TeachBooks/Sphinx-GitHub-Alerts/blob/main/README.md + - external: https://github.com/TeachBooks/Sphinx-Metadata-Figure/blob/main/MANUAL.ipynb + - external: https://github.com/TeachBooks/Sphinx-Gated-Directives/blob/main/MANUAL.md + - external: https://github.com/TeachBooks/TeachBooks-Questions/blob/main/MANUAL.md + - external: https://github.com/TeachBooks/TeachBooks-Fetch/blob/main/MANUAL.md - file: features/visuals.md sections: - external: https://github.com/TeachBooks/Sphinx-Accessibility/blob/manual/README.md @@ -98,6 +102,7 @@ parts: - file: features/apa - file: external/Sphinx-Named-Colors/README.md - external: https://github.com/TeachBooks/Sphinx-Dropdown-Toggle/blob/main/MANUAL.md + - external: https://github.com/TeachBooks/Sphinx-Sticky-Margin/blob/main/MANUAL.md - file: features/students sections: - file: external/annotater/README.md diff --git a/book/external/JupyterBook-Patches b/book/external/JupyterBook-Patches index c5cb27a..99aeda4 160000 --- a/book/external/JupyterBook-Patches +++ b/book/external/JupyterBook-Patches @@ -1 +1 @@ -Subproject commit c5cb27a87b193228c45edb95580f9ee2d82b27df +Subproject commit 99aeda40ae0cfa06eb290ba5c3a6b9b81eb3992d diff --git a/book/external/sphinx-iframes b/book/external/sphinx-iframes index d92bc03..2bc21b6 160000 --- a/book/external/sphinx-iframes +++ b/book/external/sphinx-iframes @@ -1 +1 @@ -Subproject commit d92bc03af5f067453caf104a424e0cc0ebdbf04b +Subproject commit 2bc21b6174b8e7dbd15c862c219bd506e06f9d13 diff --git a/book/features/draft-release.md b/book/features/draft-release.md index 9ce1d4c..ebf5fa4 100644 --- a/book/features/draft-release.md +++ b/book/features/draft-release.md @@ -28,7 +28,7 @@ This page is useful for user type 3-5. (draft-release)= # Draft-Release Workflow -Often it is necessary to prepare, review and edit materials in parallel to material that is currently being used by students, or another target audience. This workflow enables an author to easily maintain separate versions of a book without having to repeatedly comment out lines of a table of contents or page when building different versions. It is also easy to implement in CI/CD settings (it is already implemented in the {ref}Deploy Book Workflow `, which builds our TeachBooks). +Often it is necessary to prepare, review and edit materials in parallel to material that is currently being used by students, or another target audience. This workflow enables an author to easily maintain separate versions of a book without having to repeatedly comment out lines of a table of contents or page when building different versions. It is also easy to implement in CI/CD settings (it is already implemented in the {ref}`Deploy Book Workflow `, which builds our TeachBooks). ```{admonition} Why is this useful? :class: tip diff --git a/book/features/favourites.md b/book/features/favourites.md index 924ce7c..5e62bb2 100644 --- a/book/features/favourites.md +++ b/book/features/favourites.md @@ -30,18 +30,25 @@ TeachBooks Favourites is a Sphinx extension which collects all of TeachBooks' fa - [Download link replacer](../external/Download-Link-Replacer/README.md) - [Sphinx image inverter](../external/Sphinx-Image-Inverter/README.md) - [Sphinx iframes](../external/sphinx-iframes/README.md) -- [Sphinx exercise (including TeachBooks contributions)](https://ebp-sphinx-exercise.readthedocs.io/en/latest/) +- [Sphinx exercise (from Executable Books including TeachBooks contributions)](https://ebp-sphinx-exercise.readthedocs.io/en/latest/) - [Teachbooks Sphinx tippy](../external/teachbooks-sphinx-tippy/README.md) - [Sphinx named colors](../external/Sphinx-Named-Colors/README.md) - [Sphinx dropdown toggle](../_git/github.com_TeachBooks_Sphinx-Dropdown-Toggle/main/MANUAL.md) -- [Sphinx proof (including TeachBooks contributions)](https://sphinx-proof.readthedocs.io/en/latest/) +- [Sphinx proof (from Executable Books including TeachBooks contributions)](https://sphinx-proof.readthedocs.io/en/latest/) - [Sphinx code examples](../_git/github.com_TeachBooks_sphinx-code-examples/main/MANUAL.ipynb) - [Sphinx accessibility](../_git/github.com_TeachBooks_Sphinx-Accessibility/manual/README.md) -- [Sphinx toggle button (TeachBooks contribution to the original)](https://sphinx-togglebutton.readthedocs.io/en/latest/) +- [Sphinx toggle button (from Executable Books including TeachBooks contributions)](https://sphinx-togglebutton.readthedocs.io/en/latest/) - [Notebook execution patterns](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.md) - [Sphinx Launch Buttons](../external/Sphinx-launch-buttons/README.md) -- [Sphinx External ToC (TeachBooks contribution to the original)](https://github.com/TeachBooks/sphinx-external-toc/blob/main/README.md) - [Sphinx GitHub Alerts](../_git/github.com_TeachBooks_Sphinx-GitHub-Alerts/main/README.md) +- [Sphinx Metadata Figure](../_git/github.com_TeachBooks_Sphinx-Metadata-Figure/main/MANUAL.ipynb) +- [Sphinx last updated by git (from Matthias Geier, TeachBooks version of the original)](https://github.com/TeachBooks/sphinx-last-updated-by-git) +- [Sphinx Gated Directives](../_git/github.com_TeachBooks_Sphinx-Gated-Directives/main/MANUAL.md) +- [Teachbooks Zoomies](https://github.com/TeachBooks/TeachBooks-Zoomies/) +- [TeachBooks Questions](../_git/github.com_TeachBooks_TeachBooks-Questions/main/MANUAL.md) +- [Sphinx Sticky Margin](../_git/github.com_TeachBooks_Sphinx-Sticky-Margin/main/MANUAL.md) +- [TeachBooks Fetch](../_git/github.com_TeachBooks_TeachBooks-Fetch/main/MANUAL.md) +- [Sphinx to do (from core sphinx](https://www.sphinx-doc.org/en/master/usage/extensions/todo.html) The extension [Open in new tab](https://pypi.org/project/sphinx-new-tab-link/) is nice, but is not compatible with all setups (dependency clash) so is not included in TeachBooks-Favourites. diff --git a/book/features/plotly.ipynb b/book/features/plotly.ipynb index 6852a21..7f92684 100644 --- a/book/features/plotly.ipynb +++ b/book/features/plotly.ipynb @@ -16,15 +16,57 @@ "\n", "# Interactive plots: plotly\n", "\n", - "The use of the [plotly](https://plotly.com/python/getting-started/) package is an example which allows you to create HTML/Javascript widgets from python code without any knowledge on HTML/Javascript." + "The use of the [plotly](https://plotly.com/python/getting-started/) package is an example which allows you to create HTML/Javascript widgets from python code without any knowledge on HTML/Javascript. The example below is taken from the FEM-module by Frans van der Meer." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "The example below is taken from the FEM-module by Frans van der Meer.\n", - "When using Plotly graphs, make sure the notebook is executed in Jupyter Lab / Jupyter Notebook for the figures to be shown in the book. Running the code in VS code might break the result in the book, although the output is visible in VS code. Alternatively, add the following lines of code to your notebook to have a valid output in the book as well:\n", + "If you want to create the plot during the build of the book, don't use `fig.show()` but use the code below:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "from IPython.display import HTML\n", + "\n", + "def show_plotly(fig):\n", + " # Use HTML when building book in CI environment\n", + " if os.environ.get(\"CI\") == \"true\":\n", + " return HTML(fig.to_html(include_plotlyjs=\"cdn\"))\n", + "\n", + " # Local execution in Jupyter Notebook / JupyterLab / VS Code\n", + " fig.show()\n", + "\n", + "....\n", + "\n", + "show_plotly(fig)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Make sure you have in your `_config.yml`:\n", + "\n", + "```yaml\n", + "execute:\n", + " execute_notebooks: \"auto\"\n", + "```\n", + "\n", + "Eventually in combination with [](../_git/github.com_TeachBooks_Sphinx-NB-Execution-Patterns/Manual/README.md)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Alternatively, you can run the notebook locally before building the book. This is not recommended for the combination with git because you will be committing binary output to the repository. When pre-generating Plotly graphs, make sure the notebook is executed in Jupyter Lab / Jupyter Notebook for the figures to be shown in the book. Running the code in VS code might break the result in the book, although the output is visible in VS code. Add the following lines of code to your notebook to have a valid output in the book as well:\n", "\n", "```python\n", "import plotly.io as pio\n", diff --git a/book/images/nothing.svg b/book/images/nothing.svg new file mode 100644 index 0000000..2c4a47c --- /dev/null +++ b/book/images/nothing.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/book/installation-and-setup/tools.md b/book/installation-and-setup/tools.md index 0e83db0..537fe63 100644 --- a/book/installation-and-setup/tools.md +++ b/book/installation-and-setup/tools.md @@ -9,26 +9,26 @@ This page is useful for user type 4-5. The setup of tools and URLs is dependent on agreements you've made on [collaboration](./collab.md). -Choosing between GitHub and GitLab depends on multiple criteria. GitHub provides more functionalities, but you might prefer the TU Delft-closed GitLab system if you're a TU Delft employee. +Choosing between GitHub and GitLab depends on multiple criteria. GitHub provides more functionalities, but you might prefer the TU Delft(-closed) GitLab system if you're a TU Delft employee. ## Account GitHub is owned by Microsoft and anyone can make an account. This allows anyone to interact with the source code of your book by posting issues, forking (duplicating while allowing to sync) your book and suggesting changes with pull requests. -For the TU-Delft closed GitLab system only TU Delft account holders can interact with the source code your book, making it not as open as GitHub: collaboration and reuse is inly pissible with manual exports of the source code. Individual external accounts can be requested for. +For the TU-Delft closed GitLab system, only TU Delft account holders can interact with the source code your book, making it not as open as GitHub: collaboration and reuse is only possible with manual exports of the source code. Individual external accounts can be requested for. ## Book URL Github allows you to host your book on the GitHub server using GitHub pages (to be recognized by the `.github.io/` url, for example the [template book](https://teachbooks.github.io/template/)), which takes all the steps of hosting out of your hands. Next to GitHub-provided URLs, you can set up a custom owned URL, although this requires some additional skills on a domain which you should own. -If you're part of TU Delft, you can put your book in the [TUDelft-Book organisation](https://github.com/tudelft-books), which allows you to host your book at `oit.tudelft.nl/`. If you've a private book which is part of the [GitHub Enterprise TU Delft](https://github.com/enterprises/tudelft) and is using SSO, a random url is generated `.github.io/`. For courses we advise you to create a organization with the course name so that the URL represent that course. +If you're part of TU Delft, you can put your book in the [TUDelft-Book organisation](https://github.com/tudelft-books), which allows you to host your book at `oit.tudelft.nl/`. If you've a private book which is part of the [GitHub Enterprise TU Delft](https://github.com/enterprises/tudelft) and is using SSO, a random url is generated `.github.io/`. For courses we advise you to create an organization with the course name so that the URL represent that course. On TU Delft's GitLab you need a webserver, which was offered by TeachBooks in the past (to be recognized by the url `teachbooks.tudelft.nl/`), and is still offered by the TU Delft OIT team (to be recognized by the url `interactivetextbooks.tudelft.nl/`). ## Real-time editing book -Editing the book can happen both locally as online on GitHub/GitLab. If done locally, the book can be generated and viewed locally too (typically takes around 1 minute) but this requires you to be at least user type 4 or 5 depending on the book content. The built book can also be viewed online separate from the released version. +Editing the book can be done both locally and online on GitHub/GitLab. If done locally, the book can be generated and viewed locally too (typically takes around 1 minute) but this requires you to be at least user type 4 or 5 depending on the book content. The built book can also be viewed online separate from the released version. -On GitHub we developed a [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). For a private repository, there is an extensive but limited amount of actions-minutes required for published your book. If this proves to be a limit, consider applying for [Teacher benefits](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) or joining the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft). +On GitHub we developed an [automatic process which builds the book and publishes it online](../external/deploy-book-workflow/README.md) in a very flexible way (publication of multiple version of the book, insights in book building errors, parallel so fast build, custom urls in subdirectories). For a private repository, there is an extensive but limited amount of actions-minutes required for publishing your book. If this proves to be a limit, consider applying for [Teacher benefits](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) or joining the [GitHub Enterprise of TU Delft](https://github.com/enterprises/tudelft). -On GitLab a webserver is required to process book-changes online. Both we and other people at TU Delft have a simplistic workflow which can be used when you're set up on those Git environments and webservers. This simplistic workflow doesn't build all branches, is not easily adaptable, doesn't cache environments, doesn't give a visual summary, and doesn't allow for parallel processes (for every build a runner needs to be assigned for which there's typically only one available). If you want to use GitLab but still want to make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in an active editing-phase since constant copyright checks have to be performed. The amount of computing power available is dependent on how you set the server yourself. +For GitLab a webserver is required, if GitLab pages is not enabled, to process book-changes online. Both we and other people at TU Delft have a simplistic workflow which can be used when you're set up on those Git environments and webservers. This simplistic workflow doesn't build all branches, is not easily adaptable, doesn't cache environments, doesn't give a visual summary, and doesn't allow for parallel processes (for every build a runner needs to be assigned for which there's typically only one available). If you want to use GitLab but still want to make use of the GitHub workflow, you can [mirror your repository to GitHub](https://docs.gitlab.com/ee/user/project/repository/mirror/push.html#set-up-a-push-mirror-from-gitlab-to-github). For the TU Delft OIT webserver you’re required to publish your book more officially, it cannot be used for viewing your book online in an active editing-phase since constant copyright checks have to be performed. The amount of computing power available is dependent on how you set the server yourself. ## Setting up book repository and website On GitHub you can start right away with a git environment and online book using our [template](../external/template/README.md) without the need for any webserver setup! diff --git a/book/installation-and-setup/versions_URLs.md b/book/installation-and-setup/versions_URLs.md index d948409..4561c1d 100644 --- a/book/installation-and-setup/versions_URLs.md +++ b/book/installation-and-setup/versions_URLs.md @@ -6,8 +6,10 @@ If you plan on maintaining only one public version, it is advisable to set `BEHA To share the built book / website of old versions for your book on GitHub you have a few options: - Create a branch for each version. When doing this, [the GitHub workflow](../external/deploy-book-workflow/README.md) will build it on GitHub pages. Here's a few tips: - - It's advised to use the version as branch name. In case of versions per academic year, you can just name each branch to the current academic year, this leads to the URL with the same academic year.. - - It is recommended to update the primary branch as the `PRIMARY BRANCH` when using the [GitHub workflow](gh-workflow-settings) whenever a new version is considered to be the most primary one. This ensures that readers are redirected to a consistent URL, even when new versions of the book are added later. + - It's advised to use the version as branch name, making it very clear which branch to which website. In case of versions per academic year, you can just name each branch to the current academic year, this leads to the URL with the same academic year. In case of book which are more stable over year, you could consider a simpler v1.1. See the page on [TeachBooks versioning](./versioning_changelog.md) for more information about how to name versions (and thus branches). + - You might consider a draft version for each version, in which you collect contributions leading up to a new release of the non-draft versoin. It's advised to name the draft branches so that the link with the non-draft version is obvious. Furthermore, you might consider the [Draft-Release Workflow](../features/draft-release.md) + - Whenever a new version is considered to be the most primary one, it is recommended to update the branch `PRIMARY BRANCH` when using the [GitHub workflow](gh-workflow-settings). This ensures that readers which have visited your book before are redirected to a consistent URL, even when new versions of the book are added later. Furthermore, it revert new readers to the most primary one. + - Set the primary branch (or its draft branch) as the default branch in git, so that that branch is directly visible when people visit your repository. Furthermore, this is probably the branch where you'd like contributers to start from when forking / opening a pull request. - Eventually, you can add old branches to the list of `BRANCHES_ARCHIVED` when using the [GitHub workflow](gh-workflow-settings) to include a banner on the page indicating its archived state. Alternatively, you can add a banner manually to `_config.yml`, as explained [here](../basic-features/banner.md). - If you're using tags (as will be explained in [later](./versioning_changelog.md)), you can create a branch from a tag locally by running: `git branch `. - If you have many version of the book, at some point you might reach the 1 GB GitHub Pages limit. This is only expected for extremely large books with a lot of non-text-based (binary) content. To prevent going over that limit, store large content not used for building the website (like images) on an external server. This can be another GitHub repository or a (paid) object store. diff --git a/book/references.bib b/book/references.bib index 0358ae3..884c860 100644 --- a/book/references.bib +++ b/book/references.bib @@ -207,3 +207,14 @@ url = {https://arxiv.org/abs/1301.3781}, } +@misc{TeachBooksLogo, + author = {Veronica Comin}, + title = {The logo of TeachBooks.}, + year = {2024}, + date = {2024-11-13}, + note = {License: CC BY}, + url = {https://github.com/TeachBooks/logos_and_visualisations}, + howpublished = {\url{https://github.com/TeachBooks/logos_and_visualisations}}, + copyright = {© TeachBooks 2024}, +} + diff --git a/requirements.txt b/requirements.txt index 8cc3f83..2efadd0 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,8 +1,13 @@ -teachbooks == 0.2.3 +teachbooks == 0.2.7 sphinx-inline-tabs -git+https://github.com/TeachBooks/TeachBooks-Favourites +git+https://github.com/TeachBooks/TeachBooks-Favourites@all_authors teachbooks-sphinx-grasple sphinx-apa-references + +# For executing Jupyter Notebooks +myst_nb +numpy +matplotlib diff --git a/sphinx-autobuild.sh b/sphinx-autobuild.sh new file mode 100644 index 0000000..708e580 --- /dev/null +++ b/sphinx-autobuild.sh @@ -0,0 +1,27 @@ +# Deactivate any active conda environment +conda deactivate 2>/dev/null || true + +# Clear conda environment variables +unset CONDA_DEFAULT_ENV CONDA_PROMPT_MODIFIER 2>/dev/null || true + +# Create a Python virtual environment +python -m venv venv + +# Activate the virtual environment +source venv/Scripts/activate + +# Install required packages from requirements.txt and sphinx-autobuild +pip install -r requirements.txt sphinx-autobuild + +# Initialize Jupyter Book configuration for the book directory +jupyter-book config sphinx book/ + +# Disable display of all git authors in Sphinx documentation +# by changing 'git_show_all_authors' from True to False in conf.py +sed -i 's/git_show_all_authors = True/git_show_all_authors = False/' book/conf.py + +sed -i "s/external_toc_path = '_toc.yml'/external_toc_path = '_toc_with_local_paths.yml'/" book/conf.py + +# Build and serve the Sphinx documentation with auto-reload +# Opens browser automatically and ignores build artifacts and Python files +sphinx-autobuild book book/_build/html --open-browser --ignore "book/_build/**" --ignore "*.py" --ignore "book/references.bib" --ignore "book/_toc_with_local_paths.yml" --pre-build "teachbooks build book/ --process-only" \ No newline at end of file