Sphinx Needs Usage Guide

This guide explains how to use sphinx-needs for requirements engineering and traceability in the Cleanroom Labs technical documentation.

What is sphinx-needs?

sphinx-needs is a Sphinx extension that provides directives for requirements engineering. It allows you to:

  • Define requirements, tests, specifications, and other needs

  • Link needs bidirectionally

  • Generate traceability matrices automatically

  • Create visual flow diagrams

  • Filter and search needs

  • Validate completeness and coverage

Why Use sphinx-needs?

Benefits:

  • ✅ Bidirectional Traceability: Automatically track relationships between requirements, designs, implementations, and tests

  • ✅ Automated Validation: Sphinx validates all links at build time

  • ✅ Visual Diagrams: Auto-generate flowcharts showing relationships

  • ✅ Searchable: Full-text search across all requirements

  • ✅ Maintainable: Changes propagate automatically

  • ✅ Standards-Aligned: Implements the project’s documentation standards framework

This guide covers the technical details of creating and linking needs directives. For the IEEE standards that inform this documentation framework and the artifact type definitions, see Documentation Standards Framework. For the full list of directive types, prefixes, and their purposes, see the artifact type schema.

Creating Needs

Basic Syntax

All sphinx-needs directives follow this pattern:

.. directive:: Title
   :id: UNIQUE-ID
   :status: approved|pending|rejected
   :tags: tag1, tag2, tag3
   :priority: must|should|could|won't  (or high|medium|low|critical)
   :links-to-other-needs: OTHER-ID-1, OTHER-ID-2

   Description of the need goes here.
   Can be multiple paragraphs.

Use Case Example

.. usecase:: Large File Transfer
   :id: UC-TRANSFER-001
   :status: approved
   :tags: transfer, workflow, large-file, chunking

   Transfer a single large file (50GB VM image) across air-gap using
   multiple 16GB USB drives with automatic chunking.

   **Pack:** Split file into chunks sized for USB capacity.

   **Transfer:** Physically move USB drives across air-gap.

   **Unpack:** Verify checksums, reconstruct original file.

   **Success Criteria:** File reconstructed matches original, all
   checksums verified, no data loss.

Functional Requirement Example

.. req:: Split Files into Chunks
   :id: FR-TRANSFER-001
   :status: approved
   :tags: transfer, pack, chunking
   :priority: must
   :satisfies: UC-TRANSFER-001

   The system SHALL split source files/directories into fixed-size
   chunks suitable for transfer across air-gap boundaries.

Non-Functional Requirement Example

.. nfreq:: Offline Functionality
   :id: NFR-TRANSFER-004
   :status: approved
   :tags: transfer, offline
   :priority: must

   The system SHALL be 100% functional without network connectivity.
   All operations must work in air-gapped environments.

Test Case Example

.. test:: Pack Single File into Chunks
   :id: TC-PCK-001
   :status: approved
   :tags: transfer, pack, chunking
   :tests: FR-TRANSFER-001
   :priority: high

   **Objective:** Verify pack operation splits single file into chunks.

   **Setup:** Create 50GB test file, connect 16GB USB drive.

   **Steps:**
   1. Run: airgap-transfer pack vm-image.qcow2 /media/usb-drive
   2. Verify 4 chunks created (3x 16GB + 1x 2GB)
   3. Verify checksums generated for each chunk
   4. Verify manifest file created

   **Expected:** All chunks created successfully with valid checksums.

Implementation Example (Future)

.. impl:: Chunker Implementation
   :id: IMPL-TRANSFER-001
   :implements: FR-TRANSFER-001, FR-TRANSFER-002, FR-TRANSFER-005
   :status: implemented
   :location: src/chunker/mod.rs
   :tests: TC-PCK-001, TC-PCK-002, TC-PCK-003

   Streaming file chunker that splits files into fixed-size chunks
   without creating temporary files. Uses memory-mapped I/O for
   efficient processing.

   See :rust:struct:`Chunker` for API documentation.

Linking Needs

Generating Traceability Matrices

needtable Directive

Generate tables of needs with filtering:

Requirements Table
^^^^^^^^^^^^^^^^^^

.. needtable::
   :types: req, nfreq
   :columns: id, title, priority, status, outgoing
   :filter: "transfer" in tags
   :style: table

Parameters:

  • :types: - Which directive types to include

  • :columns: - Which fields to display

  • :filter: - Filter expression (Python syntax)

  • :style: - Display style (table, datatables)

Common Filters

By project:

:filter: "whisper" in tags

By status:

:filter: status == "approved"

By priority:

:filter: priority == "must" or priority == "critical"

Untested requirements:

:filter: len(tests_back) == 0

Multiple conditions:

:filter: "transfer" in tags and status == "approved" and priority == "must"

Column Options

Available columns:

  • id - Unique identifier

  • title - Need title

  • status - Status (approved, pending, rejected)

  • tags - Tags list

  • priority - Priority level

  • outgoing - Links TO other needs

  • incoming - Links FROM other needs

Requirements to Tests Table

Requirements Coverage
^^^^^^^^^^^^^^^^^^^^^

.. needtable::
   :types: req, test
   :columns: id, title, status, outgoing
   :filter: "whisper" in tags
   :style: table

This shows all requirements and tests, with the outgoing column showing which tests validate each requirement.

Creating Flow Diagrams

needflow Directive

Generate visual diagrams of need relationships:

Traceability Flow
^^^^^^^^^^^^^^^^^

.. needflow::
   :types: usecase, req, test
   :tags: transfer
   :show_link_names:

