# Sphinx Graph
[](https://codecov.io/gh/danieleades/sphinx-graph)
[](https://github.com/danieleades/sphinx-graph/actions/workflows/ci.yaml)
[](https://github.com/sponsors/danieleades)
[](https://sphinx-graph.readthedocs.io/en/main/?badge=main)
'Sphinx-Graph' is a plain-text, VCS-friendly, requirements management tool.
With Sphinx-Graph you define relationships between items in a document. These items form a directed acyclic graph (DAG). The extension-
- checks for cyclic references
- populates items with links to their 'neighbours'
- (optionally) tracks a hash of each item to trigger reviews when any parents change
Sphinx Graph is *heavily* inspired by [Sphinx-Needs](https://github.com/useblocks/sphinx-needs). Sphinx-Graph started life as a proof of concept refactor of Sphinx-Needs using modern python and strict type checking.
- Sphinx-Needs is the full-featured, grand-daddy of Sphinx-Graph
- By comparison, Sphinx-Graph is streamlined, and focuses on a much smaller feature set
## Vertices
The core sphinx directive provided by this extension is a 'Vertex'. A Vertex directive can be used to define relationships between text elements.
```rst
.. vertex:: USR-001
this is a user requirement.
This user requirement forms the basis of derived system requirements. When it is rendered in a
sphinx document it will be augmented with links to any child vertices.
.. vertex:: SYS-001
:parents: USR-001
this is system requirement of some sort.
It is derived from a higher-level user requirement (USR-001).
When it is rendered in a sphinx document, it will be augmented with links to its parent as well
as any 'children'.
.. vertex:: SYS-002
:parents: USR-001:iG91
this is another system requirement. This time the link to USR-001 is tracking the 'fingerprint'
of its parent.
The fingerprint is a 4-character hash. If USR-001 is modified, then SYS-002 will fail the build
until the fingerprint is updated (the build error provides the new fingerprint). This means that
changing a Vertex will trigger a review of all dependent vertices.
```
For more information, see [the docs](https://sphinx-graph.readthedocs.io/en/main/).
or, build the local docs-
cd docs
poetry run make html
---
*Was this useful? [Buy me a coffee](https://github.com/sponsors/danieleades/sponsorships?sponsor=danieleades&preview=true&frequency=recurring&amount=5)*
Raw data
{
"_id": null,
"home_page": "https://github.com/danieleades/sphinx-graph",
"name": "sphinx-graph",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "sphinx, requirements, documentation, plain-text",
"author": "Daniel Eades",
"author_email": "danieleades@hotmail.com",
"download_url": "https://files.pythonhosted.org/packages/49/e4/8bd9c75c0213e38694a3fb3bb0c26ac44c9fb9c7f6456cf4fe61f06f8bfd/sphinx_graph-0.2.3.tar.gz",
"platform": null,
"description": "# Sphinx Graph\n\n[](https://codecov.io/gh/danieleades/sphinx-graph)\n[](https://github.com/danieleades/sphinx-graph/actions/workflows/ci.yaml)\n[](https://github.com/sponsors/danieleades)\n[](https://sphinx-graph.readthedocs.io/en/main/?badge=main)\n\n'Sphinx-Graph' is a plain-text, VCS-friendly, requirements management tool.\n\nWith Sphinx-Graph you define relationships between items in a document. These items form a directed acyclic graph (DAG). The extension-\n\n- checks for cyclic references\n- populates items with links to their 'neighbours'\n- (optionally) tracks a hash of each item to trigger reviews when any parents change\n\nSphinx Graph is *heavily* inspired by [Sphinx-Needs](https://github.com/useblocks/sphinx-needs). Sphinx-Graph started life as a proof of concept refactor of Sphinx-Needs using modern python and strict type checking.\n\n- Sphinx-Needs is the full-featured, grand-daddy of Sphinx-Graph\n- By comparison, Sphinx-Graph is streamlined, and focuses on a much smaller feature set\n\n## Vertices\n\nThe core sphinx directive provided by this extension is a 'Vertex'. A Vertex directive can be used to define relationships between text elements.\n\n```rst\n.. vertex:: USR-001\n\n this is a user requirement.\n\n This user requirement forms the basis of derived system requirements. When it is rendered in a\n sphinx document it will be augmented with links to any child vertices.\n\n.. vertex:: SYS-001\n :parents: USR-001\n\n this is system requirement of some sort.\n\n It is derived from a higher-level user requirement (USR-001).\n When it is rendered in a sphinx document, it will be augmented with links to its parent as well\n as any 'children'.\n\n.. vertex:: SYS-002\n :parents: USR-001:iG91\n\n this is another system requirement. This time the link to USR-001 is tracking the 'fingerprint'\n of its parent.\n\n The fingerprint is a 4-character hash. If USR-001 is modified, then SYS-002 will fail the build\n until the fingerprint is updated (the build error provides the new fingerprint). This means that\n changing a Vertex will trigger a review of all dependent vertices.\n```\n\nFor more information, see [the docs](https://sphinx-graph.readthedocs.io/en/main/).\n\nor, build the local docs-\n\n cd docs\n poetry run make html\n\n---\n\n*Was this useful? [Buy me a coffee](https://github.com/sponsors/danieleades/sponsorships?sponsor=danieleades&preview=true&frequency=recurring&amount=5)*\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "'Sphinx-Graph' is a plain-text, VCS-friendly, requirements management tool.",
"version": "0.2.3",
"project_urls": {
"Documentation": "https://sphinx-graph.readthedocs.io/en/latest/index.html",
"Homepage": "https://github.com/danieleades/sphinx-graph"
},
"split_keywords": [
"sphinx",
" requirements",
" documentation",
" plain-text"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "93ed11b5fc7abfab5a82ac0b030a194cd7e56215e4cfd232ebca0881475b5552",
"md5": "493c0f3d512115b1cce249b5ebe2bd43",
"sha256": "8558247c2177740b03d5241b168041110d0ccb19d554a2c4df73961b7df490b3"
},
"downloads": -1,
"filename": "sphinx_graph-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "493c0f3d512115b1cce249b5ebe2bd43",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 19729,
"upload_time": "2024-04-08T08:24:28",
"upload_time_iso_8601": "2024-04-08T08:24:28.374221Z",
"url": "https://files.pythonhosted.org/packages/93/ed/11b5fc7abfab5a82ac0b030a194cd7e56215e4cfd232ebca0881475b5552/sphinx_graph-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "49e48bd9c75c0213e38694a3fb3bb0c26ac44c9fb9c7f6456cf4fe61f06f8bfd",
"md5": "71a5bdbf73a691d65b4d41ea3e843862",
"sha256": "a0916cc2885c4162b22e08f7cb6ff5e338ffcf23d7abd6d6d995ccc64a562d50"
},
"downloads": -1,
"filename": "sphinx_graph-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "71a5bdbf73a691d65b4d41ea3e843862",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 14732,
"upload_time": "2024-04-08T08:24:30",
"upload_time_iso_8601": "2024-04-08T08:24:30.169101Z",
"url": "https://files.pythonhosted.org/packages/49/e4/8bd9c75c0213e38694a3fb3bb0c26ac44c9fb9c7f6456cf4fe61f06f8bfd/sphinx_graph-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-08 08:24:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "danieleades",
"github_project": "sphinx-graph",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-graph"
}
JSON
