Building

Configuration

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

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.
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, suffix: str | None = None, compression: bool = True) → Path[source]

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.
suffix – Suffix to append to the stem of the archive’s filename.
compression – True by default, if set to False, will create an uncompressed folder instead of a zip file.

Returns:

The path to the archive

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