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.

Parameters:
app: Sphinx

Sphinx application object

function: Callable[[Sphinx, Any, Any], str, int, float, list[str, int, float]]

Function to register

name: str | None = None

Name of the dynamic function as string

Returns:

None

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')
Parameters:
app: Sphinx

Sphinx application object

name: str

Name as string of the extra option

Returns:

None

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[[Any, 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.

Parameters:
app: Sphinx

Sphinx app object

name: str

Name as string for the warning

function: Callable[[Any, SphinxLoggerAdapter], bool] | None = None

function to execute to check the warning

filter_string: str | None = None

filter_string to use for the warning

Returns:

None

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)
Parameters:
app: Sphinx

Sphinx application object

Returns:

list of strings

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: str | None = None

Tags as single string.

constraints: str | None = None

constraints as single, comma separated string.

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 in needs_extra_options and needs_extra_links. If an entry is found in kwags, which is not specified in the configuration or registered e.g. via add_extra_option, an exception is raised.

If is_external is set to True, 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 docutils.parsers.rst import Directive
from sphinx_needs.api import add_need

class MyDirective(Directive)
    # configs and init routine

    def run():
        main_section = []

        docname = self.state.document.settings.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=None

Tags as single string.

constraints=None

Constraints as single, comma separated, string.

constraints_passed=None

Contains bool describing if all constraints have passed

Links as single string.

delete: bool = False

boolean value (Remove the complete need).

hide: bool = False

boolean value.

hide_tags: bool = False

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 is True

external_css: str = 'external_link'

CSS class name as string, which is set for the <a> tag.

Returns:

node

del_need(app: Sphinx, id: str) None

Deletes an existing need.

Parameters:
app: Sphinx

Sphinx application object.

id: str

Sphinx need id.

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.

Parameters:
app: Sphinx

Sphinx application object

need_type: str

name of the need directive, e.g. req

full_title: str

full title of the need

content: str

content of the need

id_length: int | None = None

maximum length of the generated ID

Returns:

ID as string

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