heron Documentation

Contents

Overview

heron is a C++ analysis toolkit organised into top-level modules that each provide a focused slice of functionality. Source code is split into include/ headers and src/ implementations, with executables living in apps/. Documentation is built with Sphinx, and this index provides a map of the repository so newcomers can quickly locate relevant components.

The documentation is written for analysts, developers, and reviewers who need both a quick orientation and a precise map of the repository. It aims to highlight module responsibilities, establish shared conventions, and provide a repeatable workflow for extending the toolkit.

Repository layout

Modules live at the repository root and follow a consistent layout:

ana/: analysis configuration, selection logic, and column derivations.
io/: input/output helpers, provenance capture, and data access.
plot/: plotting utilities and presentation helpers.

Each module typically contains:

include/ for public headers (.hh).
src/ for implementations (.cpp).
macros/ for ROOT-style macros and scripts.

Supporting folders include:

apps/ for small executables and command-line entry points.
cols/ for TSV column schema references used by the event builder.
docs/ for Sphinx configuration and documentation sources.
scripts/ for helper scripts and workflows.
lib/ for build outputs (shared libraries).

Architecture at a glance

heron takes a layered approach to analysis development:

Data access and provenance live in io/ to provide a consistent interface to ROOT trees, SampleIO metadata, and run database lookups.
Analysis configuration and selections live in ana/ so derived columns and selection recipes are compiled and reusable.
Plots and presentation live in plot/ to keep visualisation logic separate from event processing.
CLI drivers in apps/ orchestrate the pipeline stages.

This separation keeps low-level data access stable while allowing higher-level analysis code to iterate rapidly.

Conventions

The codebase follows consistent style rules:

Headers begin with /* -- C++ -- */ and use concise include guards.
Library code lives in the global namespace.
Class names use descriptive PascalCase, while functions prefer lowercase_with_underscores.
Member variables often use m_ or p_ prefixes, depending on ownership.
British-English spelling is preferred in code and documentation.

Navigating the documentation

The Sphinx site is designed to be scanned quickly:

Overview pages explain the structure of the repository and how modules relate to each other.
Usage guides provide step-by-step workflows for development tasks.
Reference material (when present) captures module-specific classes, functions, and data conventions.

Use the left navigation menu to jump between sections. When adding new pages, ensure they appear in the toctree above so they are discoverable.

Building documentation

From the repository root, the documentation can be built with:

sphinx-build docs _build

The generated HTML will be located in _build/.

Documentation deployment

Documentation is automatically deployed to GitHub Pages from the default branch. The GitHub Actions workflow builds the Sphinx site, adds the .nojekyll marker, and publishes the _build/ directory to the gh-pages branch on every push to the default branch. That means documentation changes must be merged to the default branch before the public site is updated.