Report generation ================= Configure with ``-DENABLE_SNT_REPORT=ON`` to build report generation (the default when DIP is enabled). ``-DENABLE_SNT_REPORT=OFF`` removes the Brief++ dependency. In a report-disabled build, the C++ and C report entry points return an error, while the CLI command, Python binding, and REST route are unavailable. ``snt::dip::report::generate`` writes a report from an evaluated ``snt::dip::Environment``. The application-facing ``snt::api::generate_dip_report`` calls the same generator. Both use the document model in the DIP library. The renderer is `Brief++ `_, a header-only library. Supported formats are TeX, PDF, Markdown, reStructuredText, HTML, Typst, plain text, and Brief++ document JSON. All contain the evaluated report data; TeX and PDF additionally use the styled cover and contents page. Generating a report ------------------- Parse a DIPfile project and pass the resulting environment to the API: .. code-block:: cpp #include #include snt::dip::DIP parser; parser.add_project("DIPfile"); auto env = parser.parse(true); snt::dip::report::ReportOptions options; options.input_label = "DIPfile"; options.introduction_file = "introduction.tex"; snt::api::generate_dip_report( env, snt::dip::report::ReportFormat::Tex, "report.tex", options); TeX output needs no external program. ``introduction_file`` is an optional trusted LaTeX fragment for TeX and PDF only, without a document preamble. It appears after the contents page; ``\subsection`` headings in the fragment become contents links. Other text supplied by the environment and cover options is escaped for LaTeX. PDF output uses the same TeX document and invokes a local TeX compiler twice to resolve contents links and page numbers: .. code-block:: cpp options.title = "Mock Heat Flow Study"; options.author = "Example Research Team"; options.date = "2026-09-28"; options.version = "1.0 demo"; options.tex_compiler = "pdflatex"; snt::api::generate_dip_report( env, snt::dip::report::ReportFormat::Pdf, "report.pdf", options); ``tex_compiler`` defaults to ``pdflatex``. Choose another compatible local compiler, such as ``lualatex`` for Unicode text, when needed. An unavailable or failing compiler raises an error; the generator does not install one. Other formats use Brief++ renderers directly and need no external program: .. code-block:: cpp options.introduction_file.clear(); snt::api::generate_dip_report( env, snt::dip::report::ReportFormat::Html, "report.html", options); snt::api::generate_dip_report( env, snt::dip::report::ReportFormat::Markdown, "report.md", options); The other format values are ``Rst``, ``Typst``, ``Text``, and ``Json``. Markdown uses Brief++'s MyST-style directives for tables. JSON is the ``briefpp/1`` document tree, not DIP's static parameter export JSON. An introduction file is rejected for these formats because it contains raw LaTeX. Report options and content -------------------------- ``ReportOptions`` defaults to the title ``DIP parameter report``, an unspecified author, the local generation date, and the SNT build version. Set the date and version explicitly when a reproducible cover matters. ``input_label`` identifies the environment on the cover. Set ``source_root`` to a project directory to show source paths relative to it when possible. The report contains effective values, types, array shapes and units, descriptions, parameter paths, schema information, source provenance, custom units, registered function names, and available publication references. The Parameter guide lists every effective value and links to its full reference entry in HTML and PDF. Each entry retains its value, type, units, description, schema provenance, declaration, modifications, and override history. When present, an Applied overrides index lists the effective value and source of each explicit override so changes can be reviewed before reading individual entries. The Schemas section lists the parameters each schema supplied, while individual entries distinguish a schema applied along a path from one that supplied the value node. Parameter entries show declared ``!options`` and ``!condition`` rules, plus tags, when present. These rules remain visible without a recorded dependency graph. Author guidance such as rationale, recommended range, scientific and performance impact, dependencies, conflicts, and deprecation is shown in a separate advisory block. A recommended range or ``?requires`` entry describes intent; it does not add a runtime validation rule. If the environment has a recorded dependency graph, parameter entries also show their evaluated expression, direct reads, branch selection, and readers where available. These are evaluation facts: a read does not always mean that input was necessary for the final result. Source qualifiers on imported reads remain visible. Pass ``true`` to ``parse()`` to record this information; ordinary parsing keeps graph recording disabled. Reports from DIPH5 use a saved graph if present. Without one, the guide says that calculation relationships are unavailable. Applied value modifications appear in order with their source locations. Override information appears only for overridden parameters. Evaluated tables have a summary of their row count and ordered column names, types, and units; their column values remain in the Parameters section. Entries are sorted by path or name. The PDF has a cover, linked contents page, and matching shaded headings for parameters, tables, schemas, sources, and custom units. Human-readable reports show a 16-character prefix of each source content hash for readability. The JSON report, environment, and DIPH5 snapshot retain full digests. Parameter paths retain their group names; there is no separate hierarchy section. Built-in PUQ unit catalogues and executable function bodies are not included. The generator also accepts a loaded DIPH5 environment: .. code-block:: cpp #include #include snt::dip::Environment env; env.load("run.diph5"); snt::dip::report::generate( env, snt::dip::report::ReportFormat::Tex, "loaded-report.tex"); This report contains only values and provenance retained in the snapshot. It cannot reconstruct unsaved source text, executable function bodies, reusable schema definitions, or empty containers without value descendants. See the :doc:`DIP report declarations <../../api/cpp/dip/report>` for the full options and the :ref:`API wrapper declaration `. The :ref:`CreateReport example ` includes a generated PDF. For other interfaces, see the :doc:`CLI <../../integrations/cli>`, :doc:`Python <../../integrations/python>`, :doc:`C <../../integrations/c>`, and :doc:`REST <../../integrations/rest>` guides.