Sphinx-Needs across the V-model

Engineering along the V-model runs in five steps: define what the system must do, implement it, verify it, iterate when something changes, and prove, at a release, how each requirement is implemented, verified and traced. This page maps each step to what Sphinx-Needs and its sibling extensions offer, and links the pages that describe it.

        flowchart LR
  define["Define<br/>need types, links, schemas"]
  implement["Implement<br/>Sphinx-CodeLinks"]
  verify["Verify<br/>Sphinx-Test-Reports, warnings"]
  prove["Prove<br/>tables, charts, needs.json"]
  iterate["Iterate<br/>back links, filters, needextend"]
  define --> implement --> verify --> prove
  prove -.->|a change| iterate -.-> define

Define

Requirements, specifications and test cases become typed needs, linked along the V-model.

  • The need items directive writes a need in your documentation; the Tutorial builds a small linked model step by step.

  • needs_types declares your need types, and Modeling need types shows how to give each type its own fields and links.

  • needs_links declares link types, such as a specification that implements a requirement.

  • Schema validation states the rules your needs and their links must follow: the type of each field, which fields a type requires, and which needs a link may point to.

Implement

The code that realises a requirement, traced back to it.

  • Sphinx-CodeLinks reads one-line markers from your source code comments: a marker either defines a new need, or names an existing need’s ID to trace the code to it.

Verify

Test results traced to the needs they verify, and a build that fails when a rule is broken.

  • Sphinx-Test-Reports turns JUnit XML and JSON test results into needs, which you can link to the specifications they test, filter and report on.

  • A need that breaks a schema rule is reported in the build log, as a warning or an error by its severity; build with -W to make the build fail on it (Build Warnings).

Iterate

A change to one need, and the needs it touches.

  • Every link type has back links, named <link>_back: a need’s card shows the needs that link to it, and a needtable can list them as a column.

  • A filter string selects the needs a question is about, such as every test linked to one requirement.

  • needextend changes existing needs in bulk, for example the status of every need a filter selects.

  • The needs builder, given the previous needs.json through needs_file, stores each documentation version’s needs side by side in it, and needimport imports the needs of a needs.json, such as another project’s.

Sphinx-Needs has no impact analysis of its own; ubCode adds it with ubc diff.

Prove

The evidence for a release, built from the same sources as the documentation.

  • needtable, needflow and needpie render traceability tables, diagrams and charts from a filter, and needextract renders copies of the needs a filter selects in another document.

  • A Sphinx builder, such as HTML, publishes the result; the needs builder, or needs_build_json beside another builder, exports every need to needs.json for other tools to read.