needservice

New in version 0.6.0.

needservice allows the import of data from external services like GitHub.

Example

.. needservice:: <service>
   :option: ...
   :status: open
   :tags: awesome, nice
   :author: me

   Extra content for each new need

In most cases, the service fetches requested data from an external server and creates a need object for each found data-element in the returned data.

These need objects can then be used and referenced as all other need objects, e.g. by filtering them via needtable.

Hint

For details about available services and their specific configuration please take a look into Services.

Options

Each service can define custom options which may be needed for the service to work correctly. Please take a look into the related service documentation to find out what is needed.

Hint

needservice supports all options available for the need / req (or any other defined need type) directive and all custom options defined by needs_extra_options.

For services provided by Sphinx-Needs please take a look into Services.

debug

Set debug to get debug-output of the needservice only. No needs will be created.

Useful to understand the return values of services or to figure out, why a connection can not be established.

Example

.. needservice:: <service>
   :debug:

Content

The content of needservice is used as content for all created need objects.

A service may deviate from this behavior and define its own usage. For example, by awaiting a json-string with a more complex configuration or by just ignoring the content.

Please take a look into the related service documentation for more information.

GitHub Issues Example

This example is using the github-issues service. For details, please take a look into its specific documentation under GitHub services.

The service queries GitHub for issues in the Sphinx-Needs repository that have node and latexpdf in their content.

Example

.. needservice:: github-issues
   :query: repo:useblocks/sphinx-needs node latexpdf
   :max_content_lines: 4
   :id_prefix: EXAMPLE_

Click the small arrow under the need id to see all meta data.

Result

Issue with sphinxneeds directives during latexpdf build (url)
../_images/129397637.png
DirkBodenschatz
user: DirkBodenschatz
created_at: 2023-03-30T12:55:00Z
updated_at: 2023-04-06T21:08:44Z
closed_at: None
service: github-issues
url: Link
type: Issue
status: open
delete: False
jinja_content: False
latexpdf build leads to an exception if I use `..
needextract::` is used. The same happens also if `..
needtable::` is used

The html build works fine .....

```

Traceback (most recent call last):

  File "/usr/local/lib/python3.10/site-
packages/sphinx/events.py", line 94, in emit

    results.append(listener.handler(self.app, *args))

  File "/usr/local/lib/python3.10/site-
packages/sphinx_needs/directives/need.py", line 394, in
process_need_nodes

    print_need_nodes(app, doctree, fromdocname,
found_needs_nodes)

  File "/usr/local/lib/python3.10/site-
packages/sphinx_needs/directives/need.py", line 423, in
print_need_nodes

    build_need(layout, node_need, app,
fromdocname=fromdocname)

  File "/usr/local/lib/python3.10/site-
packages/sphinx_needs/layout.py", line 157, in build_need

    new_need_node = lh.get_need_table()

  File "/usr/local/lib/python3.10/site-
packages/sphinx_needs/layout.py", line 317, in
get_need_table

    func["func"](**func["configs"])

  File "/usr/local/lib/python3.10/site-
packages/sphinx_needs/layout.py", line 1081, in _grid_simple

    head_entry += self.get_section("head")

  File "/usr/local/lib/python3.10/site-
packages/sphinx_needs/layout.py", line 339, in get_section

    line_ready = self._func_replace(line_parsed)

  File "/usr/local/lib/python3.10/site-
packages/sphinx_needs/layout.py", line 438, in _func_replace

    result = func(*func_args, **func_kargs)

  File "/usr/local/lib/python3.10/site-
packages/sphinx_needs/layout.py", line 563, in meta_id

    id_ref = make_refnode(

  File "/usr/local/lib/python3.10/site-
packages/sphinx/util/nodes.py", line 561, in make_refnode

    node['refuri'] = (builder.get_relative_uri(fromdocname,
todocname) +

  File "/usr/local/lib/python3.10/site-
packages/sphinx/builders/latex/__init__.py", line 138, in
get_relative_uri

    return self.get_target_uri(to, typ)

  File "/usr/local/lib/python3.10/site-
packages/sphinx/builders/latex/__init__.py", line 132, in
get_target_uri

    raise NoUri(docname, typ)

sphinx.errors.NoUri: ('xxxxxx', None)

The above exception was the direct cause of the following
exception:

Traceback (most recent call last):

  File "/usr/local/lib/python3.10/site-
packages/sphinx/cmd/build.py", line 281, in build_main

    app.build(args.force_all, args.filenames)

  File "/usr/local/lib/python3.10/site-
packages/sphinx/application.py", line 347, in build

    self.builder.build_update()

  File "/usr/local/lib/python3.10/site-
packages/sphinx/builders/__init__.py", line 307, in
build_update

    self.build(['__all__'], to_build)

  File "/usr/local/lib/python3.10/site-
packages/sphinx/builders/__init__.py", line 376, in build

    self.write(docnames, list(updated_docnames), method)

  File "/usr/local/lib/python3.10/site-
packages/sphinx/builders/latex/__init__.py", line 285, in
write

    doctree = self.assemble_doctree(

  File "/usr/local/lib/python3.10/site-
packages/sphinx/builders/latex/__init__.py", line 349, in
assemble_doctree

    self.env.resolve_references(largetree, indexfile, self)

  File "/usr/local/lib/python3.10/site-
packages/sphinx_monkeypatch/__init__.py", line 173, in
_resolve_references

    self.apply_post_transforms(doctree, fromdocname)

  File "/usr/local/lib/python3.10/site-
packages/sphinx/environment/__init__.py", line 642, in
apply_post_transforms

    self.events.emit('doctree-resolved', doctree, docname)

  File "/usr/local/lib/python3.10/site-
packages/sphinx/events.py", line 94, in emit

    results.append(listener.handler(self.app, *args))

  File "/usr/local/lib/python3.10/site-
packages/sphinx_needs/needs.py", line 417, in process_caller

    check_func(app, doctree, fromdocname,
current_nodes[check_node])

  File "/usr/local/lib/python3.10/site-
packages/sphinx_needs/directives/needextract.py", line 126,
in process_needextract

    need_extract = create_need(

  File "/usr/local/lib/python3.10/site-
packages/sphinx_needs/layout.py", line 80, in create_need

    env.resolve_references(node_container, docname,
env.app.builder)

  File "/usr/local/lib/python3.10/site-
packages/sphinx_monkeypatch/__init__.py", line 173, in
_resolve_references

    self.apply_post_transforms(doctree, fromdocname)

  File "/usr/local/lib/python3.10/site-
packages/sphinx/environment/__init__.py", line 642, in
apply_post_transforms

    self.events.emit('doctree-resolved', doctree, docname)

  File "/usr/local/lib/python3.10/site-
packages/sphinx/events.py", line 105, in emit

    raise ExtensionError(__("Handler %r for event %r threw
an exception") %

sphinx.errors.ExtensionError: Handler <function
process_need_nodes at 0x7f09ceace5f0> for event 'doctree-
resolved' threw an exception (exception: ('xxxxxxx', None))

Extension error (sphinx_needs.directives.need):

Handler <function process_need_nodes at 0x7f09ceace5f0> for
event 'doctree-resolved' threw an exception (exception:
('xxxxxxx', None))

make: *** [Makefile:31: latexpdf] Error 1

 *  The terminal process "/bin/sh '-c', 'make latexpdf'"
terminated with exit code: 2.

 *  Terminal will be reused by tasks, press any key to close
it.

 ```