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¶
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.
VS Code Extension¶
The VS Code extension ubCode provides support for Sphinx-Needs. See more details in the Documentation.