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
ID |
Title |
Status |
Outgoing |
---|---|---|---|
My first requirement |
|||
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
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 |
---|---|---|---|---|---|---|---|---|---|
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 :) |
|
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 |
---|---|---|---|---|---|---|---|---|---|
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 :) |
|
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
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
show_filters¶
If set, we add the used filter above the table:
Show example
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 |
---|---|---|---|
A more complex and highlighted requirement |
open |
||
Issue with sphinxneeds directives during latexpdf build |
open |
||
My first requirement |
open |
||
Content of each need |
open |
Table with :style: datatables
:
ID |
Title |
Status |
Outgoing |
---|---|---|---|
A more complex and highlighted requirement |
open |
||
Issue with sphinxneeds directives during latexpdf build |
open |
||
My first requirement |
open |
||
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 |
---|---|---|---|
Test need with need parts |
|||
→ Part 1 of requirement |
|||
→ Part 2 of requirement |
|||
→ Part 3 of requirement |
|||
Specifies part 1 |
|||
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
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 |
---|---|---|---|
Implemented spec |
implemented |
||
Not implemented spec |
open |
||
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 |
---|---|---|
Implemented spec |
implemented |
|
Not implemented spec |
open |
|
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
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 |
---|---|---|---|
Implemented spec |
implemented |
||
Not implemented spec |
open |
||
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 |
---|---|---|---|
Implemented spec |
implemented |
||
Spec under progress |
in progress |
||
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