Demos¶

Title	ID	Demonstrates
C++ API in Sphinx (using Doxygen)	needs_doxygen_breathe	doxygen_sphinx
Sphinx Needs external data	needs_external_data
Nested Need objects	nested_needs

Sphinx Needs external data¶

Contains examples for external data integration with Sphinx Needs.

Open demo

Analyse code on github

Demo result

Solution overview

No needs passed the filters

Title	ID

conf.py

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
from docutils.parsers.rst import directives


# -- Project information -----------------------------------------------------

project = 'Sphinx Needs external data'
copyright = '2021, sphinx-scale community'
author = 'sphinx-scale community'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinxcontrib.needs'
]

needs_extra_links = [
   {
      "option": "connects",
      "incoming": "connected by",
      "outgoing": "connects"
   }
]



needs_global_options = {
   # Without default value
   'layout': 'clean'
}

needs_extra_options = {
  "assignee": directives.unchanged,
 }

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

index.rst

.. Sphinx Needs external data documentation master file, created by
   sphinx-quickstart on Thu Apr 15 17:03:08 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Demo Sphinx Needs external data
===============================

This is a demo from the `Sphinx-Scale documentation project <https://sphinx-scale.readthedocs.io>`__.

It demonstrates the usage of:

* need_import

Please see `Sphinx-Scale documentation project <https://sphinx-scale.readthedocs.io>`__
for more details and source code.


Original Needs
--------------

.. req:: Dummy requirement
   :id: REQ_1
   :assignee: Alice

.. spec:: Dummy specification
   :id: SPEC_1
   :links: REQ_1
   :connects: REQ_1
   :assignee: Bob

.. test:: Dummy test case
   :id: TEST_1
   :links: SPEC_1, REQ_1
   :connects: SPEC_1
   :assignee: Charlie


Created needs.json
------------------

Created via ``make needs``.

.. literalinclude:: needs.json


Imported needs
--------------

Using::

   .. needimport:: needs.json

.. needimport:: needs.json
   :id_prefix: IMPORTED_
   :layout: complete
   :style: red_border


All needs
---------

.. needtable::
   :columns: id, title, outgoing, incoming, connects, connects_back

Solutions

No needs passed the filters

C++ API in Sphinx (using Doxygen)¶

Demo documents a C++ based API.

The API docs gets first generated by Doxygen. The sphinx extension Breathe reads in the Doxygen results and creates the needed data in this sphinx project.

Open demo

Analyse code on github

ID: needs_doxygen_breathe

Demo result

Solution overview

Title	ID
Doxygen + breathe for C++ APIs in Sphinx	doxygen_sphinx

conf.py

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
import subprocess
import shutil

sys.path.append(os.path.abspath("."))


# -- Project information -----------------------------------------------------

project = 'Demo C++ API with Doxygen'
copyright = '2021, sphinx-scale community'
author = 'sphinx-scale community'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinxcontrib.plantuml', 'sphinxcontrib.needs', 'breathe']


breathe_projects = {"doxygen_example": "_build/doxygen/xml"}
breathe_default_project = "doxygen_example"
if shutil.which("doxygen") and \
        not os.environ.get("SKIP_DOXYGEN", None) == "True":
    for prjname, prjdir in breathe_projects.items():
        print("Generating doxygen files for {}...".format(prjname))
        os.makedirs(prjdir, exist_ok=True)
        cmd = "cd code && doxygen {}.dox".format(prjname)
        subprocess.call(cmd, shell=True)
else:
    for prjname, prjdir in breathe_projects.items():
        assert os.path.exists(prjdir) is True, \
            "Regenerate doxygen XML for {}".format(prjname)

# PLANTUML config

on_rtd = os.environ.get('READTHEDOCS') == 'True'
cwd = os.getcwd()
local_plantuml_path = os.path.join(cwd, "../../docs/utils/plantuml.jar")

if on_rtd:
    # Deactivated using rtd plantuml version as it looks quite old.
    # plantuml = 'java -Djava.awt.headless=true -jar /usr/share/plantuml/plantuml.jar'
    plantuml = 'java -Djava.awt.headless=true -jar {}'.format(local_plantuml_path)
