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]
Note
Prior 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 .
# 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¶
Download the latest version of the plantuml.jar file: http://sourceforge.net/projects/plantuml/files/plantuml.jar/download
Make a new folder called
utils
inside your docs folder. Copy theplantuml.jar
file into theutils
folder.Install the plantuml sphinx extension:
pip install sphinxcontrib-plantuml
.Add
sphinxcontrib.plantuml
to the sphinx extension list inconf.py
extensions = ['sphinxcontrib.plantuml',
'sphinx_needs']
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.