Installation

Using pip

pip install sphinx-needs

If you wish to also use the plotting features of sphinx-needs (see needbar and needpie), you need to also install matplotlib, which is available via the plotting extra:

pip install sphinx-needs[plotting]

Note

Prior to version 1.0.1 the package was named sphinxcontrib-needs.

Using sources

git clone https://github.com/useblocks/sphinx-needs
cd sphinx-needs
pip install .

Activation

For final activation, please add sphinx_needs to the project’s extension list of your conf.py file.

extensions = ["sphinx_needs",]

For the full configuration, please read Configuration.

HTML Theme support

To represent needs and data tables within HTML builds, sphinx-needs injects some CSS styles into the pages.

This CSS is designed to be generally compatible with common Sphinx themes, but may require some adjustments depending on the theme you use. In particular, CSS Variables are used to specify the coloring of most components. The default values are as follows (see also needs_css):

Default CSS Variables
/* Colors based on https://flatuicolors.com/palette/se */

:root {
    --sn-color-bg-gray: #eee;
    --sn-color-bg-lightgray: rgba(0,0,0,0.004);
    --sn-color-bg-green: #05c46b;
    --sn-color-bg-red: #ff3f34;
    --sn-color-bg-yellow: #ffc048;
    --sn-color-bg-blue: #0fbcf9;

    --sn-color-border-lightgray: rgba(0,0,0,0.05);
    --sn-color-border-green: #05c46b;
    --sn-color-border-red: #ff3f34;
    --sn-color-border-yellow: #ffc048;
    --sn-color-border-blue: #0fbcf9;

    --sn-color-bar-green: #05c46b;
    --sn-color-bar-red: #ff3f34;
    --sn-color-bar-yellow: #ffc048;
    --sn-color-bar-orange: #e67e22;
    --sn-color-bar-blue: #0fbcf9;

    --sn-color-need-border: #555;
    --sn-color-need-row-border: hsla(232,75%,95%,0.12);
    --sn-color-need-bg: #eee;
    --sn-color-need-bg-head: rgba(0,0,0,0.1);

    --sn-color-complete-bg-head: rgba(0,0,0,0.1);
    --sn-color-complete-bg-foot: rgba(0,0,0,0.1);

    --sn-color-datatable-body-bg: transparent;
    --sn-color-datatable-label: #333;
    --sn-color-datatable-btn-border: #999;

    --sn-color-debug-btn-border: #333;
    --sn-color-debug-btn-on-text: #f43333;
    --sn-color-debug-btn-off-text: #096285;

    --sn-color-forbidden-dead-link: #dc3545;
}

These variables can be overridden by adding your own CSS file to the Sphinx project (see this how-to).

For examples of how to adjust the CSS, this documentation is configured to build against multiple themes using the following CSS:

furo
/* Note, the recommended way to set colors for furo is in the `html_theme_options`
https://pradyunsg.me/furo/customisation/#light-css-variables-dark-css-variables

But here we are setting the colors directly in the CSS,
to make it a little easier to compare to the different themes.
*/
body {
    --color-code-background: #eeffcc;
    --color-code-foreground: black;
    --sn-color-need-border: #555;
    --sn-color-need-row-border: hsla(232, 75%, 95%, 0.12);
    --sn-color-need-bg: #eee;
    --sn-color-need-bg-head: rgba(0, 0, 0, 0.1);
    --sn-color-complete-bg-head: rgba(0, 0, 0, 0.1);
    --sn-color-complete-bg-foot: rgba(0, 0, 0, 0.1);
    --sn-color-bg-gray: #eee;
    --sn-color-bg-lightgray: rgba(0, 0, 0, 0.004);
    --sn-color-bg-green: #05c46b;
    --sn-color-bg-red: #ff3f34;
    --sn-color-bg-yellow: #ffc048;
    --sn-color-bg-blue: #0fbcf9;
    --sn-color-debug-btn-border: #333;
    --sn-color-debug-btn-on-text: #f43333;
    --sn-color-debug-btn-off-text: #096285;
    --sn-color-datatable-label: var(--color-foreground-muted);
    --sn-color-datatable-btn-border: var(--color-foreground-muted);
}

