API¶
Sphinx-Needs provides an open API for other Sphinx-extensions to provide specific need-types, create needs or make usage of the filter possibilities.
The API allows the injection of extra configuration into it. The API does not support the overall manipulation (e.g remove need types) to keep the final configuration transparent for the Sphinx project authors.
For some implementation ideas, take a look into the Sphinx extension Sphinx-Test-Reports and its source code.
Configuration¶
API to get or add specific sphinx needs configuration parameters.
All functions here are available under sphinxcontrib.api
. So do not import this module directly.
-
add_dynamic_function(app: Sphinx, function: Callable[[Sphinx, Any, Any], str | int | float | list[str | int | float]], name: str | None =
None
) None ¶ Registers a new dynamic function for sphinx-needs.
If
name
is not given, the name to call the function is automatically taken from the provided function. The used name must be unique.Usage:
from sphinx_needs.api import add_dynamic_function def my_function(app, need, needs, *args, **kwargs): # Do magic here return "some data" add_dynamic_function(app, my_function)
Read Dynamic functions for details about how to use dynamic functions.
- add_extra_option(app: Sphinx, name: str) None ¶
Adds an extra option to the configuration. This option can then later be used inside needs or
add_need
.Same impact as using needs_extra_options manually.
Usage:
from sphinx_needs.api import add_extra_option add_extra_option(app, 'my_extra_option')
-
add_need_type(app: Sphinx, directive: str, title: str, prefix: str, color: str =
'#ffffff'
, style: str ='node'
) None ¶ Adds a new need_type to the configuration.
The given directive must no exist, otherwise NeedsApiConfigException gets raised.
Same impact as using needs_types manually.
Usage:
from sphinx_needs.api import add_need_type add_need_type(app, 'awesome', 'Awesome', 'AW_', '#000000', 'cloud')
- Parameters:¶
- app: Sphinx¶
Sphinx application object
- directive: str¶
Name of the directive, e.g. ‘story’
- title: str¶
Long, human-readable title, e.g. ‘User-Story’
- prefix: str¶
Prefix, if IDs get automatically generated. E.g.:
'US_'
- color: str =
'#ffffff'
¶ Hex-color code used in needflow representation. Default:
'#ffffff'
- style: str =
'node'
¶ Plantuml-style for needflow representation. Default: ‘node’
- Returns:¶
None
-
add_warning(app: Sphinx, name: str, function: Callable[[NeedsInfoType, SphinxLoggerAdapter], bool] | None =
None
, filter_string: str | None =None
) None ¶ Registers a warning.
A warning can be based on the result of a given filter_string or an own defined function.
- get_need_types(app: Sphinx) list[str] ¶
Returns a list of directive-names from all configured need_types.
Usage:
from sphinx_needs.api import get_need_types all_types = get_need_types(app)
Need¶
-
add_external_need(app: Sphinx, need_type, title: str | None =
None
, id: str | None =None
, external_url: str | None =None
, external_css: str ='external_link'
, content: str =''
, status: str | None =None
, tags: str | None =None
, constraints: str | None =None
, links_string: str | None =None
, **kwargs: Any)¶ Adds an external need from an external source. This need does not have any representation in the current documentation project. However, it can be linked and filtered. It’s reference will open a link to another, external sphinx documentation project.
It returns an empty list (without any nodes), so no nodes will be added to the document.
- Parameters:¶
- app: Sphinx¶
Sphinx application object.
- need_type¶
Name of the need type to create.
- title: str | None =
None
¶ String as title.
- id: str | None =
None
¶ ID as string. If not given, a id will get generated.
- external_url: str | None =
None
¶ URL as string, which shall be used as link to the original need source
- content: str =
''
¶ Content as single string.
- status: str | None =
None
¶ Status as string.
Tags as single string.
- constraints: str | None =
None
¶ constraints as single, comma separated string.
- links_string: str | None =
None
¶ Links as single string.
- external_css: str =
'external_link'
¶ CSS class name as string, which is set for the <a> tag.
- **kwargs: Any¶
- Returns:¶
Empty list
-
add_need(app: Sphinx, state, docname: str, lineno: int, need_type, title: str, id: str | None =
None
, content: str =''
, status: str | None =None
, tags=None
, constraints=None
, constraints_passed=None
, links_string: str | None =None
, delete: bool =False
, jinja_content: bool =False
, hide: bool =False
, hide_tags: bool =False
, hide_status: bool =False
, collapse=None
, style=None
, layout=None
, template=None
, pre_template: str | None =None
, post_template: str | None =None
, is_external: bool =False
, external_url: str | None =None
, external_css: str ='external_link'
, **kwargs)¶ Creates a new need and returns its node.
add_need
allows to create needs programmatically and use its returned node to be integrated in any docutils based structure.kwags
can contain options defined inneeds_extra_options
andneeds_extra_links
. If an entry is found inkwags
, which is not specified in the configuration or registered e.g. viaadd_extra_option
, an exception is raised.If
is_external
is set toTrue
, no node will be created. Instead, the need is referencing an external url. Used mostly for needs_external_needs to integrate and reference needs from external documentation.Usage:
Normally needs get created during handling of a specialised directive. So this pseudocode shows how to use
add_need
inside such a directive.from sphinx.util.docutils import SphinxDirective from sphinx_needs.api import add_need class MyDirective(SphinxDirective) # configs and init routine def run(): main_section = [] docname = self.env.docname # All needed sphinx-internal information we can take from our current directive class. # e..g app, state, lineno main_section += add_need(self.env.app, self.state, docname, self.lineno, need_type="req", title="my title", id="ID_001" content=self.content) # Feel free to add custom stuff to main_section like sections, text, ... return main_section
- Parameters:¶
- app: Sphinx¶
Sphinx application object.
- state¶
Current state object.
- docname: str¶
documentation name.
- lineno: int¶
line number.
- need_type¶
Name of the need type to create.
- title: str¶
String as title.
- id: str | None =
None
¶ ID as string. If not given, an id will get generated.
- content: str =
''
¶ Content as single string.
- status: str | None =
None
¶ Status as string.
Tags as single string.
- constraints=
None
¶ Constraints as single, comma separated, string.
- constraints_passed=
None
¶ Contains bool describing if all constraints have passed
- links_string: str | None =
None
¶ Links as single string.
- delete: bool =
False
¶ boolean value (Remove the complete need).
- hide: bool =
False
¶ boolean value.
boolean value. (Not used with Sphinx-Needs >0.5.0)
- hide_status: bool =
False
¶ boolean value. (Not used with Sphinx-Needs >0.5.0)
- collapse=
None
¶ boolean value.
- style=
None
¶ String value of class attribute of node.
- layout=
None
¶ String value of layout definition to use
- template=
None
¶ Template name to use for the content of this need
- pre_template: str | None =
None
¶ Template name to use for content added before need
- post_template: str | None =
None
¶ Template name to use for the content added after need
- is_external: bool =
False
¶ Is true, no node is created and need is referencing external url
- external_url: str | None =
None
¶ URL as string, which is used as target if
is_external
isTrue
- external_css: str =
'external_link'
¶ CSS class name as string, which is set for the <a> tag.
- Returns:¶
node
-
make_hashed_id(app: Sphinx, need_type: str, full_title: str, content: str, id_length: int | None =
None
) str ¶ Creates an ID based on title or need.
Also cares about the correct prefix, which is specified for each need type.
Exceptions¶
- exception NeedsApiConfigException¶
A configuration changes collides with the already provided configuration by the user.
Example: An extension wants to add an already existing needs_type.
- exception NeedsApiConfigWarning¶
- exception NeedsConstraintFailed¶
- exception NeedsConstraintNotAllowed¶
- exception NeedsDuplicatedId¶
- exception NeedsInvalidException¶
- exception NeedsInvalidFilter¶
- exception NeedsInvalidOption¶
- exception NeedsNoIdException¶
- exception NeedsStatusNotAllowed¶
- exception NeedsTagNotAllowed¶
- exception NeedsTemplateException¶