Complex Variant Handling

[danwos]

Resolving variant data can be a complex setup and be based on different input parameters, so that this may create a huge list of possible combinations of variant data.

For instance the max_speed can be the result of a combination by engine_type, engine_power, chassis, target_country.
To handle this, specialised tools are use like PureVariants or KConfig from the Linux Kernel developers.

This mean in the end, the exact value gets resolved outside of Sphinx-Needs.
This shall be supported, by reading in a file with resolved statements for variants vars.
These vars can the be used inside rst-code/Sphinx-Needs as some kind of placeholder.

Placeholder spec

Examples

Sphinx-Needs object

.. req:: For OS <<cfg_os>>
   :id: ID_<<cfg_os_id>>_001
   :status: open
   :max_speed: <<max_speed>

rst-code, using n_var role to inject data

Set max_speed to :n_var:`max_speed`

If-else statement

Different variants may need also bigger rst-parts, so that some kind of an if-else solution is needed

Examples

.. if:: ifelse_OS == "ifelse_Windows"

   We are building currently for Windows via ifelse.

   .. need:: Need ifelse Windows
      :id: N_VARIANT_IFELSE_WINDOWS

.. elseif:: ifelse_OS == "ifelse_MacOS"

   We are building currently for MacOS via ifelse.

   .. need:: Need ifelse MacOS
      :id: N_VARIANT_IFELSE_MACOS

.. elseif:: ifelse_OS == "ifelse_Linux"

   We are building currently for Linux via ifelse.

   .. need:: Need ifelse Linux
      :id: N_VARIANT_IFELSE_LINUX

.. else::

   We are building currently for an unknown OS via ifelse.

   .. need:: Need ifelse OS Unknown
      :id: N_VARIANT_IFELSE_OS_UNKNOWN

Idea coming from https://philippartsch.github.io/Howto-Sphinx/variant_management.html#sphinx-ifelse by @PhilipPartsch

Alternatives

Jinja can be used for this as well, but it can not resolved by most Sphinx-related solutions for checking/linting rst-files.
Also it will be hard to debug and reference, as it can create hundreds of lines of code just with a jinja-for-loop.
Therefore a native rst-solution would be great.