Automatic referencing of Sphinx sections that use the `:need:` role

[knoepfel]

We are creating a Sphinx-based design document for a computing framework based on various requirements (WIP webpage: https://framework-r-d.github.io/phlex-design/requirements.html).

For each need, we'd like to cross-reference sections within the design document that address that particular need. We'd also like to generate warnings whenever the design document does not refer to a particular need, thus helping us identify requirements that are not yet addressed by the design.

Right now I have to do a lot of this "by hand" and some of it outside of the .. req:: directive body, which doesn't support :numref::

.. req:: Algorithm Decomposability
    :id: DUNE 1
    :Tags: General, Original
    :jama: 1 https://fnal-prod.jamacloud.com/perspective.req?projectId=63&docId=14536
    :status: Approved
    :notes: This is ID #01 from the original DUNE document.
    :collapse: True

    The framework shall allow the execution of multiple algorithms.

- See :numref:`scheduling:Topology of the data-flow graph`

Two questions:

1. Is there a way that such section-references (e.g. the :numref:` ...` ) can be automatically generated whenever a section of the document calls (e.g.) :need:`DUNE 1` ?
2. Can we use sphinx-needs such that a warning is generated (or report given) of which needs are not referenced in the design document?

[ubmax]

Hi Kyle,

Thanks a lot for your detailed comment. Your use case sounds really interesting and aligns closely with what we had in mind when building Sphinx-Needs!

We’d love to get more feedback on your setup and see how we can help streamline it. If you're open to it, we'd be happy to set up a short call just to better understand your needs and discuss possible solutions. We’re particularly interested in how we can make cross-referencing and coverage validation more intuitive in real-world projects like yours.

Feel free to reach out to us at [email protected] if that sounds good to you. We’d be happy to coordinate something!

[knoepfel]

Thanks, @ubmax. I'll send a note to the email address you mentioned.