User Guide

Preface

This user guide targets end-users.

If you’re about to create templates for end users, please refer to our Template Designer Guide.

End-users usually will:

• Generate Pharaoh projects based on the templates the template designers provided

• Update project settings

• Manage project components (update, add, remove)

• Modify/add asset scripts

• Overwrite certain pre-defined blocks inside provided templates

Important

The following guide only shows the API provided by Pharaoh. Keep in mind that the template designers of your project might provide an additional or different API to create Pharaoh projects.

Project Generation

The first thing to do is generating a Pharaoh project.

Note

This step may be skipped if you already created a project and manage it via GIT for example.

API

Create a Python script with following example content to create a new Pharaoh project:

from pharaoh.api import PharaohProject

# Create a project with a default template optimized for HTML output inside current working directory
proj = PharaohProject(".")

# For overwriting an existing project
proj = PharaohProject(project_root="path-to-existing-project", overwrite=True)

# Passing a custom template to extend the default project template "pharaoh.default_project"
proj = PharaohProject(
    ".",
    templates=("pharaoh.default_project", r"C:\...\my-extension-template"),
    template_context=dict(some_variable_in_extension_template="abc")
)

# Passing a custom settings YAML file
proj = PharaohProject(".", custom_settings=r"C:\...\my_custom_settings.yaml")

CLI

In a terminal with activated virtual environment that has pharaoh installed, type following commands:

# Create a project with a default template optimized for HTML output inside current working directory
pharaoh new

# For overwriting an existing project
pharaoh -p "path/to/existing/project" new --force

# Passing a custom template to extend the default project template "pharaoh.default_project"
pharaoh new -t pharaoh.default_project -t "C:\...\my-extension-template"
    -c "{'some_variable_in_extension_template': 'abc'}"

# Passing a custom settings YAML file
pharaoh -p . new --settings "C:\...\my_custom_settings.yaml"

Update Settings

See also

Settings Reference

Single settings may be updated during project generation (API & CLI) or afterwards (API or manually).

During Generation

API

This is done via the settings API function put_setting(key: str, value: Any) or via environment variables. Refer to the Custom Settings section for examples.

CLI

Besides passing an entire settings YAML file to the project generation, settings can be set using environment variables during project generation. Those will be automatically persisted in the settings file.

# CMD syntax:
set PHARAOH.LOGGING.LEVEL=INFO
set PHARAOH.FOO=bar
set PHARAOH.bla="{'blubb': 123}"

# PowerShell syntax:
Set-Variable -Name PHARAOH.LOGGING.LEVEL -Value INFO
Set-Variable -Name PHARAOH.FOO -Value bar
Set-Variable -Name PHARAOH.bla -Value "{'blubb': 123}"

# Bash syntax:
env "PHARAOH.LOGGING.LEVEL=INFO" bash
env "PHARAOH.FOO=bar" bash
env "PHARAOH.bla={'blubb': 123}" bash

pharaoh new

After Generation

API

This is done via the settings API function put_setting(key: str, value: Any) or via environment variables. Refer to the Custom Settings section for examples.

from pharaoh.api import PharaohProject

proj = PharaohProject(project_root="some-path")
proj.put_setting("report.title", "My own title")
proj.put_setting("toolkits.bokeh.export_png", dict(width=720, height=480))

CLI

Updating settings via CLI may be done via the env command:

cd "path/to/project"
pharaoh env report.title "My own title"

# or
pharaoh -p "path/to/project" env toolkits.bokeh.export_png "{'width':720, 'height':480}"

Manually

Just open the file pharaoh.yaml in your project root and modify its content according to YAML Coding Guidelines and the OmegaConf library specification.

Manage Components

The main content of a Pharaoh report is determined by components.

See also

What’s a Component? in the Components Reference

Components may be added or updated using following API/CLI:

API

This is done via the component API functions for managing components documented here.

Please refer to the component API functions for managing components here. Relevant sections are:

• Adding Components

• Updating Components

• Removing Components

CLI

Please refer to the CLI reference here. Relevant commands are:

• Add

• Update-resource

• Add-template

• Remove

Here some examples:

pharaoh add -n dummy1 -t pharaoh_testing.simple -c "{'test_name':'dummy'}"
pharaoh add -n dummy1 -t pharaoh_testing.simple -r "FileResource(alias='foo', pattern='.*')"

pharaoh update-resource -n dummy1 -a foo -r "FileResource(alias='baz', pattern='.*')"

pharaoh add-template -n dummy1 -t pharaoh_testing.simple -c "{'test_name':'dummy'}"

pharaoh remove -f dummy.*

Manage Asset Scripts

Once components are added, users may add or modify existing asset scripts.

See also

What’s an Asset? in the Assets Reference and Example Asset Scripts.

Modify Templates

If assets scripts are added or modified the templates might need to be updated to include potentially modified or added assets.

See also

Pharaoh Directive on how to include generated assets into your templates and the Build-time Templating section.