Layouts & Styles

Sphinx-Needs provides functions to manipulate the layout and the style of a need.

Layouts are defined by a preconfigured table grid and the data, which shall be shown inside specific grid cells. Styles define mostly the color of a need.

Both features can be set directly during need-configuration or inside the sphinx file.

Sphinx-Needs provides some preconfigured, ready-to-use standard layouts:

  • clean
  • complete
  • focus


Layouts are using a predefined grid system and define which data shall be shown in which grid-cells.

There can be multiple layouts using the same grid system, but maybe showing different data. E.g. a layout for bugs and one for specifications.

Sphinx-Needs comes with some predefined layouts. But the user is free to create own layouts and use only them.

Most useful layouts are:

Layout Used grid Comment
clean simple The standard Sphinx-Needs layout
complete complex Divided head, meta, footer rows. Showing really all user-added data.
focus content Content focused layout. Showing content only. Nothing more.


Requirement: CLEAN layout EX_CLEAN _images/arrow-right-circle.svg
status: open
tags: a, b, c, example
layout: clean
links outgoing: EX_COMPLETE, EX_FOCUS
links incoming: EX_COMPLETE, EX_FOCUS
This is a need using CLEAN layout.
status: open
tags: a, b, c, example
links outgoing: EX_CLEAN, EX_FOCUS
links incoming: EX_CLEAN, EX_FOCUS
This is a need using COMPLETE layout.
This is a need using FOCUS layout. The same meta is set as the two needs above.

There are also some extensions for the layouts above available:

Layout Used grid Comment
clean_l simple_side_left Like clean but with an extra side element on left side
clean_r simple_side_right Like clean but with an extra side element on right side
clean_lp simple_side_left_partial Like clean but with an extra, small side element on left side
clean_rp simple_side_right_partial Like clean but with an extra, small side element on right side
focus_f content_footer Adds a small footer below content with the need id.
focus_l content_side_left Adds a small footer to the left side of content, showing the need id.
focus_r content_side_right Adds a small footer to the right side of content, showing the need id.

The layouts clean_l, clean_r, clean_lp and clean_rp are using the value from the field image as source for the image in the side element. This field must made available via needs_extra_options. If you need another field as source, you must create your own layout.


Requirement: CLEAN_L layout EX_CLEAN_L
status: open
tags: a, b, c, example
layout: clean_l
image: _images/needs_logo.png
This is a need using CLEAN_L layout.
Requirement: CLEAN_R layout EX_CLEAN_R
status: open
tags: a, b, c, example
layout: clean_r
image: _images/needs_logo.png
This is a need using CLEAN_R layout.
Requirement: CLEAN_LP layout EX_CLEAN_LP
status: open
tags: a, b, c, example
layout: clean_lp
image: _images/needs_logo.png
This is a need using CLEAN_LP layout.
Requirement: CLEAN_RP layout EX_CLEAN_RP
status: open
tags: a, b, c, example
layout: clean_rp
image: _images/needs_logo.png
This is a need using CLEAN_RP layout.
This is a need using FOCUS_L layout.
This is a need using FOCUS_R layout.

Special layouts:

Layout Used grid Comment
debug content_footer Shows all meta data (also internal ones). Useful do see what data is available for a need and which can be used in Filter string.


Debug view off
docname: layout_styles
lineno: 202
target_node: <target refid="EX_DEBUG"/>
content_node: <Need classes="need need-req" ids="EX_DEBUG"><paragraph>This is a need using <strong>DEBUG layout</strong>.</paragraph></Need>
type: req
type_name: Requirement
type_prefix: R_
type_color: #BFD8D2
type_style: node
status: open
tags: a, b, c, example
title: DEBUG layout
full_title: DEBUG layout
content: This is a need using **DEBUG layout**.
layout: debug
hide: False
parts: {}
is_part: False
is_need: True
sections: Layouts, Layouts & Styles
section_name: Layouts
id_parent: EX_DEBUG
id_complete: EX_DEBUG
This is a need using DEBUG layout.

Using layouts

There are two ways of setting a layout for a need:

Set it globally via needs_default_layout in your file:

needs_default_layout = 'complete'

Or set it locally for each need by using layout option:

.. req:: My requirement
   :layout: complete

Defining own layouts

Own layouts can be defined by using the the config parameter needs_layouts in your file.

needs_layouts must be a dictionary and each key represents a layout. A layout must define the used grid-system and a layout-structure. Example:

