**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", ]
Raw data
{
"_id": null,
"home_page": "http://github.com/useblocks/sphinx-modeling",
"name": "sphinx-modeling",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7.2,<3.11",
"maintainer_email": "",
"keywords": "",
"author": "team useblocks",
"author_email": "info@useblocks.com",
"download_url": "https://files.pythonhosted.org/packages/84/88/f113d3b7b5eaa2bef42d70ef6464e923bf7920c64cc76982374e72741d57/sphinx_modeling-0.2.0.tar.gz",
"platform": null,
"description": "**Complete documentation**: https://sphinx-modeling.useblocks.com/\n\nIntroduction\n============\n\n``Sphinx-Modeling`` allows the definition of models and constraints for objects defined with\n`Sphinx-Needs <https://github.com/useblocks/sphinx-needs>`_. They can be validated during the Sphinx build.\n\n`pydantic <https://github.com/pydantic/pydantic>`_ is used under the hood to validate all models.\n\nArbitrary constraints can be enforced such as:\n\n- value constraints for need options\n- multiplicity of need link options\n- typed fields (string, regex, int, enums)\n- allow or disallow additional options\n- outgoing links must target specific need types or union of types\n- need type must be nested within another need type (via ``parent_need``)\n- need type must be part of a specific document or chapter/section\n- custom validators\n\n.. warning:: This Sphinx extension is in an early stage and subject to breaking changes.\n\nMotivation\n==========\n\nRequirements 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\nuse all ``needs_extra_options``/``needs_extra_links`` by default.\n\nThis is a problem for organizations that want to enforce well defined (UML) standards on objects.\nEspecially when migrating parts of the requirements management system to ``Sphinx-Needs`` it is crucial to be\nconsistent with existing solutions. Doing so enables technological interoperability.\n\nMore reasons to use sphinx-modeling are:\n\n* defining model constraints (typed links, multiplicity, allowed attributes, allowed values etc) as part of your model\n definition (and not as `need_warnings`). This leaves `need_warnings` with the load of doing only data relevant checks\n later. That is, reduce glue and duplication as much as possible.\n* automatic visualization of typed model (planned feature)\n* self contained need definitions which does not leave types, options, links and warnings scattered (planned feature)\n* user-documentation of meta-model (automatically create readable textual documentation on the types, its allowed\n values etc. Can be combined with additional docstring documentation as part of model definition if needed)\n* possibility to use the typed model in external tools (VsCode Extension, Linter etc.)\n* possibility to auto-generate\n `needs_ide_directive_snippets <https://sphinxcontrib-needs.readthedocs.io/en/latest/configuration.html#needs-ide-directive-snippets>`_ (planned feature)\n\n\nPlanned features\n================\n\n* Generation of the following ``Sphinx-Needs`` configurations from a model configuration:\n\n * ``needs_types``\n * ``needs_extra_options``\n * ``needs_extra_links``\n\n* Visualization of the model (e.g. with PlantUML)\n* Use the model as source for IDE extensions\n\nInstallation\n============\n\nUsing poetry\n------------\n::\n\n poetry add sphinx-modeling\n\n\nUsing pip\n---------\n::\n\n pip install sphinx-modeling\n\nUsing sources\n-------------\n::\n\n git clone https://github.com/useblocks/sphinx-modeling\n cd sphinx-modeling\n pip install .\n\nActivation\n----------\n\nAdd **sphinx_modeling** to your extensions::\n\n extensions = [\"sphinx_needs\", \"sphinx_modeling\", ]\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Sphinx extension to enable modeling and set constraints for sphinx-needs",
"version": "0.2.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "a09134276f1b7e09aef1bffc35d92bbb",
"sha256": "d8f9b04746b0258aac6c3bf1c23ea2457eb1326ad3c803eff23055a8a17ece59"
},
"downloads": -1,
"filename": "sphinx_modeling-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a09134276f1b7e09aef1bffc35d92bbb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7.2,<3.11",
"size": 29745,
"upload_time": "2022-12-12T15:51:12",
"upload_time_iso_8601": "2022-12-12T15:51:12.832880Z",
"url": "https://files.pythonhosted.org/packages/ba/c1/d71b2e1a1b7492102d8ad6758c7a0e02314320c5d93138047e1955f1492b/sphinx_modeling-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "d2f2f78fd717369ee39e666a2773317c",
"sha256": "90e965331ec2ae96c10f3842b3dee1280642118b4e221211b7d8505911d83022"
},
"downloads": -1,
"filename": "sphinx_modeling-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "d2f2f78fd717369ee39e666a2773317c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.2,<3.11",
"size": 31741,
"upload_time": "2022-12-12T15:51:14",
"upload_time_iso_8601": "2022-12-12T15:51:14.579747Z",
"url": "https://files.pythonhosted.org/packages/84/88/f113d3b7b5eaa2bef42d70ef6464e923bf7920c64cc76982374e72741d57/sphinx_modeling-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-12 15:51:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "useblocks",
"github_project": "sphinx-modeling",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-modeling"
}
JSON
