sphinx_diagram_connect package

sphinx_diagram_connect package#

A Sphinx extension for connecting references within SVG diagrams.

This extension processes SVG files generated as part of a Sphinx build, identifying Sphinx cross-references (e.g., :ref:, :doc:) and Sphinx-Needs references (:need:), and replaces them with the actual resolved URLs in the SVG’s xlink:href attributes. This allows interactive, clickable diagrams within your Sphinx documentation.

The extension integrates into the Sphinx build process and modifies SVG outputs to ensure links remain functional in the final HTML documentation.

class sphinx_diagram_connect.DiagramConnect(app)#

Bases: object

A class to handle the resolution of Sphinx references within SVG files generated by Sphinx, particularly for connecting diagrams to other documentation elements like reST references or sphinx-needs.

resolve_references(app_from_event, exception)#

Resolves Sphinx references embedded within SVG files generated by Sphinx.

This method iterates through all SVG files in the Sphinx build output’s image directory. It looks for specific patterns (e.g., :ref:`target` or :doc:`target`) in href attributes within the SVG XML. If a pattern is found, it attempts to resolve the reference to an actual URI using _resolve_ref or by looking up sphinx-needs data. The SVG file is then updated with the resolved URIs.

This is the main method connected to Sphinx’s ‘build-finished’ event.

Parameters:

  • app_from_event (sphinx.application.Sphinx) – The Sphinx application object passed by the event.

  • exception (Exception or None) – The exception object if an error occurred during the build, otherwise None.

sphinx_diagram_connect.setup(app)#

Sets up the Sphinx extension.

This function instantiates the DiagramConnect class and registers its resolve_references method to be called after the Sphinx build is finished. It also adds a configuration value ‘sphinx_diagram_connect_verbose’ which can be set in conf.py to enable verbose logging.

Parameters:

app (sphinx.application.Sphinx) – The Sphinx application object.

Returns:

A dictionary containing Sphinx extension metadata.

Return type:

dict

Contents