The Vertex Node

The core feature of Sphinx-Graph is the vertex directive. The vertex directive is used to wrap an arbitrary document element and augment it with additional information. Each vertex directive forms a node in a graph of related nodes.

This is particularly useful for tracking relationships between requirements, specifications, or any other item used for plain-text requirements management.

.. vertex:: node-001
    :tags: P1

    A vertex node can contain arbitrary content.

    .. note::

        That includes nested restructuredtext directives.

.. vertex:: node-002
    :parents: node-001
    :tags: P2, ux

    Vertex nodes can have parent-child relationships to other nodes

this is rendered in place and augmented with additional information, like so:

_{node-001 | Children: node-002 | Tags: P1}

A vertex node can contain arbitrary content

Note

That includes nested restructuredtext directives.

_{node-002 | Parents: node-001 | Tags: P2, ux}

Vertex nodes can have parent-child relationships to other nodes

Fingerprints

Vertex nodes may optionally use ‘fingerprints’ to detect when a relationship between two nodes must be reviewed (this is known as a ‘suspect link’).

A ‘fingerprint’ is a simple hash of the parent node’s content. If the hash on the child node doesn’t match the content of the parent node, Sphinx-Graph will raise an error and inform the user of the new hash.

Updating the hash silences the error, and signifies that the relationship between the nodes has been reviewed and accepted.

The first time you add a fingerprint you can add an arbitrary value. At build time, the correct value will be calculated and reported as a build error.

.. vertex:: node-003

    A user story

.. vertex:: node-004
    :parents: node-003:1234

    in this case '1234' is the (example) fingerprint of the relationship.
    if '1234' is the wrong hash (it is), then Sphinx-Graph will raise an error so that it can
    be updated to the correct value.

output:

WARNING: suspect link found. vertex node-004 is linked to vertex node-003 with a fingerprint of ‘1234’, but node-003’s fingerprint is ‘c6Rq’. node-004 should be reviewed, and the link fingerprint manually updated.

Configuration

For information on global configuration, see sphinx_graph.config.Config.

For information on vertex configuration, see sphinx_graph.vertex.config.Config.

There are three locations that a vertex node can be configured.

global configuration in conf.py
per-type configuration in confy.py
local configuration directly on the vertex directive

Global configuration is overwritten by per-type configuration, which is in turn overwritten by local configuration.

Global Vertex Configuration

conf.py

# ...

graph_config = Config(
    vertex_config=VertexConfig(
        require_fingerprints=True,
        regex=re.compile(r"^REQ-[0-9]{4}$")
    )
)

Per-Type Vertex Configuration

conf.py

# ...

graph_config = Config(
    types={
        "mrd": VertexConfig(layout="transparent", regex=re.compile(r"^MRD-[0-9]{3}$")),
        "usr": VertexConfig(regex=re.compile(r"^USR-[0-9]{3}$")),
        "sys": VertexConfig(regex=re.compile(r"^SYS-[0-9]{3}$")),
    },
)

your-docs.rst

.. vertex:: USR-001
    :type: usr

    the ID will be checked and the layout chosen according the 'type' of vertex which has been configured.

Local Vertex Configuration

.. vertex:: node-004
    :parents: node-003:1234
    :require_fingerprints:
    :layout: transparent

    (content)