Overview
For a more serious project, it is often recommended to have a "high-level" design document (suggestion is to use <project root>/SPECIFICATION.md) that contains "requirements" (sentences in the design document that contain identifying language such as MUST, MUST NOT, MAY, SHALL, SHALL NOT, SHOULD, etc.) which describe the system's intended operation.
These types of documents are very useful in helping to identify "requirements coverage", which are parts of the code and/or test suite that match the requirements in the specification and ensure overall traceability from design specification to implementation and verification/validation activities.
Especially in the age of AI/LLM coding, this will become more important as we get further from actual human "ownership" of implementing or testing these design requirements, as it streamlines (human or AI-assisted) system design review (what we typically call "auditing") and helps us answer the question "is it done yet?"
Specification
The basics of how this might work is to take the normal markdown-based rendering of documents (like the project's README.md, which is typically just a high-level about/motivation document, with other information about the project) and add special "requirements transformation" and rendering to this sphinx plugin, so that the original source gets analyzed for "requirement statements", and a special link gets added to the rendered docuemnt so that documentation from other relevant sections (think contract autodoc using NatSpec, or similar with tests) can "link" back to the specification, demonstrating a requirements "linkage" between design spec and these other documentation sections.
Further, explore a higher-level "documentation agent" (bundled with this plugin?) that can read a documentation page containing this setup and discover coverage "gaps" (missing implementation/test for spec requirement, or broken links indicating a requirements change) and create issues for them to be handled by downstream development processes.
Dependencies
Related to #8, as it can "lift" requirement ID-linked comments in contract-based code/test comments/NatSpec (e.g. @req 1a2b3c4 ...)
Overview
For a more serious project, it is often recommended to have a "high-level" design document (suggestion is to use
<project root>/SPECIFICATION.md) that contains "requirements" (sentences in the design document that contain identifying language such as MUST, MUST NOT, MAY, SHALL, SHALL NOT, SHOULD, etc.) which describe the system's intended operation.These types of documents are very useful in helping to identify "requirements coverage", which are parts of the code and/or test suite that match the requirements in the specification and ensure overall traceability from design specification to implementation and verification/validation activities.
Especially in the age of AI/LLM coding, this will become more important as we get further from actual human "ownership" of implementing or testing these design requirements, as it streamlines (human or AI-assisted) system design review (what we typically call "auditing") and helps us answer the question "is it done yet?"
Specification
The basics of how this might work is to take the normal markdown-based rendering of documents (like the project's
README.md, which is typically just a high-level about/motivation document, with other information about the project) and add special "requirements transformation" and rendering to this sphinx plugin, so that the original source gets analyzed for "requirement statements", and a special link gets added to the rendered docuemnt so that documentation from other relevant sections (think contract autodoc using NatSpec, or similar with tests) can "link" back to the specification, demonstrating a requirements "linkage" between design spec and these other documentation sections.Further, explore a higher-level "documentation agent" (bundled with this plugin?) that can read a documentation page containing this setup and discover coverage "gaps" (missing implementation/test for spec requirement, or broken links indicating a requirements change) and create issues for them to be handled by downstream development processes.
Dependencies
Related to #8, as it can "lift" requirement ID-linked comments in contract-based code/test comments/NatSpec (e.g.
@req 1a2b3c4 ...)