Reporting#

The reporting modules read model parameter values and descriptions from the model repository and write to a report.

docs_pages#

Assemble a multi-version documentation site from released documentation builds.

A version switcher file (as used by the pydata-sphinx-theme) lists the released versions to be published. Each version is downloaded as a tarball of its built HTML site and extracted to <output_path>/<version>/. The newest version is additionally copied to the site root. Identical files are replaced by relative symlinks to one copy, so that unchanged pages of different versions are stored only once.

reporting.docs_pages.assemble_pages(switcher_file, output_path, package_url, size_budget_mb, token=None)[source]#

Assemble the multi-version documentation site.

Parameters:

switcher_filePath or str: Version switcher JSON file listing the versions to publish.
output_pathPath or str: Site directory (must be empty or not exist).
package_urlstr: URL template of the documentation tarballs with a {version} placeholder.
size_budget_mbfloat: Maximum deployed size in MB.
tokenstr, optional: GitLab CI job token for downloading the tarballs.

reporting.docs_pages.check_size(output_path, versions, size_budget_mb)[source]#

Log the deployed size per version and check it against a size budget.

Raises:

RuntimeError: If the deployed size exceeds the size budget.

reporting.docs_pages.copy_version_to_root(output_path, version)[source]#: Copy a version to the site root (served as latest version).

reporting.docs_pages.deduplicate(output_path)[source]#

Replace identical files by relative symlinks to one canonical copy.

Files at the site root are preferred as canonical copies, as the root is always deployed while individual versions may be removed.

Parameters:

output_pathPath: Site directory.

reporting.docs_pages.deployed_size(path)[source]#: Return the size in bytes of a directory; symlinks count with the length of their target.

reporting.docs_pages.download_version(version, package_url, output_path, token=None)[source]#

Download and extract the documentation tarball of a released version.

Parameters:

versionstr: Release version (vX.Y.Z).
package_urlstr: URL template of the documentation tarball with a {version} placeholder.
output_pathPath: Site directory; the version is extracted to output_path / version.
tokenstr, optional: GitLab CI job token sent as JOB-TOKEN header.

reporting.docs_pages.read_version_switcher(switcher_file)[source]#

Read and validate a version switcher file.

The ‘latest’ entry gives the site URL; each released version vX.Y.Z must be served at <site URL>vX.Y.Z/.

Parameters:

switcher_filePath or str: Version switcher JSON file.

Returns:

list of str: Listed release versions, newest first.

Raises:

ValueError: If the file content is not a valid version switcher.

reporting.docs_pages.remove_source_maps(output_path)[source]#: Remove JavaScript and CSS source maps, which are not needed for serving.

reporting.docs_pages.version_key(version)[source]#: Return a sort key for version strings of the form vX.Y.Z.

docs_toctree#

Generate Sphinx toctree index files for the generated simulation model reports.

reporting.docs_toctree.generate_toctree(docs_path)[source]#

Generate index.md files with toctrees for all directories of a documentation source tree.

Directories used for static content, images, data files, and build output are ignored.

Parameters:

docs_pathPath or str: Root directory of the Sphinx documentation source.

reporting.docs_toctree.toctree_entries(directory, subdirectories)[source]#: Return the sorted toctree entries of a directory (markdown files, images, subdirectories).

reporting.docs_toctree.write_index_file(directory, entries, is_site_root=False)[source]#

Write an index.md file with a toctree listing the given entries.

Parameters:

directoryPath: Directory of the index file.
entrieslist of str: Toctree entries (document names relative to the directory).
is_site_rootbool: Write the site title and introduction (site root index).

docs_read_parameters#

Class to read and manage relevant model parameters for a given telescope model.

class reporting.docs_read_parameters.ReadParameters(args, output_path, model_reader=None, context=None)[source]#

Read and manage model parameter data for report generation.

generate_model_parameter_reports_for_devices(array_elements)[source]#: Create model-parameter comparison reports for calibration devices.

get_all_parameter_descriptions(collection='telescopes')[source]#

Get descriptions for all model parameters.

Returns:

dict: Nested dictionaries with first key as the parameter name and the following dictionary as the value: - key: description, value: description of the parameter. - key: short_description, value: short description of the parameter. - key: inst_class, value: class, for eg. Structure, Camera, etc.

get_array_element_parameter_data(telescope_model, collection='telescopes')[source]#

Get model parameter data and descriptions for a given array element.

Parameters:

telescope_modelTelescopeModel: The telescope model instance.

Returns:

tuple: rows of [class, parameter, version, value, description, short description]: and the dict tables (parameter, value, unit).

get_calibration_data(all_parameter_data, array_element)[source]#: Get calibration data and descriptions for a given array element.

get_simulation_configuration_data()[source]#: Get data and descriptions for simulation configuration parameters.

is_markdown_link(value)[source]#

