Sphinx extension for Pipeline Manager

Pipeline Manager provides Sphinx extension that allows drawing graphs inside documentation.

To use it, first include pipeline_manager in your installed packages, with following extra dependencies:

  • docs - optional, brings Sphinx and basic dependencies (can be skipped if Sphinx is in requirements)

  • to-image - optional, allows converting Pipeline Manager graphs to images automatically for documentation types other than HTML (e.g. PDF)

Secondly, add pipeline_manager.sphinxext to extensions in Sphinx’s conf.py file:

extensions = [
    ...,
    "pipeline_manager.sphinxext.draw_graph"
]

After these steps you should be able to define Pipeline Manager graph like so:

```{pipeline_manager}
:spec: ../examples/sample-specification.json
:graph: ../examples/sample-dataflow.json
```

When building the docs, a static single-html pipeline-manager.html is created in the static directory of the docs. Any specification or dataflow referenced by the extension will be copied to downloads subdirectory and automatically linked in the final docs. If the docs are not built in html, images will be included in the documentation.

Directive parameters

The pipeline_manager directive allows for following parameters:

  • spec - required, points to specification that should be used for the graph.

  • graph - optional, points to dataflow that should be used for the graph.

  • preview - optional, if set, the graph is displayed in preview mode (read only, no HUD).

  • height - optional, specifies height of the graph in chosen units, px/%/em etc. Unit has to be specified. If height was not set, aspect ratio of 3/2 will be assumed.

  • alt - optional, changes alternative text of the graph.

So for example this is a valid directive usage:

```{pipeline_manager}
:spec: ../examples/specification.json
:height: 500px
:alt: This is an example of using pipeline manager in documentation
:preview:
```

draw_graph extension documentation

KPMNode

class pipeline_manager.sphinxext.draw_graph.KPMNode(*, depth: int, preview: bool | None = None, spec: str | None = None, graph: str | None = None, height: str | None = None, alt: str | None = None)

Docutils node introducing Pipeline Manager graph to docs.

static visit_html(trans: HTML5Translator, node: KPMNode)

Node renderer method for HTML target.

KPMDirective

class pipeline_manager.sphinxext.draw_graph.KPMDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Sphinx directive for pipeline_manager.

option_spec : dict[str, type] = {'alt': <function unchanged>, 'graph': <function path>, 'height': <function unchanged>, 'preview': <function flag>, 'spec': <function path>}

Mapping of option names to validator functions.

run() → list[Node]

Creates nodes for the directive.

pipeline_manager.sphinxext.draw_graph.build_pipeline_manager(app)

Builds Pipeline Manager frontend on builder’s initialization.

Last update: 2026-07-01