Vertex Table

a vertex table is a directive used to generate a summary of vertices in the vertex graph.

for example, this:

.. vertex-table::

would produce the following table of vertices contained in this document (see the example Example Project):

uid	tags	parents	children
MRD-001			USR-001
MRD-002
SYS-001		USR-001
SYS-002		USR-001
SYS-003		USR-001
SYS-004
USR-001	P1, functional	MRD-001	SYS-003, SYS-002, SYS-001
node-001	P1		node-002
node-002	P2, ux	node-001

Queries

Sphinx-Graph supports using ‘queries’ to sort and filter the vertices displayed in a vertex table.

A query is a Python function with the signature:

Callable[[sphinx_graph.vertex.State], Iterable[str]]

sphinx_graph.vertex.State provides access to all vertices and the graph of relationships between them. The return value is the list of vertex UIDs to display, in order.

Queries may also accept additional keyword arguments (with or without defaults), which are passed in from the directive body using TOML syntax.

Writing a query

Define the query function in a separate module (not directly in conf.py), then register it under a name in conf.py:

# my_queries.py

from collections.abc import Iterable
from sphinx_graph.vertex import State

def by_tag(state: State, *, tag: str) -> Iterable[str]:
    """Return all vertices that have a given tag."""
    return (
        uid for uid, info in state.vertices.items()
        if tag in info.tags
    )

# conf.py

from sphinx_graph import Config
from my_queries import by_tag

graph_config = Config(
    queries={"by_tag": by_tag},
)

Then reference the query by name in a vertex-table directive:

.. vertex-table::
    :query: by_tag

    tag = "my-tag"

Keyword arguments are parsed from the directive body as TOML.