Skip to content

How documentation works and how to update it

This page explains the documentation pipeline in this repository and gives practical steps for common edits.

If you are new to this repo, read this first before editing docs.

Why docs look unusual in this repo

The docs are assembled from multiple sources at build time:

  • docs/ contains user-facing content
  • docs_dev/ contains developer-facing content
  • docs_dev/utils/generate_logging_autodocs.py generates API reference pages from Python registries
  • docs_dev/utils/mirror_docs.py mirrors everything into a virtual docs tree
  • docs_anchor/ is the build input directory used by MkDocs (docs_dir: docs_anchor)

This means the final site structure is not a direct 1:1 mirror of a single folder on disk.

Documentation structure at a glance

Source content folders

  • docs/
  • User docs (tutorial, explanation, how-to, reference)

  • Mirrored to user/... in the virtual MkDocs filesystem

  • docs_dev/

  • Developer docs and docs tooling scripts
  • Mirrored to dev/... in the virtual MkDocs filesystem
  • Excludes utils/, requirements.txt, and readme_toplevel.md from mirrored output

Generated content

  • APIref/ (virtual at MkDocs build time)
  • Generated by generate_logging_autodocs.py
  • Includes:
    • logger API pages (get_daq_logger, setup_root_logger, setup_daq_ers_logger)
    • handlers and filters index pages
    • per-handler and per-filter pages from spec registries

Top-level landing page

  • docs_dev/readme_toplevel.md
  • Mirrored to virtual README.md
  • Acts as the top-level landing page in MkDocs nav

Build flow: what happens when MkDocs runs

The mkdocs.yml plugin section drives this sequence:

  1. gen-files loads docs_dev/utils/generate_logging_autodocs.py - Generates APIref/... docs into MkDocs virtual files
  2. gen-files loads docs_dev/utils/mirror_docs.py - Mirrors:
    • docs/ -> user/
    • docs_dev/ -> dev/
    • docs_dev/readme_toplevel.md -> README.md
  3. MkDocs builds from docs_anchor with the generated virtual files included

Important: docs_anchor/ is a build anchor, while the real authored content is mainly in docs/ and docs_dev/.

How to modify existing docs (simple edits)

Edit user docs

  • Edit files under docs/...
  • Example: docs/how-to/route-messages.md

Edit developer docs

  • Edit files under docs_dev/...
  • Example: docs_dev/how-to/add-a-handler.md

Edit top-level docs landing page

  • Edit docs_dev/readme_toplevel.md
  • This becomes README.md in the built docs

Edit API reference content

  • Do not directly edit generated pages in APIref/
  • Instead edit source code/registries used by generator:
  • logger APIs list in generate_logging_autodocs.py
  • handler/filter specs in Python logging modules

After changes, rebuild docs and confirm nav + links.

How to add a new documentation page

1) Create the page in the right source folder

  • User-facing page: create under docs/...
  • Developer-facing page: create under docs_dev/...

Follow existing naming style (kebab-case.md) and heading conventions.

Update the relevant tables so people can find the page:

  • docs_dev/readme_toplevel.md (site landing page)
  • docs_dev/index.md (developer docs home)
  • Any local index/reference page where it belongs

3) Add it to MkDocs navigation

Update mkdocs.yml under nav: to place the page in the desired section/order.

4) Build and validate

From repo root (with environment sourced):

. /nfs/home/emmuhamm/nightly/NFD_DEV_260410_A9/env.sh
cd /nfs/home/emmuhamm/nightly/NFD_DEV_260410_A9/sourcecode/daqpytools
mkdocs build -f mkdocs.yml

Then run mkdocs serve if you want to inspect the live nav and page rendering.

How to add or change generated API reference pages

Use docs_dev/utils/generate_logging_autodocs.py.

Common tasks:

  • Add/remove logger API pages: update LOGGER_APIS
  • Change generated index wording/sections: edit _render_logging_index()
  • Change per-type page structure: edit _render_type_page()

If generation depends on runtime imports, keep docs-time stubs (like erskafka) working so MkDocs can import safely in CI/docs environments.

Common pitfalls

  • Editing generated APIref files directly (they get regenerated)
  • Forgetting to update mkdocs.yml nav after creating a new page
  • Editing docs_anchor/ manually (it is build-oriented, not primary authored docs)
  • Running mkdocs without sourcing the workarea environment first
  • Breaking links by moving pages without updating references in landing/index docs

Quick checklist for doc PRs

  • Page added in correct source folder (docs/ or docs_dev/)
  • Page linked from index/landing docs
  • mkdocs.yml nav updated (if required)
  • mkdocs build -f mkdocs.yml succeeds in sourced environment
  • Generated API docs changes come from generator/source, not manual edits in output