2. A teaching site built with Sphinx¶
Bob McNabb’s site, iamdonovan.github.io, holds the practicals for several Ulster modules (EGM101, EGM310, EGM702, EGM703, EGM722) alongside research and writing pages. Its repository is public, github.com/iamdonovan/iamdonovan.github.io, so how it is made can be read directly. Everything below was taken from that repository in November 2026.
2.1 Source and tools¶
The source sits in a docs folder: 188 reStructuredText (.rst) files and one Python file, conf.py, which configures Sphinx. A practical is one page; the SAR practical for EGM703 Week 3, for example, is docs/teaching/egm703/practicals/week3.rst, with its 27 screenshots in docs/img/egm703/week3/ and the data in docs/files/EGM703_Week3.zip.
The build environment is a conda file, environment.yml, naming Sphinx extensions: sphinx-book-theme for the look (left navigation, contents panel, search, light and dark mode), sphinxcontrib-bibtex for references from a refs.bib, sphinx-design for cards and tabs, and sphinx-copybutton for copying code. The site is licensed CC BY-SA 4.0.
2.2 Build and publish¶
There is no CI workflow. The Makefile builds into a folder beside the repository (../../iamdonovan-sphinx-docs), which is a checkout of the gh-pages branch; GitHub Pages serves that branch. Publishing is therefore: edit the .rst, run make html, commit and push the built pages on gh-pages, and commit the source on main. The same Makefile has a latexpdf target, so a PDF can come from the same source through Sphinx’s LaTeX writer.
2.3 Editing after publication¶
The theme is configured with use_repository_button, use_issues_button and use_edit_page_button. Every page therefore carries three icons: one to the repository, one to open an issue (so a student can report a broken step), and one to edit that page’s source on GitHub. The commit history shows the rhythm: small, frequent, plainly described changes (update instructions for spss version 31, re-order teaching links, add carrivick LIA paper).
2.4 What it does well¶
-
One plain-text source per page, under version control, with a written environment.
-
Edit and issue buttons on every page, which invite corrections from readers.
-
A theme that gives navigation, search and a contents panel with no custom code.
-
Course materials split out: each module’s code and data have their own repository (for example egm722), and the research packages (for example spymicmac) document themselves on Read the Docs from a
.readthedocs.yaml, so their documentation is rebuilt by the host on every push.