else:
    cwd = os.getcwd()
    plantuml = 'java -jar {}'.format(local_plantuml_path)

# If we are running on windows, we need to manipulate the path,
# otherwise plantuml will have problems.
if os.name == "nt":
    plantuml = plantuml.replace("/", "\\")
    plantuml = plantuml.replace("\\", "\\\\")

# plantuml_output_format = 'png'
plantuml_output_format = 'svg_img'


# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

index.rst

.. Demo C++ API with Doxygen documentation master file, created by
   sphinx-quickstart on Thu Apr 15 17:59:36 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Demo C++ API with Doxygen
=========================

RST content
-----------
.. need:: Need inside rst
   :id: NEED_1
   :status: open

.. need:: Need inside rst
   :id: NEED_3
   :status: open
   :links: NEED_1

C++ files
---------
:file: code/doxygen_example.hpp

.. literalinclude:: code/doxygen_example.hpp

Doxygen include
---------------
.. code-block:: rst

   .. doxygenfile:: doxygen_example.hpp
      :project: doxygen_example

``doxygenfile`` **result starts here:**

.. doxygenfile:: doxygen_example.hpp
   :project: doxygen_example

Analysis
--------
.. needtable::
   :style: table
   :columns: id, title, status, outgoing, incoming

.. needflow::

Solutions

Solution: Doxygen + breathe for C++ APIs in Sphinx doxygen_sphinx

style: green_border

layout: scale_short

template: solution

pre_template: pre_scale

post_template: post_solution

solves: cpp_api_doc

uses: doxygen, breathe, sphinx

demonstrated by: needs_doxygen_breathe

Doxygen must be installed on the system! And Breathe must be installed as Python package on the used virtual environment.

# conf.py

# Executes doxygen.
# This makes sure that the extension "breathe" has access to the latest API information.

extensions = ['breathe']

if shutil.which("doxygen"):
    breathe_projects = {
        "doxygen_example": "_build/doxygen/xml"
        }
    breathe_default_project = "doxygen_example"

    if not os.environ.get("SKIP_DOXYGEN", None) == "True":
        for prjname, prjdir in breathe_projects.items():
            print("Generating doxygen files for {}...".format(prjname))
            os.makedirs(prjdir, exist_ok=True)
            cmd = "cd code && doxygen {}.dox".format(prjname)
            subprocess.call(cmd, shell=True)
    else:
        for prjname, prjdir in breathe_projects.items():
            assert os.path.exists(prjdir) == True, \
                "Regenerate doxygen XML for {}".format(prjname)

.. index.rst

.. doxygenfile:: doxygen_example.hpp
   :project: doxygen_example

Nested Need objects¶

Uses embedded/nested needs and some dynamic functions to automatically link child needs to parent needs.

Open demo

Analyse code on github

Demo result

Solution overview

No needs passed the filters

Title	ID

conf.py

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))


# -- Project information -----------------------------------------------------

project = 'Nested needs'
copyright = '2021, sphinx scale'
author = 'sphinx scale'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'sphinxcontrib.needs'
]

from docutils.parsers.rst import directives

needs_extra_options = {
  "main_req": directives.unchanged,
}

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

index.rst

.. Nested needs documentation master file, created by
   sphinx-quickstart on Mon Apr 26 12:44:24 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Nested needs
============

Example of how needs can be nested / embedded and to make use of meta data from parent need.



.. req:: Parent requirement
   :id: REQ_001
   :status: open
   :style: green_border

   This is the parent requirement.

   It shall get some kind of a child requirement.


   .. req:: Child requirement
      :id: REQ_001_a
      :status: closed
      :style: blue_border

      I'm the child requirement.

      .. spec:: A spec for the child requirement
         :id: REQ_001_a_a
         :main_req: [[copy("parent_need")]]
         :style: red_border

         I'm the the spec for the child requirement.

      Req child text after embedded spec.

   Req parent text after embedded child requirement.


Analysis
--------


.. needtable::
   :style: table
   :columns: id, title, parent_needs, child needs

Solutions

No needs passed the filters