Skip to content
Back to top
View this page
Edit this page

# 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']

5. 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.