Logical architecture

Behavioral architecture model

When Sphinx is run, this extension performs the steps listed below.

  1. Initialization
    • Sphinx calls setup(), which registers the extension’s directives, roles, event handlers, etc.
  2. Parsing source files
    • When Sphinx encounters a traceables directive or role while parsing input, it calls the associated class.
    • The directive or role class processes its input and creates one or more nodes which are then inserted into the resulting doctree; these will be processed later after all source files have been parsed.
    • A directive that defines a new traceable item adds that item to the traceables cache that this extension maintains, so that later processing logic knows about all traceable items.
  3. Processing doctrees
    • During initialization, this extension registered a handler for the event-doctree-resolved event; that handler is called after all source files have been parsed into doctrees.
    • The event handler calls the ProcessorManager to process the given doctree; it in turn calls classes derived from ProcessorBase to perform the various traceables functionalities.
  4. Maintaining state information
    • During initialization, this extension registered a handler for the event-env-purge-doc event; that handler is called to clean up any state this extension may keep related to a given source file.
    • The event handler calls the TraceablesStorage to remove all information stored in its cache related to the given source file.

During parsing of source files

This extension adds the following directives and roles which are used by Sphinx during parsing of source.

Traceable directive

When Sphinx encounters a traceable directive during parsing, a TraceableDirective is called to process the directive. It creates a target node, so that the traceable can be referenced from elsewhere in the documentation, and a presentation node, to show the traceable’s definition at the directive’s location in the documentation.

The attributes defined in the traceable directive may contain references to other traceables which cannot be resolved until the entire doctree has been resolved. The attributes are therefore stored in a traceable_attribute_list node for later processing.

Traceable role

When Sphinx encounters a traceable role during parsing, a traceable_xref cross reference node is created. Later on that note will be replaced by an appropriate final node.

After doctree has been resolved

This extension registers the process_traceables_in_doctree() to be called when the doctree-resolved event fires. That callback function invokes the TraceablesProcessor to process the main business logic of this extension.

The TraceablesProcessor performs the following activities:

  1. Collect all traceables defined throughout the documentation
  2. Analyze relationships between traceables; this is done with help from the RelationshipManager class
  3. Process traceable_attribute_list nodes; these are part of traceable directives
  4. Resolve traceable_xref cross reference nodes; these are created by traceable roles, amongst other possible sources

Purging of old state

This extension registers the purge_traceables() to be called when the env-purge-doc event fires. That callback function removes the relevant data from the TraceablesStorage.