needtable

New in version 0.2.0.

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

.. needtable::
   :tags: main_example
   :style: table
ID Title Status Outgoing
req_001 My first requirement
S_503A1 Spec for a requirement done

Options

Note

needtable supports the full filtering possibilities of sphinx-needs. Please see Filtering needs for more information.

Supported options:

columns

Needs a comma/semicolon separated string, which is 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 given order.

Show example
.. needtable::
   :columns: id;title;tags
ID Title Tags
R_F4722 My first requirement requirement; test; awesome
T_C3893 Test for XY test; user_interface; python27

Supported columns are:

  • id
  • title
  • type
  • status
  • tags
  • incoming
  • outgoing

If :columns: is set, the value of config parameter needs_table_columns is not used for the current table.

show_filters

If set, the used filter is added in front of the table:

.. needtable::
   :show_filters:
Show example
.. needtable::
   :tags: test
   :show_filters:

Used filter: tags(test)

ID Title Tags
R_F4722 My first requirement requirement; test; awesome
T_C3893 Test for XY test; user_interface; python27

style

Allows to set a specific style for the current table.

Supported values are:

  • table
  • datatables

Overrides config parameter needs_table_style if set.

Show example
.. needtable::
   :style: table

.. needtable::
   :style: datatables

Table with :style: table:

ID Title Status Outgoing
EX_REQ_2 A more complex and highlighted requirement open
R_F4722 My first requirement open
SPEC_1 Content of each need open

Table with :style: datatables:

ID Title Status Outgoing
EX_REQ_2 A more complex and highlighted requirement open
R_F4722 My first requirement open
SPEC_1 Content of each need open

show_parts

New in version 0.3.6.

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

The part rows are added directly under the related need rows and their id and title get a prefix.

To change the prefix please read needs_part_prefix.

ID Title Outgoing Incoming
→ table_001.1 →  Part 1 of requirement
→ table_001.2 →  Part 2 of requirement
→ table_001.3 →  Part 3 of requirement
table_001 Test need with need parts
→ table_001.1 →  Part 1 of requirement
→ table_001.2 →  Part 2 of requirement
→ table_001.3 →  Part 3 of requirement
table_002 Specifies part 1
table_003 Specifies part 2
Show example 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::
   :show_parts:
   :columns: id;title;outgoing;incoming
   :style: table
Requirement: Test need with need parts table_001 ../_images/arrow-right-circle.svg
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 ../_images/arrow-right-circle.svg
tags: test_table
links outgoing: table_001.1
 
Specification: Specifies part 2 table_003 ../_images/arrow-right-circle.svg
tags: test_table
links outgoing: table_001.2
 

style_row

New in version 0.4.1.

style_row can be used to set a specific class-attribute for the table-row representation.

The class-attribute can then be addressed by css and specific layout can be set for the row.

ID Title Status Outgoing
EX_ROW_1 Implemented spec implemented
EX_ROW_2 Not implemented spec open
EX_ROW_3 Spec under progress in progress
Show used configuration
.. needtable::
   :tags: ex_row_color
   :style_row: needs_green

Row style based on specific need value

Dynamic functions can be used to calculate a value for style_row based on a specific value of the documented need in the row.

ID Title Status
EX_ROW_1 Implemented spec implemented
EX_ROW_2 Not implemented spec open
EX_ROW_3 Spec under progress in progress

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

Note

If style_row contains whitespaces, they get automatically replaced by _ to get a valid css class name.

So a copied status value like in progress will become in_progress.

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 ../_images/arrow-right-circle.svg
status: implemented
tags: ex_row_color
 
Requirement: Not implemented spec EX_ROW_2 ../_images/arrow-right-circle.svg
status: open
tags: ex_row_color
 
Requirement: Spec under progress EX_ROW_3 ../_images/arrow-right-circle.svg
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

New in version 0.4.3.

.. needtable:: provides a sort option to sort the filter-results for a given key.

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

If no sort option is given, id is used by default:

ID Title Status Outgoing
EX_ROW_1 Implemented spec implemented
EX_ROW_2 Not implemented spec open
EX_ROW_3 Spec under progress in progress

In this case, status is given for sort. So EX_ROW_3 is above of EX_ROW_2.

ID Title Status Outgoing
EX_ROW_1 Implemented spec implemented
EX_ROW_3 Spec under progress in progress
EX_ROW_2 Not implemented spec open
Show used configuration
.. needtable::
   :tags: ex_row_color
   :style: table

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

Note

Sorting may only work if the standard sphinx-table is used for output: :style: table. The default DatabTables table uses Javascript to sort results by its own.