Specifications

Specifications#

ID

Title

Status

Refinement

Satisfy

spc_demo_00001

SVG Reference Resolution Mechanism

open

spc_demo_00002; spc_demo_00003

req_demo_00001

spc_demo_00002

Standard Sphinx Reference Resolution

open

req_demo_00002

spc_demo_00003

Sphinx-Needs Reference Resolution

open

req_demo_00003

spc_demo_00004

Error Handling for Unresolved References

open

req_demo_00004

spc_demo_00005

Verbose Logging Configuration

open

req_demo_00010

@startuml ' Nodes definition node "<size:12>Specification</size>\n**SVG Reference**\n**Resolution**\n**Mechanism**\n<size:10>spc_demo_00001</size>" as spc_demo_00001 [[../traceability/specifications.html#spc_demo_00001]] #FFFF99 node "<size:12>Specification</size>\n**Standard Sphinx**\n**Reference**\n**Resolution**\n<size:10>spc_demo_00002</size>" as spc_demo_00002 [[../traceability/specifications.html#spc_demo_00002]] #FFFF99 node "<size:12>Specification</size>\n**Sphinx-Needs**\n**Reference**\n**Resolution**\n<size:10>spc_demo_00003</size>" as spc_demo_00003 [[../traceability/specifications.html#spc_demo_00003]] #FFFF99 node "<size:12>Specification</size>\n**Error Handling**\n**for Unresolved**\n**References**\n<size:10>spc_demo_00004</size>" as spc_demo_00004 [[../traceability/specifications.html#spc_demo_00004]] #FFFF99 node "<size:12>Specification</size>\n**Verbose Logging**\n**Configuration**\n<size:10>spc_demo_00005</size>" as spc_demo_00005 [[../traceability/specifications.html#spc_demo_00005]] #FFFF99 ' Connection definition spc_demo_00001 --> spc_demo_00002 spc_demo_00001 --> spc_demo_00003 @enduml

Specification: SVG Reference Resolution Mechanism spc_demo_00001
status: open
refines: spc_demo_00002, spc_demo_00003
satisfies: req_demo_00001

The DiagramConnect class shall implement a method, resolve_references, which is triggered upon the build-finished Sphinx event. This method shall iterate through all .svg files located in the app.builder.outdir and app.builder.imagedir. It shall identify and modify xlink:href attributes that contain Sphinx cross-reference patterns (e.g., :ref:`target, :doc:`target) or Sphinx-Needs reference patterns (e.g., :need:`target). The modification involves replacing these patterns with their resolved URIs.

Component Diagram: Extension Architecture
Specification: Standard Sphinx Reference Resolution spc_demo_00002
status: open
refined by: spc_demo_00001
satisfies: req_demo_00002
verified by spec: tsc_demo_00001

The _resolve_ref internal method shall utilize app.env.domains[‘std’].resolve_xref to convert Sphinx reference targets (e.g., my-section, my-document) into their corresponding relative or absolute URIs. This process must handle sphinx.errors.NoUri by returning None if a reference cannot be resolved by Sphinx’s standard mechanisms.
Specification: Sphinx-Needs Reference Resolution spc_demo_00003
status: open
refined by: spc_demo_00001
satisfies: req_demo_00003

If app.config.needs_build_json is set to True, the resolve_references method shall load needs.json using sphinx_needs.needsfile.NeedsList. For xlink:href attributes matching a Sphinx-Needs reference pattern (e.g., :need:`ID), the system shall look up the ‘docname’ associated with the ‘ID’ in the loaded needs.json data. The xlink:href shall then be updated to ../<docname>.html#<ID>.
Specification: Error Handling for Unresolved References spc_demo_00004
status: open
satisfies: req_demo_00004

The resolve_references method shall log a warning message using sphinx.util.logging.getLogger(__name__).warning when a Sphinx or Sphinx-Needs reference pattern found in an xlink:href attribute cannot be successfully resolved. The warning message shall include the unresolved reference and the filename where it occurred. The warning type shall be “sphinx-diagram-connect-missing-reference”.
Specification: Verbose Logging Configuration spc_demo_00005
status: open
satisfies: req_demo_00010

The extension shall expose a configuration option, sphinx_diagram_connect_verbose (defaulting to False), which, when set to True, shall enable additional logger.info messages during the resolve_references process, specifically detailing the transformation of original href values to their resolved URIs.