Use Cases

ID	Title	Status	Refinement	Realization	Elaboration
usc_demo_00001	Resolve Standard Sphinx References in SVG	open	usc_demo_00002	ftr_demo_00002	req_demo_00001
usc_demo_00002	Resolve Sphinx-Needs References in SVG	open		ftr_demo_00003	req_demo_00003
usc_demo_00003	Configure Verbose Output	open		ftr_demo_00004	req_demo_00010

Use Case: Resolve Standard Sphinx References in SVG usc_demo_00001

status: open refines: usc_demo_00002 realizes: ftr_demo_00002 is elaborated by: req_demo_00001

Main Flow: The user builds Sphinx documentation that includes SVG diagrams. The extension iterates through SVG files in the output directory. For each SVG, the extension parses its content to find xlink:href attributes. If an xlink:href attribute contains a standard Sphinx reference pattern (e.g., :ref:`my-target), the extension attempts to resolve it. The resolved URI (e.g., /path/to/my-target.html) replaces the reference pattern in the xlink:href attribute. The modified SVG file is saved, making the link clickable in the generated HTML. Preconditions: Sphinx documentation build is initiated. SVG diagrams are present in the build output’s image directory. Sphinx cross-references used in SVGs are valid and resolvable within the Sphinx project. Postconditions: SVG diagrams have clickable links where Sphinx references were present. The Sphinx build completes successfully. Use Case Diagram:

Use Case: Resolve Sphinx-Needs References in SVG usc_demo_00002

status: open refined by: usc_demo_00001 validated by: tsc_demo_00003 realizes: ftr_demo_00003 is elaborated by: req_demo_00003

Main Flow: The user builds Sphinx documentation with Sphinx-Needs and SVG diagrams. The needs_build_json configuration is enabled in conf.py. The extension loads the needs.json file generated by Sphinx-Needs. For each SVG, the extension parses its content to find xlink:href attributes. If an xlink:href attribute contains a Sphinx-Needs reference pattern (e.g., :need:`MY_NEED_ID), the extension attempts to resolve it using the loaded needs.json data. The resolved URI (e.g., ../needs_doc.html#MY_NEED_ID) replaces the reference pattern. The modified SVG file is saved, making the link clickable in the generated HTML. Alternative Flows: No `needs.json` found: The extension proceeds without resolving Sphinx-Needs references, logging a message if needs_build_json is enabled. Preconditions: Sphinx documentation build is initiated. SVG diagrams are present in the build output’s image directory. Sphinx-Needs extension is active and needs_build_json is set to True. A needs.json file is generated and accessible. Postconditions: SVG diagrams have clickable links to Sphinx-Needs where references were present. The Sphinx build completes successfully. Use Case Diagram:

Use Case: Configure Verbose Output usc_demo_00003

status: open realizes: ftr_demo_00004 is elaborated by: req_demo_00010

Main Flow: The user sets sphinx_diagram_connect_verbose = True in their conf.py. During the Sphinx build, for every successfully resolved xlink:href in an SVG, the extension logs an informative message indicating the original and resolved URI. Preconditions: The sphinx_diagram_connect extension is enabled in conf.py. Postconditions: Detailed logging messages about reference resolution are displayed during the build. Use Case Diagram: