File: open_needs.rst

package info (click to toggle)
sphinx-needs 5.1.0%2Bdfsg-1
  • links: PTS, VCS
  • area: main
  • in suites: sid
  • size: 11,924 kB
  • sloc: python: 21,132; javascript: 187; makefile: 89; sh: 29; xml: 10
file content (229 lines) | stat: -rw-r--r-- 6,445 bytes parent folder | download
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
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
.. _open_needs_service:



Open-Needs services
===================

The `Open-Needs <https://open-needs.org/>`__ service retrieves Need objects from a local or remote
`Open-Needs server <https://open-needs.org/open-needs-server/>`__ and
creates Sphinx-Needs objects during build time.
The service creates need objects for each element found by querying the Open-Needs REST-API based server.

The service name for Open-Needs service must be ``open-needs``.

Example of an imported open-needs:

.. code-block:: rst

   .. needservice:: open-needs
      :prefix: ONS_
      :params: skip=0;limit=10

Options
-------
The following options can be specified under ``.. needservice:: open-needs`` directive.

prefix
######
A string, which is taken as prefix for the need-id. E.g. ``ONS_IMPORT_`` –> ``ONS_IMPORT_003``.

**Default value**: ``ONS_NEEDS_``

params
######
A query string used to filter and organize the data retrieved from the ``open-needs`` service.
For example: The query string ``limit=10`` can be used as:

.. code-block:: rst

   .. needservice:: open-needs
      :params: limit=10

Multiple values in the query string must be separated by a comma(``,``) or a semicolon(``;``).
Example: ``:params: skip=1;limit=10``

**Default value**: ``skip=0,limit=100``

url
###
URL of the server. The final ``RESTful API`` address endpoint(`url_postfix <#url_postfix>`_) gets added automatically.
E.g.: ``http://127.0.0.1:9595`` or ``https://open-needs.org/``

**Default value**: http://127.0.0.1:9595

url_postfix
###########
The final address of the endpoint. E.g.: ``/api/needs/``

**Default value**: ``/api/needs/``

max_content_lines
#################
Maximum amount of lines from open-needs objects description/content to be used in need content.

Config
------
Most configuration needs to be done via the :ref:`needs_services` configuration in your **conf.py** file.

:ref:`needs_services` must contain a key with the service name, E.g. ``open-needs``

The following key-value configuration parameters can be set for the Open-Need services:

url
###
Open-Needs service instance url. Default: ``https://api.open-need.com/``

username
########
Username credentials used for login.

password
########
Password credentials used for login.

id_prefix
#########
Prefix string for the final need id.

mapping
#######
The field names of a service object do not often map to option names of Sphinx-Needs.
So **mapping** defines where a Sphinx-Needs option shall get its value inside the service data.

**mapping** must be a dictionary, where the key is the needs object name and the value is either a Jinja string such as ``is_{{status}}``
or a list/tuple, which defines the location of the value in the retrieved service data object.

.. _open_need_data:

.. dropdown:: Example of an Open-Needs service data object

   .. code-block::

      [
         {
           "key": "NEP_001",
           "type": "Requirement",
           "title": "Build rocket",
           "description": "We finally need to build our Neptune3000 rocket.",
           "format": "txt",
           "project_id": 1,
           "options": {
             "status": "done",
             "priority": "high",
             "costs": 3500000,
             "approved": 1,
             "lastname": "Duodu"
             "firstname": "Randy"
           },
           "references": {
             "links": [
               "NEP_001",
               "NEP_002"
             ]
           }
         },
      ]


**Example using a Jinja string as value for the Open-Needs service**

Goal: The need option ``author`` shall be set to the last and first names.

The last and first names information are stored in the retrieved :ref:`Open-Needs <open_need_data>` data
under ``lastname`` and ``firstname``.

The **mapping** entry for ``author`` would like this:


.. code-block:: python

    'mapping': {
        'author': "{{options.lastname}} {{options.firstname}}",
    }

.. note::

   When you use a Jinja string as value, you must ensure the field names of a service object does not contain spaces because that will raise a
   `Jinja Template Syntax Error <https://jinja.palletsprojects.com/en/3.1.x/api/#jinja2.TemplateSyntaxError>`_.
   For example: Instead of the field name being ``last name`` use ``last_name``.

**Example using a list/tuple as value for the Open-Needs service**

Goal: The need option ``author`` shall be set to the last name.

The **mapping** entry for ``author`` would like this:

.. code-block:: python

    'mapping': {
        'author': ["options", "lastname"],
    }

content
#######
Content takes a string, which gets interpreted as rst-code for the need-content area.
Jinja support is also available, so that service data is available and can be accessed like ``{{data.description}}``.

mappings_replaces
#################
There are use cases, where a value inside service data is not valid for a Sphinx-Needs options.
For instance: In the data retrieved from the Open-Needs server, ``type`` is named ``Requirement``, but Sphinx-Needs supports only ``req`` as value for type option.

**mappings_replaces** can replace strings defined by a regular expression with a new value. This replacement is performed for all mappings.

extra_data
##########
There may be information stored inside the :ref:`Open-Needs <open_need_data>` service data fields
which cannot be mapped to the Sphinx-Needs options, but is available inside the Need object.

This can be done by using ``extra_data``, which adds this kind of information to the end of the content of a need object.

The logic and syntax is the same as used by `mapping <#mapping>`_.


.. note::

   Some options can be overwritten by setting them directly in the need service directive:

   .. code-block:: rst

      .. needservice:: open-needs
         :url: http://127.0.0.1:9595
         :prefix: ONS_IMPORT
         :params: skip=0;limit=10

**Example configuration for conf.py**:

.. literalinclude:: /conf.py
   :language: python
   :lines: 329-346



Examples
--------
**Code**

.. code-block:: rst

   .. needservice:: open-needs
      :prefix: ONS_
      :params: skip=0;limit=10

   .. needtable::
      :filter: "ONS" in id

**Result**

.. hint::

   The below examples are just images, as no Open-Needs Server instance was available during documentation build.

.. image:: /_images/ons_example.png
   :align: center
   :width: 60%

.. image:: /_images/ons_table.png
   :align: center
   :width: 60%