Return True if the string is a Markdown-style link: [text](target).

Parameters:

valuestr: The string to check.

Returns:

bool: True if the string is a Markdown link, False otherwise.

property model_version#: Model version.

produce_array_element_report()[source]#: Produce a markdown report of all model parameters per array element.

produce_calibration_reports()[source]#: Write calibration reports.

produce_model_parameter_reports(collection='telescopes')[source]#

Produce a markdown report of all model parameters for a given array element.

Outputs one markdown report per array element with one section per model parameter, comparing parameter values across model versions.

produce_observatory_report()[source]#: Produce a markdown report of all observatory parameters for a given site.

produce_simulation_configuration_report()[source]#: Write simulation configuration report.

docs_parameter_delta#

Delta reports: parameters changed between two model versions.

class reporting.docs_parameter_delta.ParameterDelta(parameter, base_param_version, new_param_version, base_value, new_value)[source]#

A changed parameter for delta report rendering.

base_param_version#: Alias for field number 1

base_value#: Alias for field number 3

new_param_version#: Alias for field number 2

new_value#: Alias for field number 4

parameter#: Alias for field number 0

class reporting.docs_parameter_delta.ParameterDeltaMixin[source]#: Delta-report methods of ReadParameters (relies on its attributes and helpers).

docs_parameter_plots#

Plot and file-reference helpers of the parameter reports (mixed into ReadParameters).

class reporting.docs_parameter_plots.ParameterPlotMixin[source]#: Plot and file-reference methods of ReadParameters (relies on its attributes).

reporting.docs_parameter_plots.scope_kwargs(telescope=None, site=None)[source]#: Return the non-empty telescope and site keyword arguments.

reporting.docs_parameter_plots.version_key(version)[source]#: Sort key for dotted version strings.

docs_auto_report_generator#

Class to automate generation of all reports according to command line inputs.

class reporting.docs_auto_report_generator.ReportGenerator(args, output_path, model_reader=None, context=None)[source]#

Automate report generation.

auto_generate_array_element_reports()[source]#: Generate all reports based on which –all_* flag is passed.

auto_generate_calibration_reports()[source]#

Generate calibration reports for one or all model versions.

Mirrors the pattern used by other auto_generate_* methods: if –all_model_versions is set, produce reports for every model version in the model repository; otherwise produce reports only for the configured model_version.

auto_generate_observatory_reports()[source]#: Generate all observatory reports based on which –all_* flags are passed.

auto_generate_parameter_reports()[source]#: Generate parameter reports for all telescope-site combinations.

auto_generate_simulation_configuration_reports()[source]#

Generate simulation configuration reports for one or all model versions.

If –all_model_versions is set, produce reports for every model version in the model repository; otherwise produce reports only for the configured model_version.

property model_source#: Return the selected reader under the historical attribute name.

docs_production_summary#

Generate markdown summaries for production descriptions.

reporting.docs_production_summary.collect_production_descriptions(data_path=None, model_reader=None)[source]#

Collect production versions and descriptions from simulation-models info files.

Parameters:

data_pathstr or Path, optional: Path to the simulation-models repository root.
model_readerSimulationModelReader, optional: Reader for a filesystem or Git simulation-model source.

Returns:

list[tuple]: List with (model_version, description) pairs from the model source.

reporting.docs_production_summary.write_production_summary_markdown(data_path=None, output_file=None, model_reader=None)[source]#

Write a markdown table with production versions and short descriptions.

Parameters:

data_pathstr or Path, optional: Path to the simulation-models repository root.
output_filestr or Path, optional: Markdown file to write.
model_readerSimulationModelReader, optional: Reader for a filesystem or Git simulation-model source.

figure_cache#

Content-derived identities for figures shared by documentation pages.

reporting.figure_cache.figure_cache_key(renderer, renderer_modules, plot_config, rendered_data, context=None)[source]#: Return a SHA-256 key for identical plot inputs and rendering settings.

model_figures#

Generate figures attached to model reports.

reporting.model_figures.plot_camera_config(parameter_version, output_path, telescope, site, model_version, model_reader, context=None)[source]#: Plot the camera layout file using the selected model version.

reporting.model_figures.plot_mirror_config(parameter, parameter_version, input_file, output_path, telescope, site, model_version, context=None)[source]#: Plot the mirror configuration file using the selected model version.

reporting.model_figures.plot_nsb_altitude_correction(input_file, output_path, context=None)[source]#: Plot the spectral extinction grid used to correct the NSB by altitude.

reporting.model_figures.write_flasher_pulse_shape_plots(file, comparison_items, collection, model_reader, site, calibration_device, context=None)[source]#: Render Gauss-Exponential tables using the production pulse-table writer.

reporting.model_figures.write_telescope_structure_figure(file, telescope_model, logger, context=None)[source]#: Generate and link the nominal telescope structure for this model version.