Report generation
=================

The :doc:`report generation guide <../en/results/reports>` describes the
command-line workflow, supported history mappings, output package, profile
schema, and diagnostics. The API below is intended for applications that need
to select sections programmatically or add a report module.

Architecture
------------

Report generation has three layers:

* measurement classes acquire and evaluate technical data;
* report modules collect evaluated results into renderer-neutral mappings;
* writers turn those mappings into tables, HTML, figures, and PDF pages.

A report profile changes metadata and presentation only. It cannot select a
different technical result or alter pass/fail assessment. This boundary keeps
repeated report generation deterministic and preserves the pickle as the
measurement-history authority.

History report
--------------

.. autoclass:: mpylab.env.tem.history_report.ReportSelection
   :members:

.. autoclass:: mpylab.env.tem.history_report.ReportModule
   :members:

.. autofunction:: mpylab.env.tem.history_report.discover_report_sections

.. autofunction:: mpylab.env.tem.history_report.select_report_sections

.. autofunction:: mpylab.env.tem.history_report.write_history_report

.. autoclass:: mpylab.env.tem.history_report.HistoryReportError

Presentation profile
--------------------

.. autoclass:: mpylab.env.tem.report_profile.ReportProfile
   :members:

.. autofunction:: mpylab.env.tem.report_profile.load_report_profile

.. autofunction:: mpylab.env.tem.report_profile.resolve_report_profile

.. autofunction:: mpylab.env.tem.report_profile.report_metadata_rows

.. autofunction:: mpylab.env.tem.report_profile.write_report_metadata_table

.. autoclass:: mpylab.env.tem.report_profile.ReportProfileError

Traceability
------------

.. autofunction:: mpylab.env.tem.history_traceability.collect_history_traceability

.. autofunction:: mpylab.env.tem.history_traceability.write_traceability_table

.. autofunction:: mpylab.env.tem.history_traceability.traceability_pdf_figure

Custom module lifecycle
-----------------------

A custom module implements :class:`~mpylab.env.tem.history_report.ReportModule`.
Its ``collect`` method converts stored evaluation results into a
renderer-neutral mapping. ``write`` produces section HTML, tables, and figure
assets, while ``pdf_figures`` supplies figures for the combined PDF. Domain
evaluation must remain outside the report module so that generating a report
cannot change the technical measurement result.

The minimal integration pattern is:

.. code-block:: python

   from mpylab.env.tem.history_report import (
       DEFAULT_REPORT_MODULES,
       ReportSelection,
       write_history_report,
   )

   class MyReportModule:
       key = "my_result"
       title = "My evaluated result"

       def discover(self, tem):
           data = getattr(tem, "processedData_MyResult", {}) or {}
           return [
               ReportSelection(self.key, str(name), self.title)
               for name in sorted(data, key=str)
           ]

       def collect(self, tem, selection):
           return {
               "description": selection.dataset_key,
               "rows": tem.processedData_MyResult[selection.dataset_key],
           }

       def write(self, report, output_dir, formats):
           # Write section tables, HTML, and requested image assets here.
           return {"output_dir": output_dir}

       def pdf_figures(self, report):
           return ()

       def summary(self, report):
           return {"result_count": len(report["rows"])}

   modules = (*DEFAULT_REPORT_MODULES, MyReportModule())
   result = write_history_report(
       tem,
       output_dir="report",
       formats=("html", "pdf", "svg"),
       modules=modules,
   )

``discover`` must return stable :class:`ReportSelection` identifiers.
``collect`` should be independently testable without Matplotlib or file I/O.
``write`` owns only its section directory, and ``pdf_figures`` transfers
figure ownership to the history writer, which closes figures after use.
External modules are passed explicitly through ``modules``; the standard CLI
does not import arbitrary report plugins.