@media not print {
    body[data-theme="dark"] {
        --color-code-background: #202020;
        --color-code-foreground: #d0d0d0;
        --sn-color-need-border: #aaaaaa;
        --sn-color-need-row-border: hsla(52, 75%, 5%, 0.12);
        --sn-color-need-bg: #111111;
        --sn-color-need-bg-head: rgba(255, 255, 255, 0.1);
        --sn-color-complete-bg-head: rgba(255, 255, 255, 0.1);
        --sn-color-complete-bg-foot: rgba(255, 255, 255, 0.1);
        --sn-color-bg-gray: #111111;
        --sn-color-bg-lightgray: rgba(255, 255, 255, 0.1);
        --sn-color-bg-green: #024e2a;
        --sn-color-bg-red: #81201b;
        --sn-color-bg-yellow: #a97c32;
        --sn-color-bg-blue: #096285;
        --sn-color-debug-btn-border: #888;
        --sn-color-debug-btn-on-text: #ff3f34;
        --sn-color-debug-btn-off-text: #0fbcf9;
    }

    @media (prefers-color-scheme: dark) {
        body:not([data-theme="light"]) {
            --color-code-background: #202020;
            --color-code-foreground: #d0d0d0;
            --sn-color-need-border: #aaaaaa;
            --sn-color-need-row-border: hsla(52, 75%, 5%, 0.12);
            --sn-color-need-bg: #111111;
            --sn-color-need-bg-head: rgba(255, 255, 255, 0.1);
            --sn-color-complete-bg-head: rgba(255, 255, 255, 0.1);
            --sn-color-complete-bg-foot: rgba(255, 255, 255, 0.1);
            --sn-color-bg-gray: #111111;
            --sn-color-bg-lightgray: rgba(255, 255, 255, 0.1);
            --sn-color-bg-green: #024e2a;
            --sn-color-bg-red: #81201b;
            --sn-color-bg-yellow: #a97c32;
            --sn-color-bg-blue: #096285;
            --sn-color-debug-btn-border: #888;
            --sn-color-debug-btn-on-text: #ff3f34;
            --sn-color-debug-btn-off-text: #0fbcf9;
        }
    }
}
pydata-sphinx-theme
body {
    --sn-color-datatable-label: var(--pst-color-text-muted);
    --sn-color-datatable-btn-border: var(--pst-color-text-muted);
}

html[data-theme="light"] {
    --sn-color-bg-gray: #eee;
    --sn-color-bg-lightgray: rgba(0, 0, 0, 0.004);
    --sn-color-bg-green: #05c46b;
    --sn-color-bg-red: #ff3f34;
    --sn-color-bg-yellow: #ffc048;
    --sn-color-bg-blue: #0fbcf9;

    --sn-color-border-lightgray: rgba(0, 0, 0, 0.05);
    --sn-color-border-green: #05c46b;
    --sn-color-border-red: #ff3f34;
    --sn-color-border-yellow: #ffc048;
    --sn-color-border-blue: #0fbcf9;

    --sn-color-bar-green: #05c46b;
    --sn-color-bar-red: #ff3f34;
    --sn-color-bar-yellow: #ffc048;
    --sn-color-bar-orange: #e67e22;
    --sn-color-bar-blue: #0fbcf9;

    --sn-color-need-border: #555;
    --sn-color-need-row-border: hsla(232, 75%, 95%, 0.12);
    --sn-color-need-bg: #eee;
    --sn-color-need-bg-head: rgba(0, 0, 0, 0.1);

    --sn-color-complete-bg-head: rgba(0, 0, 0, 0.1);
    --sn-color-complete-bg-foot: rgba(0, 0, 0, 0.1);

    --sn-color-datatable-body-bg: transparent;

    --sn-color-debug-btn-border: #333;
    --sn-color-debug-btn-on-text: #f43333;
    --sn-color-debug-btn-off-text: #096285;

    --sn-color-forbidden-dead-link: #dc3545;
}