needs_layouts = {
    'my_layout': {
        'grid': 'simple',
        'layout': {
            'head': ['my custom head']
            'meta': [ 'my first meta line',
                      'my second meta line']

The layout-structure must also be a dictionary, where each key reference an area in the used grid system. By default these can be: head, meta, footer and more. If the layout-structure is using a not supported key by the current grid-system, the entry gets ignored. E.g. grid simple is not supporting footer area.

The values of a specific layout-structure area definition must be a list, where each entry must be a string and represents a single line in the later need representation. This line can contain Layout functions, which care about getting need-data or adding links.


Sphinx-Needs provides some default layouts. These layouts can not be overwritten. See layout list for more information.


The content area of a grid can not be overwritten. It is always there and can’t be changed or replaced.

Layout line

A layout line may look like this:

**style**: my_<<meta('status')>>_style

This line contains:

  • a rst text, which supports common inline roles (bold, italic): **style**: _my_
  • a layout function, which gets executed and returns a string: <<meta('status')>>
  • another rst text: _style

When executed, the line will result in the following for a status like open:

style: my_open_style

You can combine as many Layout functions and text elements as you want for a line.

The head-line for the default Sphinx-Needs layout clean looks like this:

<<meta("type_name")>>: **<<meta("title")>>** <<meta_id()>>  <<collapse_button("meta", collapsed="icon:arrow-down-circle", visible="icon:arrow-right-circle", initial=False)>>

You are free to surround a layout function with a rst role. Like **<<meta("title")>>** to get a bold printed title.

Sometimes an argument for a layout function shall be based on a given need option. In this cases the option name can be surrounded by {{ .. }}. As example, there may be an author option in a bug-need and you want to show a picture of the author in the grid simple_side_right_partial.

The line for the side area could look like:

'<<image("_images/{{author}}.png", align="center")>>'
My test spec for daniel
status: open
author: daniel

This example shows an image based on the author option.

The used layout takes the value from author and puts some image-path related information around it.

Here is the complete used code:

# -------

from docutils.parsers.rst import directives
# Make the author option valid
needs_extra_options = {
      "author": directives.unchanged,

# Define own layout
needs_layouts = {
    'example': {
        'grid': 'simple_side_right_partial',
        'layout': {
            'head': ['**<<meta("title")>>** for *<<meta("author")>>*'],
            'meta': ['**status**: <<meta("status")>>',
                     '**author**: <<meta("author")>>'],
            'side': ['<<image("_images/{{author}}.png", align="center")>>']

# rst-code of the above need
# --------------------------

.. spec:: My test spec
   :author: daniel
   :status: open
   :layout: example
   :tags: example
   :style: yellow, blue_border

Layout functions

To get custom data into your layout the usage of layout function is needed. A layout function may look like <<meta(arg1, arg2, kwarg=data)>>

Available layout functions are:

meta(name, prefix=None, show_empty=False)

Returns the specific meta data of a need inside docutils nodes. Usage:

<<meta('status', prefix='**status**', show_empty=True)>>
  • name – name of the need item
  • prefix – string as rst-code, will be added infront of the value output
  • show_empty – If false and requested need-value is None or ‘’, no output is returned. Default: false

docutils node


Returns the current need id as clickable and linked reference.


Returns:docutils node
meta_all(prefix='', postfix='', exclude=None, no_links=False, defaults=True, show_empty=False)

meta_all() excludes by default the output of: docname, lineno, target_node, refid, content, collapse, parts, id_parent, id_complete, title, full_title, is_part, is_need, type_prefix, type_color, type_style, type, type_name, id, hide, hide_status, hide_tags, sections, section_name.

To exclude further need-data, use exclude, like exclude=['status', 'tags']

To exclude nothing, set defaults to False.


<<meta_all(prefix='\*\*', postix='\*\*', no_links=True)>>


You must escape all rst_content in your function strings! E.g. to get ** one must use \*\*.

  • prefix
  • postfix
  • exclude – List of value names, which are excluded from output
  • no_links – excludes all incoming and outgoing extra link types from output
  • defaults – If True, default excludes are added. This filters out all internal data, which is normally not relevant for the user.
  • show_empty – If true, also need data with no value will be printed. Mostly useful for debugging.

docutils nodes

Documents the set links of a given link type. The documented links are all full clickable links to the target needs.

  • name – link type name
  • incoming – If False, outcoming links get documented. Use True for incoming

docutils nodes

Documents all used link types for the current need automatically.

  • prefix – prefix string
  • postfix – postfix string
  • exclude – list of extra link type names, which are excluded from output

docutils nodes

image(url, height=None, width=None, align=None, no_link=False)


If url starts with icon: the following string is taken is icon-name and the related icon is shown. Example: icon:activity will show:


For all icons, see


'<<image("_images/useblocks_logo.png", height="50px", align="center")>>',
'<<image("icon:bell", height="20px", align="center")>>'
'<<image("field:url", height="60px", align="center")>>'  # Get url from need['url']
  • no_link
  • url
  • height
  • width
  • align
  • prefix – Prefix string infront of the image
  • is_external – If True url references an external image, which needs to be downloaded

Shows a link. Link can be a text, an image or both

  • url
  • text
  • image_url
  • image_height
  • image_width
  • prefix – Additional string infront of the string
  • is_dynamic – if True, url is not static and gets read from need


<<link('', 'Sphinx')>>
<<link('url', 'Link', is_dynamic=True)>>  # Reads url from need[url]
collapse_button(target='meta', collapsed='Show', visible='Close', initial=False)

To show icons instead of text on the button, use collapse_button() like this:

<<collapse_button("icon:arrow-down-circle", visible="icon:arrow-right-circle", initial=False)>>

For the builders latex and latexpdf no output is returned, as their build results are really static and collapse-feature can not be implemented..

  • target – css_name of row to collapse. Default is meta
  • collapsed – Text or image/icon string to show when target rows are collapsed
  • visible – Text or image/icon string to show when target rows are visible
  • initial – If True, initial status will hide rows after loading page.

docutils nodes


Styles handle mostly colors for background, border and co. for a need. Their definition is done in css files, so that Sphinx-Needs only cares about setting the correct class in HTML output. This also means that styles do not have any impact to the need design in PDFs and other output formats.

Default styles are:

green or implemented Green background
red or open Red background
yellow or in_progress Yellow background
blue Blue background
discreet Background color is only a little bit lighter/darker as the page background
green_border Green border, but normal background
red_border Red border, but normal background
yellow_border Yellow border, but normal background
blue_border Blue border, but normal background
discreet_border Border color is only a little bit lighter/darker as the page background
clean Removes all style information. Looks like normal text. Mostly used with layout focus.


Requirement: Green background EX_STYLE_GREEN _images/arrow-right-circle.svg
tags: example
style: green
Requirement: Red background EX_STYLE_RED _images/arrow-right-circle.svg
tags: example
style: red
Requirement: Yellow background EX_STYLE_YELLOW _images/arrow-right-circle.svg
tags: example
style: yellow
Requirement: Blue background EX_STYLE_BLUE _images/arrow-right-circle.svg
tags: example
style: blue
Requirement: Discreet background EX_STYLE_DISCREET _images/arrow-right-circle.svg
tags: example
style: discreet
Requirement: Clean style EX_STYLE_CLEAN _images/arrow-right-circle.svg
tags: example
style: clean
Requirement: Green border EX_STYLE_GREEN_BORDER _images/arrow-right-circle.svg
tags: example
style: green_border
Requirement: Red border EX_STYLE_RED_BORDER _images/arrow-right-circle.svg
tags: example
style: red_border
Requirement: Yellow border EX_STYLE_YELLOW_BORDER _images/arrow-right-circle.svg
tags: example
style: yellow_border
Requirement: Blue border EX_STYLE_BLUE_BORDER _images/arrow-right-circle.svg
tags: example
style: blue_border
Requirement: Discreet border EX_STYLE_DISCREET_BORDER _images/arrow-right-circle.svg
tags: example
style: discreet_border

Different styles can also be combined by setting a comma-separated string: yellow, red_border.

Requirement: Yellow background + Red border EX_STYLE_YELLOW_RED _images/arrow-right-circle.svg
tags: example
style: yellow, red_border
Requirement: Discreet view EX_STYLE_DISCREET_COMBI _images/arrow-right-circle.svg
tags: example
style: discreet, discreet_border

Using styles

There are two ways of setting a style for a need:

Set it globally via needs_default_style in your file:

needs_default_style = 'red'

Or set it locally for each need by using style option:

.. req:: My requirement
   :style: red

By setting a style to None, no style is set and the normal Sphinx-Needs style is used.

Own style configuration

If you need to customize the css definitions, there are twi ways of doing it:

  • Provide a css file by using needs_css
  • Set own css on sphinx level

Sphinx-needs CSS option

A css file can be set in the file by setting needs_css. See needs_css on the configuration page for more information.

Sphinx-needs provides the following css styles:







Own CSS file on sphinx level

If you want to use most of the sphinx-needs internal styles but only need some specific changes for single elements, you can provide your own CSS file by register it inside your

def setup(app):
    app.add_stylesheet('css/my_custom.css')  # may also be an URL


Do not name it custom.css if you are using Read the docs as this name is already taken.

HTML output

For html output the used layout and style names are added as css-class to the need table object. Beside this also the used grid system is added:

<table class="need needs_grid_simple needs_layout_complex needes_style_blue docutils" id="SPEC_1">

The above line contains the following css classes:

  • need: Each html table, which represents a need has the need class
  • needs_grid_simple: Used grid system of the layout
  • needs_layout_complex: Used layout
  • needs_style_needs_blue: Used style

Please note, that the classes added by Sphinx-Needs always contain a prefix: needs_grid_, needs_layout_, needs_style_. So if a user defined layout has the name specification_layout, the related css class is needs_layout_specification_layout


The following grids are available.

Simple grids


This is the default layout used by Sphinx-Needs.



side head


head side


side head


head side

Complex grids


head_left head head_right
meta_left meta_right
footer_left footer footer_right

Content focused grids




side content


content side