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

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