From 73f7e83fdf0d48bf644611494afac1825521980e Mon Sep 17 00:00:00 2001 From: Frankie Robertson Date: Fri, 20 Mar 2026 08:10:43 +0200 Subject: [PATCH 1/4] Emphasise shell work of GitHub actions in GH workflow --- content/gh_workflow.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/content/gh_workflow.md b/content/gh_workflow.md index c88f6a8f..d1d0c0da 100644 --- a/content/gh_workflow.md +++ b/content/gh_workflow.md @@ -46,7 +46,9 @@ on GitHub and create a copy to your namespace. **Step 3**: Add the GitHub Action to your new Git repository. - Add a new file at `.github/workflows/documentation.yml` (either through terminal or web interface), containing: -```yaml +```{code-block} yaml +:linenos: +:emphasize-lines: 16,19 name: documentation on: [push, pull_request, workflow_dispatch] @@ -75,8 +77,11 @@ jobs: publish_dir: _build/ force_orphan: true ``` -- You don't need to understand all of the above, but you - might spot familiar commands in the `run:` sections. +- You don't need to understand all of the above + -- you should mainly pay attention the highlighted lines + which are shell commands (we know this because they are part of a `run: |` section). + The first uses `pip` to install the dependencies and the second runs `sphinx-build` + to actually build the documentation (as we saw in the previous episode). - After the file has been committed (and pushed), check the action at `https://github.com/USER/documentation-example/actions` (replace `USER` with your GitHub username). From 939279fa4061676e162161bea60b61d6a164dbe1 Mon Sep 17 00:00:00 2001 From: Frankie Robertson Date: Fri, 20 Mar 2026 08:11:02 +0200 Subject: [PATCH 2/4] Add solution and more hints to GH-Pages-2 exercise --- content/gh_workflow.md | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/content/gh_workflow.md b/content/gh_workflow.md index d1d0c0da..78ee7c4a 100644 --- a/content/gh_workflow.md +++ b/content/gh_workflow.md @@ -103,13 +103,14 @@ 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) 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)) + 1. API documentation (see [previous exercise](#api-exercise) on API references) which requires the `sphinx-autodoc2` package. + 2. a Jupyter notebook (see [previous exercise](#jupyter-exercise) on Jupyter notebooks) which requires the `myst-nb` package. + 3. change the theme (see the end of [the quickstart](#quickstart)). You can browse themes and find their package names on the [Sphinx themes gallery](https://sphinx-themes.org/#themes). ```{important} The computer on which the GitHub actions run is *not* your local machine, @@ -117,11 +118,32 @@ jobs: Make sure you update the dependencies (installed with `pip` in the demonstration) appropriately. ``` ```{important} - Make sure the correct file paths are used where appropriate. + Make sure the correct file paths are used. This will require adjusting paths from the example from the previous episode to the new layout. Note many paths, including e.g. the `autodoc2_packages` preference are now relative to the `doc/` directory. ``` What do you need to change in the workflow file? ```` +`````{solution} Solution +1. **API documentation** + 1. Change line 16 of `.github/workflows/documentation.yml` from `pip install sphinx sphinx_rtd_theme myst_parser` to `pip install sphinx sphinx_rtd_theme myst_parser sphinx-autodoc2`. + 2. Follow the instructions in [Sphinx-3](#api-exercise) changing paths so that: + 1. `multiply.py` is `src/multiply` and is specified as `../src/multiply.py` in the `autodoc2_packages` preference in `conf.py` + 2. `conf.py` is `doc/conf.py` + 3. `index.md` is `doc/index.md`. + 3. Commit and push your changes, verify the action has run successfully, and view the built site in your browser. +2. **a Jupyter notebook** + 1. Change line 16 of `.github/workflows/documentation.yml` from `pip install sphinx sphinx_rtd_theme myst_parser` to `pip install sphinx sphinx_rtd_theme myst_parser myst-nb`. + 2. Follow the instructions in [Sphinx-4](#jupyter-exercise) changing paths so that: + 1. `flower.md` is `docs/flower.md` + 2. `conf.py` is `doc/conf.py` + 3. `index.md` is `doc/index.md`. + 3. Commit and push your changes, verify the action has run successfully, and view the built site in your browser. +3. **change the theme** + 1. Change line 16 of `.github/workflows/documentation.yml` and add the theme package if necessary. + 2. In `docs/config.py` change `html_theme = 'sphinx_rtd_theme'` to the name of your chosen theme. + 3. Commit and push your changes, verify the action has run successfully, and view the built site in your browser. +````` + ## Alternatives to GitHub Pages - [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/) From 0cc787a3b8fb8a5ea426aac6ca2f15eb1f93bde1 Mon Sep 17 00:00:00 2001 From: Michele Mesiti Date: Fri, 20 Mar 2026 08:58:07 +0100 Subject: [PATCH 3/4] solution in exercise box, change ex title --- content/gh_workflow.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/content/gh_workflow.md b/content/gh_workflow.md index 78ee7c4a..52c6ad64 100644 --- a/content/gh_workflow.md +++ b/content/gh_workflow.md @@ -105,7 +105,8 @@ jobs: ```` ## Exercise - Sphinx documentation on GitHub Pages -````{exercise} GH-Pages-2: Deploy Sphinx documentation to GitHub Pages +````{exercise} GH-Pages-2: Putting it all together + 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: 1. API documentation (see [previous exercise](#api-exercise) on API references) which requires the `sphinx-autodoc2` package. @@ -121,9 +122,8 @@ jobs: Make sure the correct file paths are used. This will require adjusting paths from the example from the previous episode to the new layout. Note many paths, including e.g. the `autodoc2_packages` preference are now relative to the `doc/` directory. ``` What do you need to change in the workflow file? -```` -`````{solution} Solution +```{solution} Solution 1. **API documentation** 1. Change line 16 of `.github/workflows/documentation.yml` from `pip install sphinx sphinx_rtd_theme myst_parser` to `pip install sphinx sphinx_rtd_theme myst_parser sphinx-autodoc2`. 2. Follow the instructions in [Sphinx-3](#api-exercise) changing paths so that: @@ -142,7 +142,8 @@ What do you need to change in the workflow file? 1. Change line 16 of `.github/workflows/documentation.yml` and add the theme package if necessary. 2. In `docs/config.py` change `html_theme = 'sphinx_rtd_theme'` to the name of your chosen theme. 3. Commit and push your changes, verify the action has run successfully, and view the built site in your browser. -````` +``` +```` ## Alternatives to GitHub Pages From a48fdbb5fc9f673b797280c1ad06ee5dceda46f7 Mon Sep 17 00:00:00 2001 From: Michele Mesiti Date: Fri, 20 Mar 2026 09:00:11 +0100 Subject: [PATCH 4/4] fix missing .py extension --- content/gh_workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/gh_workflow.md b/content/gh_workflow.md index 52c6ad64..105d8be9 100644 --- a/content/gh_workflow.md +++ b/content/gh_workflow.md @@ -127,7 +127,7 @@ What do you need to change in the workflow file? 1. **API documentation** 1. Change line 16 of `.github/workflows/documentation.yml` from `pip install sphinx sphinx_rtd_theme myst_parser` to `pip install sphinx sphinx_rtd_theme myst_parser sphinx-autodoc2`. 2. Follow the instructions in [Sphinx-3](#api-exercise) changing paths so that: - 1. `multiply.py` is `src/multiply` and is specified as `../src/multiply.py` in the `autodoc2_packages` preference in `conf.py` + 1. `multiply.py` is `src/multiply.py` and is specified as `../src/multiply.py` in the `autodoc2_packages` preference in `conf.py` 2. `conf.py` is `doc/conf.py` 3. `index.md` is `doc/index.md`. 3. Commit and push your changes, verify the action has run successfully, and view the built site in your browser.