Parameters:

  • :types: - Which directive types to include in diagram

  • :tags: - Filter by tags

  • :show_link_names: - Display link type labels on arrows

  • :filter: - Advanced filtering (same as needtable)

Full Traceability Diagram

Complete Traceability
^^^^^^^^^^^^^^^^^^^^^

.. needflow::
   :types: usecase, req, nfreq, impl, test
   :tags: whisper
   :show_link_names:

This creates a Graphviz diagram showing:

  • Use cases at the top

  • Requirements in the middle

  • Implementations and tests at the bottom

  • Arrows showing relationships

  • Color-coded by directive type

Focused Diagrams

Just requirements and tests:

.. needflow::
   :types: req, test
   :tags: recording
   :show_link_names:

Specific requirement and its links:

.. needflow::
   :filter: id == "FR-WHISPER-001" or "FR-WHISPER-001" in links

Best Practices

ID Naming Conventions

Format: PREFIX-PROJECT-(COMPONENT-)###

Examples:

  • FR-WHISPER-001 - Cleanroom Whisper functional requirement #1

  • NFR-DEPLOY-005 - AirGap Deploy non-functional requirement #5

  • TC-TRANSFER-CLI-003 - AirGap Transfer CLI test #3

  • UC-WHISPER-001 - Cleanroom Whisper use case #1

Rules:

  • Use project name in ID for clarity

  • Sequential numbering within each type

  • Add subcategory for tests (TC-CLI, TC-ERR, etc.)

  • Never reuse IDs

Status Values

Use consistent status values:

  • approved - Requirement is approved and ready for implementation

  • pending - Under review, not yet approved

  • rejected - Explicitly rejected, not to be implemented

Priority Values

For requirements (MoSCoW):

  • must - Must have, critical

  • should - Should have, important

  • could - Could have, nice to have

  • won't - Won’t have this release

For tests:

  • critical - Critical test, must pass

  • high - High priority

  • medium - Medium priority

  • low - Low priority

Tags

Use hierarchical tags:

  • Project: whisper, deploy, transfer

  • Feature: recording, transcription, packaging, chunking

  • Type: security, performance, usability

  • Platform: linux, macos, windows

Example:

:tags: whisper, recording, security, linux

Writing Good Descriptions

Requirements:

  • Start with SHALL/SHOULD/MAY

  • Be specific and measurable

  • One requirement per directive

  • Include acceptance criteria

Tests:

  • Include objective, setup, steps, expected result

  • Link to ALL requirements tested

  • Be reproducible

  • Include pass/fail criteria

Use Cases:

  • Describe user’s goal

  • Include actors, preconditions, success criteria

  • Link to requirements that satisfy it

Validation

Build-Time Checks

Sphinx validates:

  • ✅ All need IDs are unique

  • ✅ All linked IDs exist

  • ✅ Required options are present

  • ✅ Status values are valid

Error example:

WARNING: Need could not be created: A need with ID 'TC-001' already exists.
ERROR: Unknown status 'complete' for need 'FR-WHISPER-001'

Coverage Checking

Use filters to find gaps:

Untested requirements:

.. needtable::
   :types: req
   :columns: id, title
   :filter: len(tests_back) == 0

Requirements without use cases:

.. needtable::
   :types: req
   :columns: id, title
   :filter: len(satisfies) == 0

Common Tasks

Adding a New Requirement

Choose ID: Next sequential number (e.g., FR-WHISPER-037) Add directive to SRS:

.. req:: Brief Title
   :id: FR-WHISPER-037
   :status: pending
   :tags: whisper, feature-name
   :priority: should
   :satisfies: UC-WHISPER-001

   The system SHALL [specific requirement].

Build docs: make html Verify: Check traceability matrix shows new requirement

Adding a New Test Case

Choose ID: Sequential in category (e.g., TC-REC-010) Add directive to testing plan:

.. test:: Brief Title
   :id: TC-REC-010
   :status: approved
   :tags: whisper, recording
   :tests: FR-WHISPER-037
   :priority: high

   **Objective:** Verify [what]

   **Steps:**
   1. [Step 1]
   2. [Step 2]

   **Expected:** [Expected result]

Build docs: make html Verify: Requirement now shows “tested by TC-REC-010”

Updating Traceability

When requirements change:

Update the requirement directive Update linked test cases Update :satisfies: links if use cases changed Run make html to regenerate matrices Check needflow diagrams for accuracy

Troubleshooting

Duplicate ID Error

Error:

WARNING: Need could not be created: A need with ID 'TC-CLI-001' already exists.

Solution:

Use project prefix: TC-TRANSFER-CLI-001 instead of TC-CLI-001

Missing in Traceability Matrix

Problem: Need doesn’t appear in needtable

Solutions:

Check :filter: expression matches need’s tags Check :types: includes need’s directive type Rebuild with make clean && make html

Summary

Key Points:

  • ✅ Use directive types consistently (usecase, req, nfreq, test, impl, spec)

  • ✅ Follow ID naming conventions (PREFIX-PROJECT-(COMPONENT-)###)

  • ✅ Link needs bidirectionally (:tests:, :implements:, :satisfies:)

  • ✅ Use tags for filtering and organization

  • ✅ Generate matrices with needtable

  • ✅ Visualize with needflow

  • ✅ Validate at build time

Workflow:

Write use cases (.. usecase::) Write requirements that satisfy use cases (:satisfies:) Write design specs that implement requirements (:implements:) Write code with doc comments referencing requirements Write tests that validate requirements (:tests:) Generate matrices to verify coverage Build docs to validate all links

Result:

Complete, validated, bidirectional traceability from use cases through requirements, design, implementation, and tests.

See Also