https://github.com/useblocks/sphinx-modeling
Models and constraints for sphinx-needs objects
https://github.com/useblocks/sphinx-modeling
pydantic sphinx-doc sphinx-extension sphinx-needs
Last synced: 4 months ago
JSON representation
Models and constraints for sphinx-needs objects
- Host: GitHub
- URL: https://github.com/useblocks/sphinx-modeling
- Owner: useblocks
- License: mit
- Created: 2022-09-16T11:37:40.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-09-05T14:58:39.000Z (almost 2 years ago)
- Last Synced: 2025-10-31T00:43:22.685Z (8 months ago)
- Topics: pydantic, sphinx-doc, sphinx-extension, sphinx-needs
- Language: Python
- Homepage: https://sphinx-modeling.useblocks.com/
- Size: 18.7 MB
- Stars: 6
- Watchers: 2
- Forks: 2
- Open Issues: 4
-
Metadata Files:
- Readme: README.rst
- Contributing: docs/contributing.rst
- License: LICENSE
- Support: docs/support.rst
- Authors: AUTHORS
Awesome Lists containing this project
README
**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", ]