API Reference

This section documents the internal API of sphinx-needs-tree-map for developers who want to extend or integrate with the extension.

Extension Setup

sphinx-needs-tree-map: StrictDoc-style tree map visualizations for sphinx-needs.

This extension provides the needtreemap directive to create interactive Plotly.js treemap visualizations of sphinx-needs documentation.

sphinx_needs_tree_map.setup(app)

Set up the sphinx-needs-tree-map extension.

Parameters:

app (Sphinx) – The Sphinx application instance.

Return type:

dict[str, Any]

Returns:

Extension metadata dictionary.

Directives

NeedTreeMap directive implementation.

class sphinx_needs_tree_map.directives.needtreemap.NeedTreeMapNode

Bases: General, Element

Custom docutils node for needtreemap directive.

This node stores the directive options and is processed later in the doctree-resolved event when all needs data is available.

class sphinx_needs_tree_map.directives.needtreemap.NeedTreeMapDirective

Bases: SphinxDirective

Directive to create an interactive treemap visualization of needs.

Usage:

.. needtreemap::
   :filter: type == 'req' or type == 'spec'
   :root: document
   :depth: 3
   :size_by: count
   :color_by: type
   :show_values:
   :interactive:
   :height: 600px
   :width: 100%

has_content: ClassVar[bool] = False

May the directive have content?

required_arguments: ClassVar[int] = 0

Number of required directive arguments.

optional_arguments: ClassVar[int] = 0

Number of optional arguments after the required arguments.

final_argument_whitespace: ClassVar[bool] = True

May the final argument contain whitespace?

option_spec: ClassVar[dict[str, Any]] = {'color_by': <function unchanged>, 'depth': <function positive_int>, 'filter': <function unchanged>, 'height': <function unchanged>, 'hierarchy': <function unchanged>, 'interactive': <function flag>, 'root': <function unchanged>, 'show_values': <function flag>, 'size_by': <function unchanged>, 'status': <function unchanged>, 'tags': <function unchanged>, 'title': <function unchanged>, 'types': <function unchanged>, 'width': <function unchanged>}

Mapping of option names to validator functions.

run()

Execute the directive and return a placeholder node.

The actual treemap generation happens in the doctree-resolved event when all needs have been collected.

Return type:

list[Node]

Returns:

List containing a single NeedTreeMapNode.

sphinx_needs_tree_map.directives.needtreemap.process_needtreemap_nodes(app, doctree, _docname)

Process all NeedTreeMapNode instances in the doctree.

This event handler is called during the doctree-resolved phase, when all needs have been collected and are available for processing.

Parameters:

• app (Sphinx) – The Sphinx application instance.

• doctree (document) – The document tree being processed.

• _docname (str) – Name of the document being processed (unused).

Return type:

None

Utilities

Hierarchy Builder

Classes for building hierarchical tree structures from sphinx-needs data.

class sphinx_needs_tree_map.utils.hierarchy.TreeNode

Bases: object

A node in the treemap hierarchy tree.

id

Unique identifier for this node.

label

Display label for the node.

parent_id

ID of parent node (empty string for root).

value

Numeric value for sizing (e.g., count of needs).

node_type

Type of node (root, document, section, need).

need_type

For need nodes, the sphinx-needs type (req, spec, etc.).

status

For need nodes, the status value.

metadata

Additional metadata for the node.

children

List of child nodes.

id: str

label: str

parent_id: str = ''

value: int = 1

node_type: str = 'node'

need_type: str | None = None

status: str | None = None

metadata: dict[str, Any]

children: list[TreeNode]

add_child(child)

Add a child node and set its parent.

Return type:

None

iter_all()

Iterate over this node and all descendants.

Return type:

Iterator[TreeNode]

compute_values()

Recursively compute values from leaf nodes up.

For branch nodes, value = sum of children values. For leaf nodes, value remains as set.

Return type:

int

Returns:

The computed value for this node.

__init__(id, label, parent_id='', value=1, node_type='node', need_type=None, status=None, metadata=<factory>, children=<factory>)

class sphinx_needs_tree_map.utils.hierarchy.HierarchyBuilder

Bases: object

Builds a tree hierarchy from sphinx-needs data.

Supports multiple hierarchy strategies: - document: Group by document name, then sections - links: Build tree from parent-child link relationships - type: Group by need type, then by status

Parameters:

• needs (dict[str, Any] | Any) – The filtered needs to build hierarchy from.

• hierarchy_mode (str) – The hierarchy strategy to use.

• root (str) – Root node identifier (document | section | need_id).

• max_depth (int) – Maximum hierarchy depth.

• size_by (str) – How to calculate node sizes.

__init__(needs, hierarchy_mode='document', root='document', max_depth=3, size_by='count')

build()

Build the hierarchy tree.

Return type:

TreeNode

Returns:

Root TreeNode of the hierarchy.

Filters

Filter utilities for sphinx-needs data.

sphinx_needs_tree_map.utils.filters.filter_needs(needs, _app, filter_string=None, types=None, status=None, tags=None)

Filter needs based on various criteria.

Parameters:

• needs (dict[str, Any] | Any) – All needs (dict or NeedsView).

• _app (Sphinx) – Sphinx application instance (unused, kept for API compatibility).

• filter_string (str | None) – sphinx-needs filter expression.

• types (list[str] | None) – List of need types to include.

• status (list[str] | None) – List of statuses to include.

• tags (list[str] | None) – List of tags to include (any match).

Return type:

dict[str, Any]

Returns:

Filtered needs as a dictionary.

Plotly Renderer

Plotly.js treemap rendering utilities.

class sphinx_needs_tree_map.utils.plotly_renderer.PlotlyTreemapRenderer

Bases: object

Renders a TreeNode hierarchy as a Plotly.js treemap.

Generates HTML/JavaScript code that creates an interactive treemap visualization using Plotly.js.

Parameters:

• tree (TreeNode) – Root TreeNode of the hierarchy to render.

• treemap_id (str) – Unique HTML ID for this treemap instance.

• color_by (str) – How to determine node colors (type | status).

• color_map (dict[str, str] | None) – Dictionary mapping values to colors.

• show_values (bool) – Whether to show values in labels.

• interactive (bool) – Whether to enable interactive features.

• height (str) – CSS height value (e.g., ‘600px’).

• width (str) – CSS width value (e.g., ‘100%’).

• title (str) – Optional title for the treemap.

• plotly_cdn (str) – CDN URL for Plotly.js.

__init__(tree, treemap_id, color_by='type', color_map=None, show_values=True, interactive=True, height='600px', width='100%', title='', plotly_cdn='https://cdn.plot.ly/plotly-2.35.2.min.js')

render()

Render the treemap to HTML.

Return type:

str

Returns:

HTML string containing the treemap visualization.