From 9d091ac6a17661a34ea318c61c797c307d62a833 Mon Sep 17 00:00:00 2001 From: Dennis den Ouden-van der Horst Date: Thu, 24 Jul 2025 17:06:24 +0200 Subject: [PATCH 1/3] Add sphinx-code-examples extension to project Integrated the sphinx-code-examples extension by updating _config.yml, _toc.yml, and requirements.txt. This adds support for code example features and links to its manual in the table of contents. --- book/_config.yml | 1 + book/_toc.yml | 1 + requirements.txt | 2 ++ 3 files changed, 4 insertions(+) diff --git a/book/_config.yml b/book/_config.yml index cb1ac1c..483e6e2 100644 --- a/book/_config.yml +++ b/book/_config.yml @@ -20,6 +20,7 @@ sphinx: - sphinx_image_inverter - sphinx_exercise - sphinx_proof + - sphinx_code_examples - sphinx_named_colors - sphinx_iframes - sphinx_prime_applets diff --git a/book/_toc.yml b/book/_toc.yml index 176a0d9..235ecf1 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -90,6 +90,7 @@ parts: - external: https://github.com/TeachBooks/Sphinx-Indexed-Definitions/blob/manual/README.md #BUMP - file: external/Sphinx-PRIME-applets/README.md - external: https://github.com/TeachBooks/Sphinx-Dropdown-Toggle/blob/main/MANUAL.md + - external: "https://github.com/TeachBooks/sphinx-code-examples/blob/main/MANUAL.ipynb" - file: features/visuals.md sections: - file: external/Sphinx-Image-Inverter/README.md diff --git a/requirements.txt b/requirements.txt index f260fb8..e40890d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -14,3 +14,5 @@ sphinx-dropdown-toggle == 1.0.0 git+https://github.com/TeachBooks/Sphinx-Thebe docutils==0.17.1 + +git+https://github.com/TeachBooks/Sphinx-Code-Examples \ No newline at end of file From 92baff0ddbddc1fbfa7ff38ff21e0fe09cab8332 Mon Sep 17 00:00:00 2001 From: Dennis den Ouden-van der Horst Date: Fri, 25 Jul 2025 14:29:14 +0200 Subject: [PATCH 2/3] Add sphinx-code-examples to requirements and docs Added 'sphinx-code-examples' to requirements.txt and updated live_code.ipynb to mention Sphinx-Exercises and Sphinx-Code-Examples for including executable code in exercises and examples. Cleaned up requirements.txt by removing a duplicate git reference. --- book/features/live_code.ipynb | 6 +++++- requirements.txt | 5 ++--- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/book/features/live_code.ipynb b/book/features/live_code.ipynb index 44c153d..1d9aa0c 100644 --- a/book/features/live_code.ipynb +++ b/book/features/live_code.ipynb @@ -173,6 +173,10 @@ "cell_type": "markdown", "metadata": {}, "source": [ + "## Exercises and examples with executable code\n", + "\n", + "To include executable code in your book inside exercises and/or examples, you can use the Sphinx extension [Sphinx-Exercises](https://ebp-sphinx-exercise.readthedocs.io/en/latest/syntax.html#alternative-gated-syntax) and/or the Sphinx extension {ref}`Sphinx-Code-Examples `.\n", + "\n", "## Alternative with JupyterLite (less well integrated)\n", "\n", "Another option to use python in your browser is to use [JupyterLite](https://jupyterlite.readthedocs.io/en/stable/). However, compared to Sphinx-Thebe, described above, this doesn't give a similar seamless interface within your page. Nevertheless, depending on your application, JupyterLite could be a useful tool, especially as it allows for three IDE types: Jupyter Notebook, Jupyter Lab and the iPython REPL.\n", @@ -181,7 +185,7 @@ "\n", "```{tip}\n", "The TeachBooks Team has focused primarily on the use of Sphinx-Thebe and has not looked at JupyterLite over the last couple years. If you have an interesting application of this tool for teaching, please get in touch, we would love to see it! You can use [GitHub Discussions](https://github.com/orgs/TeachBooks/discussions) or sent us an email at [info@teachbooks.io](mailto:info@teachbooks.io).\n", - "```" + "```\n" ] } ], diff --git a/requirements.txt b/requirements.txt index e40890d..a87b25b 100644 --- a/requirements.txt +++ b/requirements.txt @@ -10,9 +10,8 @@ sphinx-named-colors == 1.0.1 sphinx-iframes == 1.0.5 sphinx-prime-applets == 1.0.2 sphinx-dropdown-toggle == 1.0.0 +sphinx-code-examples == 1.0.1 git+https://github.com/TeachBooks/Sphinx-Thebe -docutils==0.17.1 - -git+https://github.com/TeachBooks/Sphinx-Code-Examples \ No newline at end of file +docutils==0.17.1 \ No newline at end of file From 854f558aaa6a64e7c740d3fe484dd8ee6a277fad Mon Sep 17 00:00:00 2001 From: Dennis den Ouden-van der Horst <49307154+douden@users.noreply.github.com> Date: Sat, 26 Jul 2025 21:34:39 +0200 Subject: [PATCH 3/3] Update requirements.txt --- requirements.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/requirements.txt b/requirements.txt index a87b25b..80269dd 100644 --- a/requirements.txt +++ b/requirements.txt @@ -10,8 +10,8 @@ sphinx-named-colors == 1.0.1 sphinx-iframes == 1.0.5 sphinx-prime-applets == 1.0.2 sphinx-dropdown-toggle == 1.0.0 -sphinx-code-examples == 1.0.1 +sphinx-code-examples == 1.0.2 git+https://github.com/TeachBooks/Sphinx-Thebe -docutils==0.17.1 \ No newline at end of file +docutils==0.17.1