needreport

Added in version 1.0.1.

needreport documents the following configurations from conf.py:

• Types

• Links

• Fields

and it also adds some needs metrics using the usage option.

needreport renders a template, and out of the box that is the default template packaged with Sphinx-Needs — no configuration is required. To render a template of your own instead, either set the needs_report_template configuration variable, which applies to every needreport in the project, or give a single directive its own template option.

Templates are rendered with MiniJinja, a Jinja-compatible engine. The packaged default template, how a template path is resolved, and the variables a template can read are all documented under needs_report_template.

Note

Each section of the default template is wrapped in a dropdown directive, which neither Sphinx nor Sphinx-Needs provides — it needs an extension that supplies one, for example sphinx-design. If none is loaded, the report is rendered with admonition instead and warns. A template of your own is only affected if that substitution actually changes what it renders; see needs_report_template. To pick the directive yourself, and so render without a warning:

needs_render_context = {
   "report_directive": "admonition",
}

Example 1

.. needreport::
   :types:

Need Types

TITLE	DIRECTIVE	PREFIX	STYLE
Interface	int	I_	card
Component	comp	C_	card
System	sys	S_	card
Requirement	req	R_	node
Specification	spec	S_	node
Implementation	impl	I_	node
Test Case	test	T_	node
Feature	feature	F_	node
User	user	U_	node
Action	action	A_	node
Milestone	milestone	M_	node
Project	tutorial-project	P_	rectangle
Requirement	tutorial-req	R_	rectangle
Specification	tutorial-spec	S_	rectangle
Test Case	tutorial-test	T_	rectangle
Issue	issue	IS_	card

Options

types

Flag for adding information about the needs_types configuration parameter. The flag does not require any values.

Example 2

.. needreport::
   :types:

Need Types

TITLE	DIRECTIVE	PREFIX	STYLE
Interface	int	I_	card
Component	comp	C_	card
System	sys	S_	card
Requirement	req	R_	node
Specification	spec	S_	node
Implementation	impl	I_	node
Test Case	test	T_	node
Feature	feature	F_	node
User	user	U_	node
Action	action	A_	node
Milestone	milestone	M_	node
Project	tutorial-project	P_	rectangle
Requirement	tutorial-req	R_	rectangle
Specification	tutorial-spec	S_	rectangle
Test Case	tutorial-test	T_	rectangle
Issue	issue	IS_	card

links

Flag for adding information about the needs_links configuration parameter. The flag does not require any values.

Example 3

.. needreport::
   :links:

Need Links

NAME	INCOMING	OUTGOING	COPY	ALLOW DEAD LINKS
Blocks	Is blocked by	Blocks	False	True
Tests	Is tested by	Tests	False	False
Checks	Is checked by	Checks	False	False
Triggers	Triggered by	Triggers	False	True
Starts_with	Triggers directly	Starts with	False	False
Starts_after	Triggers at end	Starts after	False	False
Ends_with	Triggers to end with	Ends with	False	False
Tutorial_required_by	Requires	Required by	False	False
Tutorial_specifies	Specified by	Specifies	False	False
Tutorial_tests	Tested by	Tests	False	False
Links	Links incoming	Links outgoing	False	False
Parent_needs	Child needs	Parent needs	False	False

options

Flag for adding information about the needs_fields configuration parameter. The flag does not require any values.

Example 4

.. needreport::
   :options:

Need Fields

• my_extra_option

• another_option

• author

• comment

• duration

• completion

• image

• config

• github

• query

• specific

• max_amount

• max_content_lines

• id_prefix

• user

• created_at

• updated_at

• closed_at

• service

• url

• avatar

• amount

• value

• unit

• hours

usage

Flag for adding information about all the need objects in the current project. The flag does not require any values.

Example 5

.. needreport::
   :usage:

Need Metrics

NEEDS TYPES	NEEDS PER TYPE
Int	2
Comp	9
Sys	1
Req	120
Spec	44
Impl	1
Test	12
Feature	8
User	4
Action	24
Milestone	2
Tutorial-project	1
Tutorial-req	2
Tutorial-spec	2
Tutorial-test	4
Issue	8
Total Needs Amount	244

template

Path to the template this directive should render, overriding needs_report_template for this one directive. Unlike the flags above, it takes a value.

The path is resolved relative to the document the directive is written in, and a leading / makes it relative to the source directory — the path convention Sphinx uses throughout, and not the one needs_report_template uses, which is always relative to the source directory whether or not it starts with a /.

.. needreport::
   :types:
   :template: report_templates/types_only.need

If the file does not exist, a needs.needreport warning is emitted and the directive renders nothing.