needtable¶

needtable generates a table, based on the result of given filters.

Example

.. needtable:: Example table
   :tags: main_example
   :style: table

Result

We use the argument of a needtable as caption for the table.

Options¶

columns¶

A comma/semicolon separated string used to define the position of specific columns. For instance:

.. needtable::
   :columns: id;title;tags

This will show the columns id, title and tags in the order given.

.. needtable::
   :columns: id;title;tags

You can set all options of a need (incl. needs_extra_options) as a column. This also includes internal options like docname (Use :layout: debug on a need for a complete list)

If you set :columns:, the current table will not use the value of config parameter needs_table_columns.

Tables with a lot of columns will get a horizontal scrollbar in HTML output.

DataTable style

Normal style

colwidths¶

A comma separated list of lengths or percentages used to define the width of each column.

It has the same meaning as the width options of listtable directive.

Example

.. needtable::
   :tags: test
   :columns: id,title,status
   :colwidths: 50,40,10
   :style: table

Result

Custom column titles¶

You can customize each column title by following this syntax for its definition: OPTION as "My custom title". The characters , or ; are not allowed.

.. needtable::
  :tags: test
  :columns: id;title as "Headline"; tags as "Labels"
  :style: table

show_filters¶

If set, we add the used filter above the table:

.. needtable::
   :tags: test
   :columns: id;title;tags
   :show_filters:
   :style: table

style¶

Allows you to set a specific style for the current table.

Supported values are:

• table

• datatables

Overrides config parameter needs_table_style if set.

.. needtable::
   :style: table

.. needtable::
   :style: datatables

show_parts¶

Adds an extra table row for each need_part / np found inside a filtered need.

It adds the part rows directly under the related need’s row, and their id and title get a prefix.

To change the prefix please read needs_part_prefix.

Example

Show above example’s configuration

.. req:: Test need with need parts
   :id: table_001

   :np:`(1) Part 1 of requirement`.

   :np:`(2) Part 2 of requirement`.

   :np:`(3) Part 3 of requirement`.

.. spec:: Specifies part 1
   :id: table_002
   :links: table_001.1

.. spec:: Specifies part 2
   :id: table_003
   :links: table_001.2

.. needtable::
   :filter: is_need
   :show_parts:
   :columns: id;title;outgoing;incoming
   :style: table

Requirement: Test need with need parts table_001

tags: test_table links incoming: table_002, table_003

Part 1 of requirement 1. Part 2 of requirement 2. Part 3 of requirement 3.

Specification: Specifies part 1 table_002

tags: test_table links outgoing: table_001.1

Specification: Specifies part 2 table_003

tags: test_table links outgoing: table_001.2

style_row¶

You can use the style_row option to set a specific class-attribute for the table-row representation and use CSS to select the class-attribute

Also, you can set specific layout for the row.

Example

.. needtable::
   :tags: ex_row_color
   :style_row: needs_blue_border

Result

Row style based on specific need value¶

You can use Dynamic functions to derive the value for style_row based on a specific value of the documented need in the row.

Example

In this example we set style_row to needs_[[copy("status")]], so the status of each need will be part of the row style.

Show used configuration

needtable

.. needtable::
   :tags: ex_row_color
   :columns: id, title, status
   :style_row: needs_[[copy("status")]]

needs as input

Requirement: Implemented spec EX_ROW_1

status: implemented tags: ex_row_color

Requirement: Not implemented spec EX_ROW_2

status: open tags: ex_row_color

Requirement: Spec under progress EX_ROW_3

status: in progress tags: ex_row_color

inside a provided css file

tr.needs_implemented {
 background-color: palegreen !important;
}

tr.needs_open {
    background-color: palevioletred !important;
}

tr.needs_in_progress {
    background-color: palegoldenrod !important;
}

/* This sets values for the status column */
tr.needs_in_progress td.needs_status p {
    background-color: #1b6082;
    padding: 3px 5px;
    text-align: center;
    border-radius: 10px;
    border: 1px solid #212174;
    color: #ffffff;
}

sort¶

Option to sort the filtered-results based on a key.

The sort-value must be compatible with the options supported by the Filter string, and the addressed need-value must have the type string, float or int.

Example

By default, we use id_complete if we don’t set a sort option.

In this case, we set the sort option to status. So EX_ROW_3 is above of EX_ROW_2.

.. needtable::
   :tags: ex_row_color
   :style: table

.. needtable::
   :tags: ex_row_color
   :style: table
   :sort: status

class¶

You can set additional class-names for a needtable using the class option. Mostly used for HTML output. It supports comma separated values and will add classes to the already set classes by Sphinx-Needs.

Example

rst file:

.. needtable::
   :tags: test
   :columns: id,title,status
   :style: table
   :class: class_red_border

custom css file:

table.class_red_border {
    border: 3px solid red;
}

Result

common filters¶

• status

• tags

• types

• filter