Skip to content

Documentation

All documentation lives in the docs/ folder and is written in Markdown, built with MkDocs and the Material for MkDocs theme. Versioned deployments to GitHub Pages are managed with mike.

Building the documentation locally

(venv) .../ddm> pip install -r requirements/docs.txt
(venv) .../ddm> mkdocs serve

mkdocs serve starts a live-reloading preview at http://127.0.0.1:8000/.

mkdocs build --strict produces the static site in site/ and fails the build on broken internal links (or pages missing from the navigation), so run it before opening a pull request. CI runs the same check in .github/workflows/docs-check.yml.

The site configuration is in mkdocs.yml at the repository root — theme, navigation, Markdown extensions and plugins.

How it is published

.github/workflows/publish-docs.yml is a reusable workflow that runs mike deploy --push <version> [alias]:

  • a push to develop publishes the dev version;
  • a vX.Y.Z tag publishes the X.Y version and moves the latest alias.

mike writes each version into its own subdirectory of the gh-pages branch and maintains the version selector shown at the top of the site. Documentation for releases older than the MkDocs migration is kept as a frozen archive under https://uzh.github.io/ddm/ddm/… (see Older Versions).

Updating screenshots

The screenshots under docs/**/img/ are generated by tools/screenshots/update_screenshots.py (Selenium + Firefox). It logs into a local DDM instance, walks the researcher and participant flows against a fixed demo project, and captures specific page elements.

Requirements: pip install -r requirements/dev.txt installs selenium and webdriver_manager; Firefox must be installed (Selenium Manager fetches geckodriver automatically).

# 1. serve the demo project
(venv) .../ddm/test_project> python manage.py runserver

# 2. regenerate the screenshots
(venv) .../ddm> python tools/screenshots/update_screenshots.py

The demo project is referenced by the PROJECT_ID / PROJECT_SLUG / FILE_UPLOADER_ID constants at the top of the script and must already exist in the local database, together with a takeout-demo.zip fixture next to the script. Useful environment variables:

  • DDM_HEADLESS=1 — run Firefox headless.
  • DDM_SCREENSHOT_DIR=<path> — write to a scratch directory instead of docs/**/img/.