needreport¶

New in version 1.0.1.

needreport documents the following configurations from conf.py:

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

To use the needreport directive, you need to set the needs_report_template configuration variable. If you do not set the needs_report_template configuration variable, the plugin uses the default needs report template.

The needs_report_template value is a path to the jinja2 template file. You can use the template file to customise the content generated by needreport.

Note

The default needs report template is set to use dropdown directives for containing each configuration type, which requires the dropdown directive to be available in your Sphinx environment. If you do not have the dropdown directive available, you can use the following configuration to set the default needs report template to use admonition directives instead:

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

Example

.. needreport::
   :types:

Result

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
Issue	issue	IS_	card
PullRequest	pr	PR_	card
Commit	commit	C_	card

Options¶

types¶

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

Example

.. needreport::
   :types:

Result

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
Issue	issue	IS_	card
PullRequest	pr	PR_	card
Commit	commit	C_	card

links¶

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

Example

.. needreport::
   :links:

Result

Need Extra Links

OPTION	INCOMING	OUTGOING	COPY	ALLOW DEAD LINKS
Links	Links incoming	Links outgoing	False	False
Parent_needs	Child needs	Parent needs	False	False
Blocks	Is blocked by	Blocks	True	True
Tests	Is tested by	Tests	True	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

options¶

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

Example

.. needreport::
   :options:

Result

usage¶

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

Example

.. needreport::
   :usage:

Result

NEEDS TYPES	NEEDS PER TYPE
Action	18
Commit	0
Comp	3
Feature	6
Impl	0
Int	0
Issue	0
Milestone	2
Pr	0
Req	51
Spec	19
Sys	0
Test	7
User	0
Total Needs Amount	106