From dc1ad258ee175d1b129af16ead8cc55f2a1b5cd1 Mon Sep 17 00:00:00 2001 From: Michele Mesiti Date: Mon, 16 Mar 2026 14:45:15 +0100 Subject: [PATCH 1/2] add new exercise for ghpages Add new exercise for ghpages Updated the section titles too to match --- content/gh_workflow.md | 21 +++++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/content/gh_workflow.md b/content/gh_workflow.md index 90bc2c4c..ecc77f1e 100644 --- a/content/gh_workflow.md +++ b/content/gh_workflow.md @@ -25,7 +25,7 @@ --- -## Exercise - Deploy Sphinx documentation to GitHub Pages +## Demonstration - Deploy Sphinx documentation to GitHub Pages ````{exercise} GH-Pages-1: Deploy Sphinx documentation to GitHub Pages In this exercise we will create an example repository on GitHub and @@ -95,7 +95,24 @@ jobs: - Commit some changes to your documentation - Verify that the documentation website refreshes after your changes (can take few seconds or a minute) ```` - +## Exercise - Sphinx documentation on GitHub Pages +````{exercise} GH-Pages-2: Deploy Sphinx documentation to GitHub Pages +1. Follow the above instructions to create a new repository with a Sphinx documentation project; +2. Try adding one or more of the following to your Sphinx project: + a. API documentation (see [previous exercise](#api-exercise)) + b. Jupyter Notebook (see [previous exercise](#jupyter-exercise)) + c. change the theme (see the end of [the quickstart](#quickstart)) + + ```{important} + The computer on which the GitHub actions run is *not* your local machine, + and might not have the libraries you need to build the project. + Make sure you update the dependencies (installed with `pip` in the demonstration) appropriately. + ``` + ```{important} + Make sure the correct file paths are used where appropriate. + ``` +What do you need to change in the workflow file? +```` ## Alternatives to GitHub Pages From da46b604dc1e6166dad17d8ad3c4b3810ee193a0 Mon Sep 17 00:00:00 2001 From: Michele Mesiti Date: Mon, 16 Mar 2026 14:58:45 +0100 Subject: [PATCH 2/2] gh_workflow, ex: format, add anchors in sphinx.md --- content/gh_workflow.md | 8 ++++---- content/sphinx.md | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/content/gh_workflow.md b/content/gh_workflow.md index ecc77f1e..046e9080 100644 --- a/content/gh_workflow.md +++ b/content/gh_workflow.md @@ -98,10 +98,10 @@ jobs: ## Exercise - Sphinx documentation on GitHub Pages ````{exercise} GH-Pages-2: Deploy Sphinx documentation to GitHub Pages 1. Follow the above instructions to create a new repository with a Sphinx documentation project; -2. Try adding one or more of the following to your Sphinx project: - a. API documentation (see [previous exercise](#api-exercise)) - b. Jupyter Notebook (see [previous exercise](#jupyter-exercise)) - c. change the theme (see the end of [the quickstart](#quickstart)) +2. Try adding one or more of the following to your Sphinx project: + a. API documentation (see [previous exercise](#api-exercise) on API references) + b. a Jupyter notebook (see [previous exercise](#jupyter-exercise) on Jupyter notebooks) + c. change the theme (see the end of [the quickstart](#quickstart)) ```{important} The computer on which the GitHub actions run is *not* your local machine, diff --git a/content/sphinx.md b/content/sphinx.md index 9cef5c4c..8af3d135 100644 --- a/content/sphinx.md +++ b/content/sphinx.md @@ -66,7 +66,7 @@ But please don't give up if you don't have these - the episodes after this one w tools. ```` - +(quickstart)= ## Exercise: Sphinx quickstart ````{exercise} Sphinx-1: Generate the basic documentation template @@ -328,7 +328,7 @@ extensions = ['myst_parser', 'sphinx.ext.mathjax'] ````` - +(api-exercise)= ## Exercise: Sphinx autodoc `````{exercise} Sphinx-3: Auto-generating documentation from Python docstrings @@ -369,7 +369,7 @@ If you already have extensions from another exercise, just add `"autodoc2"` to t 5. Re-build the documentation and check the "API reference" section. ````` - +(jupyter-exercise)= ## Exercise: Using Jupyter with Sphinx `````{exercise} Sphinx-4: Writing Sphinx content with Jupyter