Open-Needs services¶
The Open-Needs service retrieves Need objects from a local or remote 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:
.. 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:
.. 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) 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 needs_services configuration in your conf.py file.
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.
Example of an Open-Needs service data object
[
{
"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 Open-Needs data
under lastname
and firstname
.
The mapping entry for author
would like this:
'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.
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:
'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 Open-Needs 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.
Note
Some options can be overwritten by setting them directly in the need service directive:
.. needservice:: open-needs
:url: http://127.0.0.1:9595
:prefix: ONS_IMPORT
:params: skip=0;limit=10
Example configuration for conf.py:
from docutils.statemachine import StringList # noqa: E402
from sphinx.application import Sphinx # noqa: E402
from sphinx.directives import SphinxDirective # noqa: E402
from sphinx.roles import SphinxRole # noqa: E402
from sphinx_needs.api import generate_need # noqa: E402
from sphinx_needs.config import NeedsSphinxConfig # noqa: E402
from sphinx_needs.logging import ( # noqa: E402
WarningSubTypeDescription,
WarningSubTypes,
)
from sphinx_needs.needsfile import NeedsList # noqa: E402
class NeedsWarningsDirective(SphinxDirective):
"""Directive to list all extension warning subtypes."""
def run(self):
Examples¶
Code
.. 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.