needlist

Added in version 0.2.0.

needlist creates a list of elements based on the result of given filters.

Example 1

.. needlist::
   :tags: main_example

No needs passed the filters

Options

Note

needlist supports the full filtering possibilities of Sphinx-Needs. Please see Filtering needs for more information.

Some further options are accepted only for ubCode compatibility, and are otherwise ignored.

show_status

Flag for adding status information to the needs list results filtered.

If a filtered need has no status information, we write no status output for the need.

Example 2

.. needlist::
   :show_status:
   :status: done; implemented

show_tags

Flag for adding tag information to the needs list results filtered.

If a filtered need has no tag information, we write no tag output for the need.

Example 3

.. needlist::
   :show_tags:
   :status: done; implemented

show_filters

If set, we add the used filter below the needlist results:

Example 4

.. needlist::
   :show_filters:
   :status: done; implemented

Used filter: status(done OR implemented)

max_items

Added in version 8.4.0.

The maximum number of needs to show.

We apply the limit after filtering and sorting, so the list keeps the first needs it would otherwise have shown, and tells the reader how many needs it is hiding. A truncated view says so in the page and emits a needs.max_items warning, so that a build does not have to be read page by page to find it; a project that caps deliberately can silence the warning with suppress_warnings = ["needs.max_items"]. The limit counts the entries the filter returned, which are needs and need parts alike.

:max_items: 0 means no limit, also for a project that sets needs_views_max_items. Without the option, the list shows as many needs as that configuration allows.

Example 5

.. needlist::
   :tags: flow_example
   :max_items: 2

Showing the first 2 of 7 needs; refine the filter or set :max_items: (0 for all).

common filters