def add_dynamic_function(app, function, name=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 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 :ref:`dynamic_functions` for details about how to use dynamic functions.
:param app: Sphinx application object
:param function: Function to register
:param name: Name of the dynamic function as string
:return: None
"""
register_func(function, name)
def prepare_env(app, env, docname):
"""
Prepares the sphinx environment to store sphinx-needs internal data.
"""
if not hasattr(env, 'needs_all_needs'):
# Used to store all needed information about all needs in document
env.needs_all_needs = {}
if not hasattr(env, 'needs_functions'):
# Used to store all registered functions for supporting dynamic need values.
env.needs_functions = {}
# needs_functions = getattr(app.config, 'needs_functions', [])
needs_functions = app.needs_functions
if needs_functions is None:
needs_functions = []
if not isinstance(needs_functions, list):
raise SphinxError(
'Config parameter needs_functions must be a list!')
# Register built-in functions
for need_common_func in needs_common_functions:
register_func(env, need_common_func)
# Register functions configured by user
for needs_func in needs_functions:
register_func(env, needs_func)
app.config.needs_hide_options += ['hidden']
app.config.needs_extra_options['hidden'] = directives.unchanged
if not hasattr(env, 'needs_workflow'):
# Used to store workflow status information for already executed tasks.
# Some tasks like backlink_creation need be be performed only once.
# But most sphinx-events get called several times (for each single document file), which would also
# execute our code several times...
env.needs_workflow = {
'backlink_creation': False,
'dynamic_values_resolved': False
}
def prepare_env(app, env, _docname):
"""
Prepares the sphinx environment to store sphinx-needs internal data.
"""
if not hasattr(env, "needs_all_needs"):
# Used to store all needed information about all needs in document
env.needs_all_needs = {}
if not hasattr(env, "needs_all_filters"):
# Used to store all needed information about all filters in document
env.needs_all_filters = {}
if not hasattr(env, "needs_services"):
# Used to store all needed information about all services
app.needs_services = ServiceManager(app)
# Register embedded services
app.needs_services.register("github-issues", GithubService, gh_type="issue")
app.needs_services.register("github-prs", GithubService, gh_type="pr")
app.needs_services.register("github-commits", GithubService, gh_type="commit")
# Register user defined services
for name, service in app.config.needs_services.items():
if name not in app.needs_services.services and "class" in service and "class_init" in service:
# We found a not yet registered service
# But only register, if service-config contains class and class_init.
# Otherwise the service may get registered later by an external sphinx-needs extension
app.needs_services.register(name, service["class"], **service["class_init"])
needs_functions = app.config.needs_functions
# Register built-in functions
for need_common_func in needs_common_functions:
register_func(need_common_func)
# Register functions configured by user
for needs_func in needs_functions:
register_func(needs_func)
# Own extra options
for option in ["hidden", "duration", "completion", "has_dead_links", "has_forbidden_dead_links"]:
# Check if not already set by user
# if option not in app.config.needs_extra_options:
# app.config.needs_extra_options[option] = directives.unchanged
if option not in NEEDS_CONFIG.get("extra_options"):
add_extra_option(app, option)
# The default link name. Must exist in all configurations. Therefore we set it here
# for the user.
common_links = []
link_types = app.config.needs_extra_links
basic_link_type_found = False
parent_needs_link_type_found = False
for link_type in link_types:
if link_type["option"] == "links":
basic_link_type_found = True
elif link_type["option"] == "parent_needs":
parent_needs_link_type_found = True
if not basic_link_type_found:
common_links.append(
{
"option": "links",
"outgoing": "links outgoing",
"incoming": "links incoming",
"copy": False,
"color": "#000000",
}
)
if not parent_needs_link_type_found:
common_links.append(
{
"option": "parent_needs",
"outgoing": "parent needs",
"incoming": "child needs",
"copy": False,
"color": "#333333",
}
)
app.config.needs_extra_links = common_links + app.config.needs_extra_links
app.config.needs_layouts = {**LAYOUTS, **app.config.needs_layouts}
app.config.needs_flow_configs.update(NEEDFLOW_CONFIG_DEFAULTS)
if not hasattr(env, "needs_workflow"):
# Used to store workflow status information for already executed tasks.
# Some tasks like backlink_creation need be be performed only once.
# But most sphinx-events get called several times (for each single document
# file), which would also execute our code several times...
env.needs_workflow = {
"backlink_creation_links": False,
"dynamic_values_resolved": False,
"needs_extended": False,
}
for link_type in app.config.needs_extra_links:
env.needs_workflow["backlink_creation_{}".format(link_type["option"])] = False
def prepare_env(app, env, docname):
"""
Prepares the sphinx environment to store sphinx-needs internal data.
"""
if not hasattr(env, 'needs_all_needs'):
# Used to store all needed information about all needs in document
env.needs_all_needs = {}
if not hasattr(env, 'needs_all_filters'):
# Used to store all needed information about all filters in document
env.needs_all_filters = {}
if not hasattr(env, 'needs_functions'):
# Used to store all registered functions for supporting dynamic need values.
env.needs_functions = {}
# needs_functions = getattr(app.config, 'needs_functions', [])
needs_functions = app.needs_functions
if needs_functions is None:
needs_functions = []
if not isinstance(needs_functions, list):
raise SphinxError(
'Config parameter needs_functions must be a list!')
# Register built-in functions
for need_common_func in needs_common_functions:
register_func(env, need_common_func)
# Register functions configured by user
for needs_func in needs_functions:
register_func(env, needs_func)
app.config.needs_hide_options += ['hidden']
app.config.needs_extra_options['hidden'] = directives.unchanged
# The default link name. Must exist in all configurations. Therefore we set it here for the user.
common_links = []
link_types = app.config.needs_extra_links
basic_link_type_found = False
for link_type in link_types:
if link_type['option'] == 'links':
basic_link_type_found = True
break
if not basic_link_type_found:
common_links.append({
'option': 'links',
'outgoing': 'links outgoing',
'incoming': 'link incoming',
'copy': False,
'color': '#000000'
})
app.config.needs_extra_links = common_links + app.config.needs_extra_links
if not hasattr(env, 'needs_workflow'):
# Used to store workflow status information for already executed tasks.
# Some tasks like backlink_creation need be be performed only once.
# But most sphinx-events get called several times (for each single document file), which would also
# execute our code several times...
env.needs_workflow = {
'backlink_creation_links': False,
'dynamic_values_resolved': False
}
for link_type in app.config.needs_extra_links:
env.needs_workflow['backlink_creation_{}'.format(
link_type['option'])] = False
def prepare_env(app, env, docname):
"""
Prepares the sphinx environment to store sphinx-needs internal data.
"""
NEEDS_FUNCTIONS.clear()
if not hasattr(env, 'needs_all_needs'):
# Used to store all needed information about all needs in document
env.needs_all_needs = {}
if not hasattr(env, 'needs_all_filters'):
# Used to store all needed information about all filters in document
env.needs_all_filters = {}
if not hasattr(env, 'needs_services'):
# Used to store all needed information about all services
app.needs_services = ServiceManager(app)
# Register embedded services
# env.needs_services.register('jira', JiraService)
app.needs_services.register('github-issues',
GithubService,
gh_type='issue')
app.needs_services.register('github-prs', GithubService, gh_type='pr')
app.needs_services.register('github-commits',
GithubService,
gh_type='commit')
# Register user defined services
for name, service in app.config.needs_services.items():
if name not in app.needs_services.services.keys():
# We found a not yet registered service
app.needs_services.register(name, service['class'],
**service['class_init'])
needs_functions = NEEDS_FUNCTIONS_CONF
if needs_functions is None:
needs_functions = []
if not isinstance(needs_functions, list):
raise SphinxError('Config parameter needs_functions must be a list!')
# Register built-in functions
for need_common_func in needs_common_functions:
register_func(need_common_func)
# Register functions configured by user
for needs_func in needs_functions:
register_func(needs_func)
# Own extra options
for option in ['hidden', 'duration', 'completion']:
# Check if not already set by user
if option not in app.config.needs_extra_options.keys():
app.config.needs_extra_options[option] = directives.unchanged
# The default link name. Must exist in all configurations. Therefore we set it here for the user.
common_links = []
link_types = app.config.needs_extra_links
basic_link_type_found = False
for link_type in link_types:
if link_type['option'] == 'links':
basic_link_type_found = True
break
if not basic_link_type_found:
common_links.append({
'option': 'links',
'outgoing': 'links outgoing',
'incoming': 'links incoming',
'copy': False,
'color': '#000000'
})
app.config.needs_extra_links = common_links + app.config.needs_extra_links
app.config.needs_layouts = {**LAYOUTS, **app.config.needs_layouts}
app.config.needs_flow_configs.update(NEEDFLOW_CONFIG_DEFAULTS)
if not hasattr(env, 'needs_workflow'):
# Used to store workflow status information for already executed tasks.
# Some tasks like backlink_creation need be be performed only once.
# But most sphinx-events get called several times (for each single document file), which would also
# execute our code several times...
env.needs_workflow = {
'backlink_creation_links': False,
'dynamic_values_resolved': False
}
for link_type in app.config.needs_extra_links:
env.needs_workflow['backlink_creation_{}'.format(
link_type['option'])] = False