Installation¶

Using poetry¶

poetry add sphinx-needs

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]

Using sources¶

git clone https://github.com/useblocks/sphinx-needs
cd sphinx-needs
pip install .
# or
poetry 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.

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.