needreport¶
Added 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 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 |
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 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 |
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 3
.. needreport::
:links:
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 |
Tutorial_required_by |
Requires |
Required by |
None |
False |
Tutorial_specifies |
Specified by |
Specifies |
None |
False |
Tutorial_tests |
Tested by |
Tests |
None |
False |
options¶
Flag for adding information about the needs_extra_options configuration parameter. The flag does not require any values.
Example 4
.. needreport::
:options:
Need Extra Options
my_extra_option
another_option
author
comment
amount
hours
image
config
github
value
unit
duration
completion
type
query
specific
max_amount
max_content_lines
id_prefix
user
created_at
updated_at
closed_at
service
url
avatar
params
prefix
url_postfix
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 |
115 |
Spec |
39 |
Impl |
1 |
Test |
11 |
Feature |
8 |
User |
4 |
Action |
24 |
Milestone |
2 |
Tutorial-project |
1 |
Tutorial-req |
2 |
Tutorial-spec |
2 |
Tutorial-test |
4 |
Issue |
0 |
Pr |
0 |
Commit |
0 |
Total Needs Amount |
225 |