Skip to main content

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

Project description

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

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx_modeling-0.2.0.tar.gz (31.7 kB view details)

Uploaded Source

Built Distribution

sphinx_modeling-0.2.0-py3-none-any.whl (29.7 kB view details)

Uploaded Python 3

File details

Details for the file sphinx_modeling-0.2.0.tar.gz.

File metadata

  • Download URL: sphinx_modeling-0.2.0.tar.gz
  • Upload date:
  • Size: 31.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.3.1 CPython/3.9.15 Linux/5.15.0-1024-azure

File hashes

Hashes for sphinx_modeling-0.2.0.tar.gz
Algorithm Hash digest
SHA256 90e965331ec2ae96c10f3842b3dee1280642118b4e221211b7d8505911d83022
MD5 d2f2f78fd717369ee39e666a2773317c
BLAKE2b-256 8488f113d3b7b5eaa2bef42d70ef6464e923bf7920c64cc76982374e72741d57

See more details on using hashes here.

File details

Details for the file sphinx_modeling-0.2.0-py3-none-any.whl.

File metadata

  • Download URL: sphinx_modeling-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 29.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.3.1 CPython/3.9.15 Linux/5.15.0-1024-azure

File hashes

Hashes for sphinx_modeling-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 d8f9b04746b0258aac6c3bf1c23ea2457eb1326ad3c803eff23055a8a17ece59
MD5 a09134276f1b7e09aef1bffc35d92bbb
BLAKE2b-256 bac1d71b2e1a1b7492102d8ad6758c7a0e02314320c5d93138047e1955f1492b

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page