Building this documentation¶

This site is built with Sphinx, writing pages in Markdown (MyST) and rendering the lab notebooks with MyST-NB.

Build¶

pip install -r docs/requirements.txt
sphinx-build -b html docs docs/_build/html
open docs/_build/html/index.html          # Linux: xdg-open

Or, from inside docs/:

cd docs
make html        # make clean, make latexpdf, … also available

Live preview¶

pip install sphinx-autobuild
sphinx-autobuild docs docs/_build/html --open-browser

Edits to any page reload the browser automatically.

PDF¶

cd docs
make latexpdf    # needs a TeX Live installation

How the build finds the course materials¶

The materials live outside docs/, and Sphinx only reads sources from inside its source directory. docs/conf.py therefore stages them before each build:

Source	Staged to	Why
`Chapters/chapter_NN/chapter_NN_lab.ipynb`	`docs/labs/`	MyST-NB renders them as pages
`Chapters/Advanced/advanced_NN_topic/advanced_NN_topic_lab.ipynb`	`docs/advanced_labs/`	same, for the four advanced modules
`Chapters/chapter_NN/chapter_NN.pdf`	`docs/_extra/slides/`	copied verbatim into the HTML output via `html_extra_path`, so `slides/chapter_NN.pdf` links resolve
`Chapters/Advanced/advanced_NN_topic/advanced_NN_topic.pdf`	`docs/_extra/slides/`	same, so the advanced decks are downloadable too

The mock exams are not staged: they are assessment material, kept out of the repository and off this site. docs/exams.md describes them without linking any file.

Both staging directories are generated and git-ignored — never edit anything in them, and never add a hand-written page under docs/labs/: it is wiped and recreated on every build. If a PDF is missing (for instance because a deck hasn’t been compiled yet), the build prints a note and continues; only that link breaks.

Notebooks are never executed

nb_execution_mode = "off" — the notebooks are rendered with the outputs they were committed with. That keeps the build fast and dependency-free (no torch, no lifelines, no network). To refresh outputs, run the notebook in Jupyter and commit it.

Adding a page¶

Create docs/<name>.md.
Add <name> to the appropriate toctree in docs/index.md.

Adding a new lecture chapter means appending its number to SLIDE_CHAPTERS in docs/conf.py and adding a row to Lecture slides; a new lab is picked up automatically by the glob in Lab notebooks, but deserves a row in that page’s table too, for the Colab badge.

Publishing¶

The site is live at https://chrisw09.github.io/Quantitative-Research-Methods/.

Deployment is automatic: .github/workflows/docs.yml builds the site and publishes it to GitHub Pages on every push to main that touches docs/, a chapter’s lab or deck PDF, an advanced module, or a project starter. It can also be run by hand from the repository’s Actions tab (Documentation → Run workflow).

Two things worth knowing about that workflow:

It builds with sphinx-build -W --keep-going, so any warning fails the build rather than silently publishing a broken page. If a deployment fails, read the log before re-running — the warning is real.
It publishes the artifact directly, without Jekyll, so the _static/ directory survives (a .nojekyll file is added as well).

The output in docs/_build/html/ is a self-contained static site, so it can equally be served from Read the Docs or any static host. The html_extra_path mechanism means the deck PDFs are part of that output — a published site is enough to teach from. The exams are not staged, so they are never part of it.