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
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
.. _needimport:
needimport
==========
.. versionadded:: 0.1.33
``needimport`` allows the import of needs from a JSON file.
You can generate a valid file using the builder :ref:`needs_builder`, for example:
.. code-block:: rst
.. needimport:: needs.json
:id_prefix: imp_
:version: 1.0
:tags: imported;external
:hide:
:collapse:
:filter: "test" in tags
:template: template.rst
:pre_template: pre_template.rst
:post_template: post_template.rst
The directive argument can be one of the following formats:
- A remote URL from which to download the ``needs.json``:
.. code-block:: rst
.. needimport:: https://my_company.com/docs/remote-needs.json
- A local path relative to the containing document:
.. code-block:: rst
.. needimport:: needs.json
- A local path starting with ``/`` is relative to the Sphinx source directory:
.. code-block:: rst
.. needimport:: /path/to/needs.json
- For an absolute path, make sure to start with two ``//`` (on Linux/OSX):
.. code-block:: rst
.. needimport:: //absoulte/path/to/needs.json
Options
-------
id_prefix
~~~~~~~~~
You can set ``:id_prefix`` to add a prefix in front of all imported need ids.
This may be useful to avoid duplicated ids.
.. note::
When using ``:id_prefix:``, we replace all ids used for links and inside descriptions,
if the id belongs to an imported need.
version
~~~~~~~
You can specify a specific version for the import using the ``:version:`` option.
This version must exist inside the imported file.
If no version is given, we use the ``current_version`` attribute from the JSON file.
In most cases this should be the latest available version.
tags
~~~~
You can attach tags to existing tags of imported needs using the ``:tags:`` option
(as a comma-separated list).
This may be useful to mark easily imported needs and to create specialised filters for them.
ids
~~~
.. versionadded:: 3.1.0
You can use the ``:ids:`` option to import only the needs with the given ids
(as a comma-separated list).
This is useful if you want to import only a subset of the needs from the JSON file.
filter
~~~~~~
You can use the ``:filter:`` option to imports only the needs which pass the filter criteria.
This is a string that is evaluated as a Python expression,
it is less performant than the ``:ids:`` option, but more flexible.
Please read :ref:`filter` for more information.
hide
~~~~
You can use the ``:hide:`` option to set the **hide** tag for all imported needs.
So they are not rendered on the page.
collapse
~~~~~~~~
The ``:collapse:`` will hide the meta-data information by default, if set to ``True``.
See also :ref:`need_collapse` description of :ref:`need`.
.. warning::
* Imported needs may use different need types as the current project.
* The sphinx project owner is responsible for a correct configuration for internal and external needs.
* There is no automatic type transformation during an import.
Customization
-------------
The following options can be set, which overwrite the related options in the imported need itself.
So you can decide what kind of layout or style to use during import.
* layout
* style
* template
* pre_template
* post_template
.. _needimport-keys:
Global keys
-----------
.. versionadded:: 4.2.0
The :ref:`needs_import_keys` configuration can be used to set global keys for use as the directive arguments.
For example:
.. code-block:: python
needs_import_keys = {"my_key": "path/to/needs.json"}
Allows for the use of:
.. code-block:: restructuredtext
.. needimport:: my_key
|
