needtable

New in version 0.2.0.

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

Example

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

Result

Example table

ID

Title

Status

Outgoing

req_001

My first requirement

S_503A1

Spec for a requirement

done

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

Options

Note

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

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.

Show example

Example

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

Result

ID

Title

Tags

R_F4722

My first requirement

requirement; test; awesome

T_C3893

Test for XY

test; user_interface; python27

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

ID

Title

Tags

Status

Docname

Lineno

Is External

Is Need

Is Part

Content

R_F4722

My first requirement

requirement; test; awesome

open

examples/index

106

False

True

False

This is my **first** requirement!! .. note:: You can use any rst code inside it :)

T_C3893

Test for XY

test; user_interface; python27

implemented

examples/index

126

False

True

False

This test checks :need:`IMPL_01` for :need:`OWN_ID_123` inside a Python 2.7 environment.

Normal style

ID

Title

Tags

Status

Docname

Lineno

Is External

Is Need

Is Part

Content

R_F4722

My first requirement

requirement; test; awesome

open

examples/index

106

False

True

False

This is my **first** requirement!! .. note:: You can use any rst code inside it :)

T_C3893

Test for XY

test; user_interface; python27

implemented

examples/index

126

False

True

False

This test checks :need:`IMPL_01` for :need:`OWN_ID_123` inside a Python 2.7 environment.

colwidths

New in version 0.7.4.

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

ID

Title

Status

R_F4722

My first requirement

open

T_C3893

Test for XY

implemented

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.

Show example

Example

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

Result

ID

Headline

Labels

R_F4722

My first requirement

requirement; test; awesome

T_C3893

Test for XY

test; user_interface; python27

show_filters

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

Show example

Example

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

Result

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 you to set a specific style for the current table.

Supported values are:

  • table

  • datatables

Overrides config parameter needs_table_style if set.

Show example

Example

.. needtable::
   :style: table

.. needtable::
   :style: datatables

Table with :style: table:

Result

ID

Title

Status

Outgoing

EX_REQ_2

A more complex and highlighted requirement

open

GH_166

Fails to build PDF when 'req' directive contains nested directives

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

GH_166

Fails to build PDF when 'req' directive contains nested directives

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.

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

ID

Title

Outgoing

Incoming

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 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 ../_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.

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

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

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

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.

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.

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, we set the sort option to status. 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 only works if you use the standard sphinx-table for output: :style: table. By default, tables generated with DatabTables uses Javascript to sort results.

class

New in version 0.7.4.

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

ID

Title

Status

R_F4722

My first requirement

open

T_C3893

Test for XY

implemented

common filters