sphinx-modeling 0.2.0

Sphinx extension to enable modeling and set constraints for sphinx-needs

Complete documentation: https://sphinx-modeling.useblocks.com/

Introduction

Sphinx-Modeling allows the definition of models and constraints for objects defined with Sphinx-Needs. They can be validated during the Sphinx build.

pydantic is used under the hood to validate all models.

Arbitrary constraints can be enforced such as:

• value constraints for need options

• multiplicity of need link options

• typed fields (string, regex, int, enums)

• allow or disallow additional options

• outgoing links must target specific need types or union of types

• need type must be nested within another need type (via parent_need)

• need type must be part of a specific document or chapter/section

• custom validators

Warning

This Sphinx extension is in an early stage and subject to breaking changes.

Motivation

Requirements management with Sphinx-Needs and docs-as-code traditionally comes at the cost of complete freedom for developers. need_types, needs_extra_options and needs_extra_links are global and all need_types can use all needs_extra_options/needs_extra_links by default.

This is a problem for organizations that want to enforce well defined (UML) standards on objects. Especially when migrating parts of the requirements management system to Sphinx-Needs it is crucial to be consistent with existing solutions. Doing so enables technological interoperability.

More reasons to use sphinx-modeling are:

• defining model constraints (typed links, multiplicity, allowed attributes, allowed values etc) as part of your model definition (and not as need_warnings). This leaves need_warnings with the load of doing only data relevant checks later. That is, reduce glue and duplication as much as possible.

• automatic visualization of typed model (planned feature)

• self contained need definitions which does not leave types, options, links and warnings scattered (planned feature)

• user-documentation of meta-model (automatically create readable textual documentation on the types, its allowed values etc. Can be combined with additional docstring documentation as part of model definition if needed)

• possibility to use the typed model in external tools (VsCode Extension, Linter etc.)

• possibility to auto-generate needs_ide_directive_snippets (planned feature)

Planned features

• Generation of the following Sphinx-Needs configurations from a model configuration:

  • needs_types

  • needs_extra_options

  • needs_extra_links

• Visualization of the model (e.g. with PlantUML)

• Use the model as source for IDE extensions

Installation

Using poetry

poetry add sphinx-modeling

Using pip

pip install sphinx-modeling

Using sources

git clone https://github.com/useblocks/sphinx-modeling
cd sphinx-modeling
pip install .

Activation

Add sphinx_modeling to your extensions:

extensions = ["sphinx_needs", "sphinx_modeling", ]