{"id":42763938,"url":"https://github.com/danieleades/sphinx-graph","last_synced_at":"2026-01-29T21:05:42.838Z","repository":{"id":44844897,"uuid":"499438130","full_name":"danieleades/sphinx-graph","owner":"danieleades","description":"Plain text requirements management using Sphinx","archived":false,"fork":false,"pushed_at":"2026-01-28T14:17:15.000Z","size":980,"stargazers_count":11,"open_issues_count":12,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-29T00:11:19.642Z","etag":null,"topics":["documentation","plain-text","requirements-management","sphinx","sphinx-extension","traceability"],"latest_commit_sha":null,"homepage":"https://github.com/danieleades/sphinx-graph","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danieleades.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"issuehunt":"danieleades","github":"danieleades"}},"created_at":"2022-06-03T08:35:27.000Z","updated_at":"2026-01-28T14:21:11.000Z","dependencies_parsed_at":"2022-09-11T02:50:50.028Z","dependency_job_id":"a8c02d25-cfc2-477e-8fd4-277dccd10ce8","html_url":"https://github.com/danieleades/sphinx-graph","commit_stats":{"total_commits":62,"total_committers":4,"mean_commits":15.5,"dds":"0.24193548387096775","last_synced_commit":"3b4c1701c1d69f1b7ea696ac5b4c34e691aa9e9b"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/danieleades/sphinx-graph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danieleades%2Fsphinx-graph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danieleades%2Fsphinx-graph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danieleades%2Fsphinx-graph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danieleades%2Fsphinx-graph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danieleades","download_url":"https://codeload.github.com/danieleades/sphinx-graph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danieleades%2Fsphinx-graph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28884831,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T19:55:09.949Z","status":"ssl_error","status_checked_at":"2026-01-29T19:55:08.490Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","plain-text","requirements-management","sphinx","sphinx-extension","traceability"],"created_at":"2026-01-29T21:05:37.844Z","updated_at":"2026-01-29T21:05:42.830Z","avatar_url":"https://github.com/danieleades.png","language":"Python","readme":"# Sphinx Graph\n\n[![codecov](https://codecov.io/gh/danieleades/sphinx-graph/branch/main/graph/badge.svg?token=WLPNTQXHrK)](https://codecov.io/gh/danieleades/sphinx-graph)\n[![CI](https://github.com/danieleades/sphinx-graph/actions/workflows/ci.yaml/badge.svg)](https://github.com/danieleades/sphinx-graph/actions/workflows/ci.yaml)\n[![sponsor](https://img.shields.io/static/v1?label=Sponsor\u0026message=%E2%9D%A4\u0026logo=GitHub\u0026color=%23fe8e86)](https://github.com/sponsors/danieleades)\n[![Documentation Status](https://readthedocs.org/projects/sphinx-graph/badge/?version=main)](https://sphinx-graph.readthedocs.io/en/main/?badge=main)\n\n'Sphinx-Graph' is a sphinx extension for plain-text, VCS-friendly, requirements management.\n\n## Key Features\n\n1. **Vertex Directive**: Define relationships between document elements.\n2. **Vertex Table**: Generate summary tables of vertices.\n3. **Fingerprinting**: Track changes and trigger reviews when parent elements are modified.\n4. **Customizable Layouts**: Choose how vertices are displayed in your documentation.\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 'parents' or 'children'\n- (Optionally) tracks a hash of each item to trigger reviews when any parents change\n\n## Getting Started\n\nInstall Sphinx-Graph using pip:\n\n```bash\npip install sphinx-graph\n```\n\nAdd it to your Sphinx project's `conf.py`:\n\n```python\nextensions = [\n   # ... other extensions ...\n   \"sphinx_graph\",\n]\n```\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\n## Generating Summary Tables\n\nThe `vertex-table` directive generates summary tables of vertices:\n\n```rst\n.. vertex-table::\n   :query: descendants\n\n   uid = \"REQ-001\"\n```\n\nThis will create a table showing REQ-001 and all its descendants.\n\n## Benefits of Sphinx-Graph\n\n1. **Version Control Friendly**: Plain-text format works well with Git and other VCS.\n2. **Flexible**: Define custom relationships between any elements in your documentation.\n3. **Traceable**: Easily track dependencies and impact of changes.\n4. **Integrated**: Seamlessly works within your Sphinx documentation.\n\n## Comparison with Similar Projects\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](https://github.com/useblocks/sphinx-needs):**\n\n- Sphinx-Needs is a more complex, feature-rich solution for requirements management, but may be heavy-weight for some use-cases.\n- Sphinx-Graph is smaller, more streamlined, and uses modern Python with strict type checking.\n- Sphinx-Graph can track 'suspect links' and force reviews when linked requirements are modified.\n\n**[Doorstop](https://github.com/doorstop-dev/doorstop):**\n\n- Doorstop is a command-line tool and Python API for managing requirements as text files.\n- Like Sphinx-Graph, Doorstop is lightweight and version-control friendly.\n- Sphinx-Graph integrates directly with Sphinx documentation, while Doorstop requires additional setup for documentation integration.\n- Sphinx-Graph offers more flexible relationship types between items compared to Doorstop's hierarchical structure.\n\n**Traditional Requirements Management Tools (Doors, Enterprise Architect, etc):**\n\n- Sphinx-Graph doesn't require complex workflows or specific expertise to maintain.\n- It's more cost-effective (it's free).\n- Can be maintained in plain-text alongside the code.\n\n\nFor more information, see [the docs](https://sphinx-graph.readthedocs.io/en/main/).\n\nor, build the local docs-\n\n```bash\ncd docs\nuv run make html\n```\n\n---\n\n*Was this useful? [Buy me a coffee](https://github.com/sponsors/danieleades/sponsorships?sponsor=danieleades\u0026preview=true\u0026frequency=recurring\u0026amount=5)*\n","funding_links":["https://issuehunt.io/r/danieleades","https://github.com/sponsors/danieleades","https://github.com/sponsors/danieleades/sponsorships?sponsor=danieleades\u0026preview=true\u0026frequency=recurring\u0026amount=5"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanieleades%2Fsphinx-graph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanieleades%2Fsphinx-graph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanieleades%2Fsphinx-graph/lists"}