Logical architecture¶
Behavioral architecture model¶
When Sphinx is run, this extension performs the steps listed below.
- Initialization
- Sphinx calls
setup()
, which registers the extension’s directives, roles, event handlers, etc.
- Sphinx calls
- 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.
- 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 fromProcessorBase
to perform the various traceables functionalities.
- 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:
- Collect all traceables defined throughout the documentation
- Analyze relationships between traceables; this is done with help from the
RelationshipManager
class- Process
traceable_attribute_list
nodes; these are part of traceable directives- 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
.