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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 90e965331ec2ae96c10f3842b3dee1280642118b4e221211b7d8505911d83022 |
|
MD5 | d2f2f78fd717369ee39e666a2773317c |
|
BLAKE2b-256 | 8488f113d3b7b5eaa2bef42d70ef6464e923bf7920c64cc76982374e72741d57 |
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | d8f9b04746b0258aac6c3bf1c23ea2457eb1326ad3c803eff23055a8a17ece59 |
|
MD5 | a09134276f1b7e09aef1bffc35d92bbb |
|
BLAKE2b-256 | bac1d71b2e1a1b7492102d8ad6758c7a0e02314320c5d93138047e1955f1492b |