Installation

Using poetry

poetry add sphinx-needs

Using pip

pip install sphinx-needs

Note

Prior version 1.0.1 the package was named sphinxcontrib-needs.

Using sources

git clone https://github.com/useblocks/sphinxcontrib-needs
cd sphinxcontrib-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.

Note

Prior version 1.0.1 the extensions was called sphinxcontrib.needs.

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.