Documentation site

The project documentation is written in Markdown under docs/ and rendered with Material for MkDocs. The MkDocs configuration and pinned dependencies are stored in mkdocs.yml and requirements-docs.txt at the repository root.

Local preview with Conda

Create a dedicated environment once:

conda create --name hct-docs python=3.12 -y
conda activate hct-docs
python -m pip install -r requirements-docs.txt

From the repository root, start the development server:

mkdocs serve

Open http://127.0.0.1:8000/. MkDocs watches the documentation and configuration files and refreshes the site after changes.

Validate a production build

Run the same strict build used in continuous integration:

mkdocs build --strict

The generated site is written to site/. It is a disposable build product and is not committed to Git.

Add or reorganize pages

Add Markdown files under docs/, then place them in the nav section of mkdocs.yml. Top-level documentation areas use README.md as their landing page. Nested sections use index.md, which lets the section heading serve as both a link and an expand/collapse control in the rendered navigation.

Links between documentation pages should be relative to the source Markdown file. Links to repository files outside docs/ should use a GitHub URL because MkDocs cannot include files outside its documentation directory.

Document a data product

Lifecycle landing pages such as Source data and Processed datasets should stay short and list their dataset families without a diagram. A dataset-family landing page may include one compact lineage diagram that shows how all outputs in that family relate. Use exact dataset names and omit code or transformation nodes. Color external inputs blue, pipeline-support datasets amber, reusable datasets green, and model-specific derivatives purple when the distinction is useful. Order the linked dataset pages below the diagram by dependency. Every node in a dataset-family or coverage-lineage diagram must be one concrete stored dataset; use prose, tables, edge labels, or Mermaid subgraphs for conceptual groupings and processing stages.

Analysis-family diagrams use the same lifecycle logic: upstream inputs are blue, subsection-local support products are amber, analysis-layer datasets reused across pipelines are green, and terminal datasets read by analysis code are purple. A dashed amber node may identify a configured or incomplete local product. Stop these diagrams at the datasets; document estimation code, tables, and figures in the Analyses section. Place project-built mappings with the substantive domain whose identifiers they connect rather than in a global mappings bucket.

Create one page for each durable dataset or closely related dataset family. No YAML metadata is required. Keep the page short and use this order:

1. one sentence explaining the dataset;
2. a small Mermaid diagram showing inputs, transformation, and output;
3. grain, keys, location, and builder;
4. the important transformation choices and columns;
5. commands, consumers, and known limitations.

Within a large dataset family, group pages by downstream role only when this makes the navigation easier to scan. Use the labels pipeline support for stored intermediates consumed inside that data pipeline, reusable for canonical products consumed across project areas, and model-specific for derivatives built primarily for model training or scoring. These labels describe present use, not data quality or permanence, and should be updated if the consumers change.

On an individual dataset page, the diagram should show the exact input datasets, transformation, and output represented by that page. Diagrams are written directly in the page. Prefer top-to-bottom flow, use no more than about ten nodes, and do not reproduce the entire repository lineage. The following styles are used throughout the Data section:

flowchart LR
    input[(Input dataset)] --> transform[Transformation]
    transform --> output[(Output dataset)]

    classDef source fill:#e8eef7,stroke:#52739e
    classDef process fill:#fff0cc,stroke:#a66b00
    classDef data fill:#e2f2e7,stroke:#3b7a4b
    class input source
    class transform process
    class output data

Source-data pages are simpler: record where the data came from, what files were received, their grain and identifiers, and any missing provenance. Do not mix vendor descriptions with project-built outputs.

Document an analysis

Organize analysis pages by stable research theme rather than manuscript table number. A theme landing page should show the short path from documented inputs to manuscript-ready artifacts and link to one page per analysis concept. Keep multiple outcomes, samples, or panels together when they are produced by one analysis pipeline.

Use blue cylinders for direct upstream inputs, purple cylinders for analysis-ready datasets, and amber cylinders for saved models, predictions, metrics, or other analysis support. Show analysis code or estimation steps as neutral double-bordered boxes and generated LaTeX tables as green slanted output nodes. Dashed nodes identify planned or incomplete products while retaining the shape associated with their intended role.

Each analysis page should state the research question, input links, sample and mode, specifications, uncertainty calculation, commands, persisted state, artifact paths, and current limitations. Generic container and Slurm mechanics belong under Workflows. Generated LaTeX is a fragment; captions, labels, notes, and the surrounding table environment belong to the manuscript or preview document.

Place the page under the matching lifecycle and data-family directory in docs/data/: source, processed, model-outputs, or analysis. Update the matching section in mkdocs.yml; do not add product pages directly to the docs/data/ root.

When a data product changes, update its page in the same pull request. Review the rendered page locally and run mkdocs build --strict before committing.

Deployment

The documentation workflow validates changes proposed in pull requests. A push to main builds the site and deploys the generated artifact to GitHub Pages. Repository administrators must select GitHub Actions as the Pages source under Settings → Pages → Build and deployment before the first deployment.