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 is designed to allow the injection of extra configuration. The overall manipulation (e.g remove need types) is not supported 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, function)¶

Registers a new dynamic function for sphinx-needs.

The name to call the function is automatically taken from the provided function and must be unique.

Usage:

from sphinxcontrib.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 application object function – Function to register
Returns:	None

add_extra_option(app, name)¶

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 sphinxcontrib.needs.api import add_extra_option

add_extra_option(app, 'my_extra_option')

Parameters:	app – Sphinx application object name – Name as string of the extra option
Returns:	None

add_need_type(app, directive, title, prefix, color='#ffffff', style='node')¶

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 sphinxcontrib.needs.api import add_need_type

add_need_type(app, 'awesome', 'Awesome', 'AW_', '#000000', 'cloud')

Parameters:	app – Sphinx application object directive – Name of the directive, e.g. ‘story’ title – Long, human-readable title, e.g. ‘User-Story’ prefix – Prefix, if IDs get automatically generated. E.g.: `'US_'` color – Hex-color code used in needflow representation. Default: `'#ffffff'` style – Plantuml-style for needflow representation. Default: ‘node’
Returns:	None

get_need_types(app)¶

Returns a list of directive-names from all configured need_types.

Usage:

from sphinxcontrib.needs.api import get_need_types

all_types = get_need_types(app)

Parameters:	app – Sphinx application object
Returns:	list of strings

Need¶

add_need(app, state, docname, lineno, need_type, title, id=None, content='', status=None, tags=None, links_string=None, hide=False, hide_tags=False, hide_status=False, collapse=None, style=None, layout=None, template=None, pre_template=None, post_template=None, **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.

Usage:

Normally needs get created during handling of a specialised directive. So this pseudo-code shows how to use add_need inside such a directive.

from docutils.parsers.rst import Directive
from sphinxcontrib.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 application object.
state – Current state object.
docname – documentation name.
lineno – line number.
need_type – Name of the need type to create.
title – String as title.
id – ID as string. If not given, a id will get generated.
content – Content as single string.
status – Status as string.
tags – Tags as single string.
links_string – Links as single string.
hide – boolean value.
hide_tags – boolean value. (Not used with Sphinx-Needs >0.5.0)
hide_status – boolean value. (Not used with Sphinx-Needs >0.5.0)
collapse – boolean value.
style – String value of class attribute of node.
layout – String value of layout definition to use
template – Template name to use for the content of this need
pre_template – Template name to use for content added before need
post_template – Template name to use for the content added after need

Returns:

node

make_hashed_id(app, need_type, full_title, content, id_length=None)¶

Creates an ID based on title or need.

Also cares about the correct prefix, which is specified for each need type.

Parameters:	app – Sphinx application object need_type – name of the need directive, e.g. req full_title – full title of the need content – content of the need id_length – 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 NeedsDuplicatedId¶

exception NeedsInvalidException¶

exception NeedsInvalidFilter¶

exception NeedsInvalidOption¶

exception NeedsNoIdException¶

exception NeedsNotLoadedException¶

Sphinx-Needs is not loaded. Therefore configuration parameters and functions are missing.

Make sure sphinxcontrib.needs is added to the``extension`` parameter of conf.py-

exception NeedsStatusNotAllowed¶

exception NeedsTagNotAllowed¶

exception NeedsTemplateException¶