Building

Configuration

Following steps have to be done for configuring a Sphinx build:

1. Choose a Sphinx build target via the report.target setting. Currently supported are:

   • html and all other Sphinx default builders like latex.

   • confluence, singleconfluence.

   Note

   For other builders than html and *confluence, you might need to install additional dependencies.

2. Configure the selected builder

   • Via settings sections like report.html and report.confluence

   • Via the Sphinx configuration report_project/conf.py.

     This file loads a default Sphinx configuration variables (also partially from settings) and assigns them to the local namespace.

     To modify just overwrite or alter them:

     # The list "html_css_files" is already defined from the default config,
     # but this is not the case for all variables.
     # To be sure inspect the local namespace via the debugger or print it
     # like this ``print(", ".join(locals().keys()))``
     html_css_files.append("css/mystyle.css")
     

   Note

   The HTML builder already contains a reasonable default config, so no change needed in most cases.

Build API

A Pharaoh report may be built using the method PharaohProject.build_report().

Important

If your templates are accessing assets, make sure you call PharaohProject.generate_assets() every time your asset scripts or resources changed.

You can call the API within a Python script, as for example in the included report-project/debug.py script.

from pharaoh.api import PharaohProject

if __name__ == "__main__":  # This guard is needed because Pharaoh is using multiprocessing
    proj = PharaohProject(project_root="..")
    proj.generate_assets()
    proj.build_report()

Or you just double-click the CLI scripts report-project/pharaoh-generate-assets.cmd and report-project/pharaoh-build.cmd.

Or with the Pharaoh venv activated, inside the project directory use the CLI directly: pharaoh build

Log output should be displayed in the console, but are also written to log.txt and log_warnings.txt (only warnings or errors).

Archiving

After building a report, it may be archived using PharaohProject.archive_report().

PharaohProject.archive_report(dest: str | Path | None = None) → Path

Create an archive from the build folder.

Parameters:

dest – A destination path to create the archive. Relative paths are relative to the project root. If omitted, the filename will be taken from the report.archive_name setting.

Returns:

The path to the archive

Alternatively just double-click the CLI script report-project/pharaoh-archive.cmd.