1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
.. _needreport:
needreport
==========
.. versionadded:: 1.0.1
**needreport** documents the following configurations from **conf.py**:
* :ref:`Types <needs_types>`
* :ref:`Links <needs_extra_links>`
* :ref:`Options <needs_extra_options>`
and it also adds some needs metrics using the `usage`_ option.
To use the ``needreport`` directive, you need to set the :ref:`needs_report_template`
configuration variable. If you do not set the :ref:`needs_report_template`
configuration variable, the plugin uses the default needs report template.
The :ref:`needs_report_template` value is a path to the
`jinja2 <https://jinja.palletsprojects.com/en/2.11.x/templates/>`_ 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:
.. code-block:: python
needs_render_context = {
"report_directive": "admonition",
}
.. need-example::
.. needreport::
:types:
Options
-------
.. _types:
types
~~~~~
Flag for adding information about the :ref:`needs_types` configuration parameter.
The flag does not require any values.
.. need-example::
.. needreport::
:types:
.. _links:
links
~~~~~
Flag for adding information about the :ref:`needs_extra_links` configuration parameter.
The flag does not require any values.
.. need-example::
.. needreport::
:links:
.. _options:
options
~~~~~~~
Flag for adding information about the :ref:`needs_extra_options` configuration parameter.
The flag does not require any values.
.. need-example::
.. needreport::
:options:
usage
~~~~~
Flag for adding information about all the ``need`` objects in the current project.
The flag does not require any values.
.. need-example::
.. needreport::
:usage:
|
