Plugin Architecture

Pharaoh may be extended using pluggy. Just import the impl decorator from pharaoh.plugins.api and implement one of the specs documented below.

If you like to extend other parts of the library please open up a discussion on GitHub or raise a PR directly.

Here an example on how to extend the Sphinx configuration programmatically:

from pharaoh.plugins.api import impl

@impl
def pharaoh_configure_sphinx(project: PharaohProject, config: dict, confdir: Path):
    config["extensions"].append("sphinxcontrib.confluencebuilder")
    config["html_style"] = "sphinx_rtd_theme_overrides.css"

Hookspec Markers

pharaoh_add_cli_commands(cli: click.Group)[source]

This hook is called after all click CLI commands have been added to add you own CLI commands. Example:

from pharaoh.plugins.api import impl

@impl
def pharaoh_add_cli_commands(cli: click.Group):
    @cli.command()
    @click.pass_context
    def my_cli_command(ctx):
        project = ctx.obj["project"]
        project.do_something

pharaoh_asset_gen_prepare_resources(project: PharaohProject, resources: dict[str, Resource])[source]

This hook is called before asset generation for each component that is selected.

Example:

@impl
def pharaoh_asset_gen_prepare_resources(project: PharaohProject, resources: dict[str, Resource]):
    from .resources import RemoteResource

    # Transform resources
    for r in resources.values():
        if isinstance(r, RemoteResource):
            r.download(
                url=project.get_setting("cloud.url"),
                auth_credentials=project.get_setting("cloud.auth_credentials", to_container=True) or None,
            )

Parameters:

project – The Pharaoh project instance
resources – A mapping of all resources that are defined for the current component.

pharaoh_asset_gen_started(project: PharaohProject)[source]

This hook is called when the asset generation is executed.

Parameters:: project – The Pharaoh project instance

pharaoh_build_finished(project: PharaohProject, exc_info: tuple[type[BaseException], BaseException, TracebackType] | None)[source]

This hook is called after a Sphinx build ended with or without error.

Parameters:

project – The Pharaoh project instance
exc_info – An optional value that is returned by sys.exc_info() in case the build raised an Exception.

pharaoh_build_started(project: PharaohProject, builder: str)[source]

This hook is called before a Sphinx build is started.

Parameters:

project – The Pharaoh project instance
builder – The name of the configured builder

pharaoh_collect_default_settings() → Path | dict[source]

This hook is called when scaffolding a new Pharaoh project. It collects all default settings either as a path to a YAML file or a dictionary. The collected results are loaded into omegaconf.dictconfig.DictConfig instances and merged in the same order as they are collected (first discovered may get overwritten, last discovered always wins).

Example:

@impl
def pharaoh_collect_default_settings():
    return Path(__file__).with_name("my_own_setting.yaml")

Returns:: A path to a YAML file or a dictionary

pharaoh_collect_l1_templates() → list[L1Template][source]

Collects all first-level templates.

Example:

@impl
def pharaoh_collect_l1_templates():
    return [
        L1Template(
            name="myorg.default_project",
            path=Path(__file__).parent / "templates" / "level_1" / "default_project",
        ),
    ]

pharaoh_collect_l2_templates() → list[str | Path][source]: Collects paths to all second-level template directories.

pharaoh_collect_resource_types() → list[type[Resource]][source]

Allows registering custom resource types.

Example:

@impl
def pharaoh_collect_resource_types():
    from .resources import RemoteResource

    return [RemoteResource]

pharaoh_configure_sphinx(project: PharaohProject, config: dict[str, Any], confdir: Path)[source]

This hook is called at the end of pharaoh.project.PharaohProject.get_default_sphinx_configuration() when Sphinx is reading the conf.py file. It can update the default Sphinx configuration in-place.

Example:

@impl
def pharaoh_configure_sphinx(project: PharaohProject, config: dict, confdir: Path):
    config["extensions"].append("sphinxcontrib.confluencebuilder")
    config["html_style"] = "sphinx_rtd_theme_overrides.css"

Parameters:

project – The Pharaoh project instance
config – The default Sphinx config defined by Pharaoh.
confdir – The parent directory of conf.py

pharaoh_find_asset_render_template(template_name: str) → str | Path[source]

This hook is called when an asset template is looked up by name and can customize the search behavior. Per default the templates in package pharaoh.templating.second_level.sphinx_ext.asset_ext_templates are used.

This template is used to include an asset into a Sphinx document, e.g. the template for a picture asset may be called image.rst.jinja2 and would be using the image directive to embed it. If found, the path to the template is returned.