html[data-theme="dark"] {
    --sn-color-bg-gray: #333;
    --sn-color-bg-lightgray: rgba(255, 255, 255, 0.1);
    --sn-color-bg-green: #04723c;
    --sn-color-bg-red: #81201b;
    --sn-color-bg-yellow: #a97c32;
    --sn-color-bg-blue: #096285;

    --sn-color-border-lightgray: rgba(255, 255, 255, 0.2);
    --sn-color-border-green: #04723c;
    --sn-color-border-red: #81201b;
    --sn-color-border-yellow: #a97c32;
    --sn-color-border-blue: #096285;

    --sn-color-bar-green: #05c46b;
    --sn-color-bar-red: #ff3f34;
    --sn-color-bar-yellow: #ffc048;
    --sn-color-bar-orange: #e67e22;
    --sn-color-bar-blue: #0fbcf9;

    --sn-color-need-border: #888;
    --sn-color-need-row-border: hsla(232, 75%, 95%, 0.12);
    --sn-color-need-bg: #333;
    --sn-color-need-bg-head: rgba(0, 0, 0, 0.1);

    --sn-color-complete-bg-head: rgba(0, 0, 0, 0.1);
    --sn-color-complete-bg-foot: rgba(0, 0, 0, 0.1);

    --sn-color-datatable-body-bg: transparent;

    --sn-color-debug-btn-border: #888;
    --sn-color-debug-btn-on-text: #ff3f34;
    --sn-color-debug-btn-off-text: #0fbcf9;

    --sn-color-forbidden-dead-link: #dc3545;
}

/* override */
table.need.need.need> :not(caption)>*>* {
    color: var(--pst-color-text-base)
}
sphinx-rtd-theme
/* Styling for the https://sphinx-rtd-theme.readthedocs.io theme */

/* this container is added dynamically by the sphinx_rtd_theme:
https://github.com/readthedocs/sphinx_rtd_theme/blob/28c377f99a0fb8a6a7545ceaa599b7afd082d344/src/theme.js#L103 

but it collapses the tables width, which we do not want
*/
div.wy-table-responsive {
    width: 100% !important;
    overflow-x: auto !important;
}

/* a lot of components, like paragraphs and header, do not have a top margin
so the datatable does not have a gap to the subsequent element
*/
div.dataTables_wrapper {
    margin-bottom: 2em;
}
sphinx-immaterial
body {
    --sn-color-need-bg: var(--md-default-bg-color);
    --sn-color-need-border: var(--md-typeset-table-color);
    --sn-color-need-row-border: var(--md-typeset-table-color);
    --sn-color-debug-btn-border: var(--md-typeset-color);
    --sn-color-datatable-label: var(--md-typeset-color);
    --sn-color-datatable-btn-border: var(--md-default-fg-color--light);
}

PlantUML support

needflow uses PlantUML and the Sphinx-extension sphinxcontrib-plantuml for generating the flows.

Both must be available and correctly configured to work.

Install PlantUML

  1. Download the latest version of the plantuml.jar file: http://sourceforge.net/projects/plantuml/files/plantuml.jar/download

  2. Make a new folder called utils inside your docs folder. Copy the plantuml.jar file into the utils folder.

  3. Install the plantuml sphinx extension: pip install sphinxcontrib-plantuml.

  4. Add sphinxcontrib.plantuml to the sphinx extension list in conf.py

extensions = ['sphinxcontrib.plantuml',
              'sphinx_needs']
  1. Configure plantuml in conf.py

on_rtd = os.environ.get('READTHEDOCS') == 'True'
if on_rtd:
    plantuml = 'java -Djava.awt.headless=true -jar /usr/share/plantuml/plantuml.jar'
else:
    plantuml = 'java -jar %s' % os.path.join(os.path.dirname(__file__), "utils", "plantuml.jar"))

    plantuml_output_format = 'png'

The final configuration contains already a setup for building and deploying the documentation on ReadTheDocs.

ReadTheDocs provides plantuml.jar already on their system, so do not store it inside your source version control system.

Using Docker

Sphinx-Needs is also available as a Docker Image.

See Sphinx-Needs Docker Image for the documentation and hints how to use it.

VS Code Extension

The VS Code extension ubCode provides support for Sphinx-Needs. See more details in the Documentation.