Skip to content
Back to top
View this page
Edit this page

# needservice

Added in version 0.6.0.

`needservice` allows the import of data from external services like GitHub, for 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 items 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, for 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.

Tip

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

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