Metadata-Version: 2.1
Name: sphinx-modeling
Version: 0.2.0
Summary: Sphinx extension to enable modeling and set constraints for sphinx-needs
Home-page: http://github.com/useblocks/sphinx-modeling
License: MIT
Author: team useblocks
Author-email: info@useblocks.com
Requires-Python: >=3.7.2,<3.11
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Documentation
Classifier: Topic :: Utilities
Requires-Dist: docutils (>=0.18.1)
Requires-Dist: pydantic (>=1.9.2,<2.0.0)
Requires-Dist: sphinx (>=5.0)
Requires-Dist: sphinx-needs (>=1.0.1)
Requires-Dist: sphinxcontrib-plantuml (>=0.24,<0.25)
Requires-Dist: typing-extensions (>=4.3.0,<5.0.0) ; python_version >= "3.7" and python_version < "3.8"
Project-URL: Documentation, https://sphinx-modeling.useblocks.com/
Project-URL: Repository, http://github.com/useblocks/sphinx-modeling
Description-Content-Type: text/x-rst

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

Introduction
============

``Sphinx-Modeling`` allows the definition of models and constraints for objects defined with
`Sphinx-Needs <https://github.com/useblocks/sphinx-needs>`_. They can be validated during the Sphinx build.

`pydantic <https://github.com/pydantic/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 <https://sphinxcontrib-needs.readthedocs.io/en/latest/configuration.html#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", ]

