Skip to content
Back to top
View this page
Edit this page

# needreport

Added in version 1.0.1.

needreport documents the following configurations from conf.py:

- Types

- Links

- Options

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