Skip to content

Latest commit

 

History

History
89 lines (62 loc) · 3.18 KB

README.rst

File metadata and controls

89 lines (62 loc) · 3.18 KB
Raw

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", ]