Skip to content

Commit 4d867c0

Browse files
patdhlkpatdhlk
committed
Add traceability
1 parent 83bcb95 commit 4d867c0

File tree

12 files changed

+394
-11
lines changed

12 files changed

+394
-11
lines changed

‎docs/source/basics/quickstart.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,6 @@ Sphinx Config
2727
:caption: src_trace.toml
2828
:language: toml
2929

30-
3130
One-line comment
3231
----------------
3332

‎docs/source/components/discover.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ Source Discover
66
SourceDiscover is one of the modules provided in ``Codelinks``. It discovers the source files from the given directory.
77
It provides users CLI and API to discover the source files.
88

9-
109
Usage Examples
1110
--------------
1211

‎docs/source/components/features.rst‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
Features
2+
========
3+
4+
.. dropdown:: 🔍 Features
5+
6+
.. needtable::
7+
:filter: type == "feature"
8+
:columns: id, title, si as "SI", parent_needs_back as "Errors"
9+
10+
.. feature:: Define new traceability objects in source code
11+
:id: FE_DEF
12+
13+
Create new Sphinx-Needs directly from a single comment line in your source code.
14+
This feature enables developers to maintain traceability information right at the point
15+
of implementation, ensuring that requirements, specifications, and code remain synchronized.
16+
17+
By embedding traceability markers in comments, you can:
18+
19+
* Define requirements, specifications, or test cases directly in source files
20+
* Automatically generate documentation from code comments
21+
* Maintain bidirectional links between documentation and implementation
22+
* Track coverage of requirements by implementation
23+
24+
.. fault:: Traceability objects are not detected in supported languages
25+
:id: FAULT_1
26+
27+
.. fault:: Sphinx-codelinks halucinates traceability objects
28+
:id: FAULT_2
29+
30+
.. feature:: Discover Source Code Files
31+
:id: FE_DISCOVERY
32+
33+
Discover source code files in a specified root directory. The root directory shall be configurable.
34+
35+
.. feature:: C Language Support
36+
:id: FE_C_SUPPORT
37+
38+
Support for defining traceability objects in C source code.
39+
40+
The C language parser leverages tree-sitter to accurately identify and extract
41+
comments from C source files, including both single-line (``//``) and multi-line
42+
(``/* */``) comment styles. This ensures that traceability markers are correctly
43+
associated with the appropriate code structures such as functions, structs, and
44+
global definitions.
45+
46+
Key capabilities:
47+
48+
* Detection of inline and block comments
49+
* Association of comments with function definitions
50+
* Support for standard C comment conventions
51+
* Accurate scope detection for nested structures
52+
53+
.. fault:: Traceability objects are not detected in C language
54+
:id: FAULT_C_1
55+
56+
.. fault:: Sphinx-codelinks halucinates traceability objects in C
57+
:id: FAULT_C_2
58+
59+
.. feature:: C++ Language Support
60+
:id: FE_CPP
61+
62+
Support for defining traceability objects in C++ source code.
63+
64+
Building upon C language support, the C++ parser handles the full complexity of modern
65+
C++ syntax including classes, namespaces, templates, and advanced features. The tree-sitter
66+
based parser ensures accurate comment extraction and scope detection across various C++
67+
constructs.
68+
69+
Enhanced features for C++:
70+
71+
* Class and namespace scope detection
72+
* Support for C++ style comments (``//``) and C style comments (``/* */``)
73+
* Template and method declaration handling
74+
* Accurate association with member functions and constructors
75+
* Support for modern C++ features (C++11/14/17/20)
76+
77+
.. fault:: Traceability objects are not detected in C++ language
78+
:id: FAULT_CPP_1
79+
80+
.. fault:: Sphinx-codelinks halucinates traceability objects in C++
81+
:id: FAULT_CPP_2
82+
83+
.. feature:: Python Language Support
84+
:id: FE_PY
85+
86+
Support for defining traceability objects in Python source code.
87+
88+
The Python language parser provides comprehensive support for Python's unique comment
89+
and docstring conventions. It can extract traceability markers from both standard
90+
comments (``#``) and docstrings (triple-quoted strings), making it ideal for Python's
91+
documentation-driven development practices.
92+
93+
Python-specific capabilities:
94+
95+
* Hash-style comment (``#``) detection
96+
* Docstring extraction from modules, classes, and functions
97+
* Proper handling of multi-line comments and docstrings
98+
* Scope detection for functions, classes, and methods
99+
* Support for nested class and function definitions
100+
* Integration with Python's natural documentation patterns
101+
102+
.. fault:: Traceability objects are not detected in Python language
103+
:id: FAULT_PY_1
104+
105+
.. fault:: Sphinx-codelinks halucinates traceability objects in Python
106+
:id: FAULT_PY_2
107+
108+
.. feature:: YAML Language Support
109+
:id: FE_YAML
110+
111+
Support for defining traceability objects in YAML configuration files.
112+
113+
The YAML language parser provides comprehensive support for YAML's structure
114+
and comment conventions. It can extract traceability markers from YAML comments
115+
(``#``) and properly associate them with YAML structures including key-value pairs,
116+
list items, and nested configurations, making it ideal for documenting configuration
117+
files, CI/CD pipelines, and infrastructure definitions.
118+
119+
YAML-specific capabilities:
120+
121+
* Hash-style comment (``#``) detection
122+
* Inline comment support with proper structure association
123+
* Block comment detection and association
124+
* Scope detection for block mapping pairs and sequence items
125+
* Support for nested YAML structures
126+
* Document structure handling with ``---`` separators
127+
* Accurate association of inline comments with their corresponding structures
128+
* Flow and block mapping/sequence support
129+
130+
.. fault:: Traceability objects are not detected in YAML language
131+
:id: FAULT_YAML_1
132+
133+
.. fault:: Sphinx-codelinks halucinates traceability objects in YAML
134+
:id: FAULT_YAML_2
135+
136+
.. feature:: Customized comment styles
137+
:id: FE_CMT
138+
139+
Support for different customized comment styles in source code.
140+
The comment structure can be defined in the configuration file.
141+
142+
This feature provides flexibility to adapt Sphinx-Codelinks to your project's
143+
existing coding standards and conventions. Define custom markers, prefixes, and
144+
delimiters that match your team's documentation practices without requiring code
145+
changes.
146+
147+
Configuration options include:
148+
149+
* Custom marker syntax (e.g., ``@req``, ``#TODO``, ``//!``)
150+
* Configurable comment prefixes and delimiters
151+
* Support for language-specific comment conventions
152+
* Flexible pattern matching for traceability markers
153+
* Per-project customization via configuration files
154+
155+
.. fault:: Customized comment styles are not detected in supported languages
156+
:id: FAULT_CMT
157+
158+
.. feature:: Link code to existing need items
159+
:id: FE_LNK
160+
161+
Link code to existing need items without creating new ones, perfect for tracing
162+
implementations to requirements.
163+
164+
This feature enables you to establish connections between your source code and
165+
existing documentation or requirements defined elsewhere in your Sphinx-Needs
166+
documentation. Instead of creating duplicate need objects, you can simply reference
167+
existing ones, maintaining a clean and organized traceability structure.
168+
169+
Linking capabilities:
170+
171+
* Reference existing requirements, specifications, or test cases by ID
172+
* Create bidirectional links between code and documentation
173+
* Avoid duplication of traceability information
174+
* Support for multiple links from a single code location
175+
* Automatic validation of link targets
176+
* Integration with Sphinx-Needs link visualization
177+
178+
.. fault:: Linking code to existing need items fails
179+
:id: FAULT_LNK_1
180+
181+
.. fault:: Sphinx-codelinks links code to wrong need items
182+
:id: FAULT_LNK_2
183+
184+
.. feature:: Extract blocks of reStructuredText embedded within comments
185+
:id: FE_RST_EXTRACTION
186+
187+
Extract blocks of reStructuredText embedded within comments, allowing you to
188+
include rich documentation with associated metadata right next to your code.
189+
190+
This powerful feature enables you to write full reStructuredText content directly
191+
in your source code comments, which will be extracted and processed as part of
192+
your Sphinx documentation. This approach brings documentation closer to implementation,
193+
making it easier to keep both synchronized.
194+
195+
reStructuredText extraction features:
196+
197+
* Full reStructuredText syntax support within comments
198+
* Extraction of formatted documentation blocks
199+
* Support for directives, roles, and inline markup
200+
* Preservation of indentation and formatting
201+
* Integration with Sphinx-Needs directives
202+
* Markers for block start (``@rst``) and end (``@endrst``)
203+
* Single-line and multi-line RST blocks
204+
205+
.. fault:: Extracting reStructuredText from comments fails
206+
:id: FAULT_RST_EXTRACTION_1
207+
208+
.. fault:: Sphinx-codelinks extracts wrong reStructuredText blocks
209+
:id: FAULT_RST_EXTRACTION_2
210+
211+
.. fault:: Extracted reStructuredText blocks are malformed
212+
:id: FAULT_RST_EXTRACTION_3
213+
214+
.. feature:: Analyze marked content via CLI interface
215+
:id: FE_CLI_ANALYZE
216+
217+
It shall be possible to analyze marked content via the CLI interface.
218+
219+
The command-line interface provides powerful tools for analyzing and reporting on
220+
traceability markers in your codebase without requiring a full Sphinx build. This
221+
enables quick validation, continuous integration checks, and standalone reporting.
222+
223+
CLI analysis capabilities:
224+
225+
* Scan source files for traceability markers
226+
* Generate reports on found markers and their metadata
227+
* Validate marker syntax and structure
228+
* Export analysis results in various formats (JSON, CSV)
229+
* Integration with CI/CD pipelines
230+
* Fast iteration during development
231+
* Batch processing of multiple files or directories
232+
233+
.. fault:: CLI integration fails silently
234+
:id: FAULT_CLI_ANALYZE_1
235+
236+
.. fault:: Sphinx-codelinks halucinates marked content
237+
:id: FAULT_CLI_ANALYZE_2
238+
239+
.. fault:: Sphinx-codelinks misses marked content
240+
:id: FAULT_CLI_ANALYZE_3
241+
242+
.. feature:: Discover the filepaths a specified root directory via CLI interface
243+
:id: FE_CLI_DISCOVER
244+
245+
It shall be possible to specify a root directory for the CLI interface.
246+
All files in and below this directory shall be discovered.
247+
248+
The discovery feature provides intelligent file system traversal to identify all
249+
relevant source files within a project structure. This enables bulk operations
250+
and ensures comprehensive coverage of your codebase.
251+
252+
Discovery features:
253+
254+
* Recursive directory traversal from specified root
255+
* File type filtering based on extensions
256+
* Respect for ignore patterns (e.g., ``.gitignore``)
257+
* Detection of binary vs. text files
258+
* Configurable include/exclude patterns
259+
* Support for multiple root directories
260+
* Efficient handling of large codebases
261+
262+
.. fault:: Specifying a root directory fails
263+
:id: FAULT_CLI_DISCOVER_1
264+
265+
.. fault:: Sphinx-codelinks discovers files outside the specified root directory
266+
:id: FAULT_CLI_DISCOVER_2
267+
268+
Root directory setting is not respected or ignored
269+
270+
.. feature:: Export marked content to other formats via CLI interface
271+
:id: FE_CLI_WRITE
272+
273+
It shall be possible to export marked content to other formats via the CLI interface.
274+
275+
The export functionality enables transformation of extracted traceability data into
276+
various output formats for use in external tools, reports, or downstream processing.
277+
This makes Sphinx-Codelinks a versatile component in your documentation toolchain.
278+
279+
Export capabilities:
280+
281+
* JSON format for programmatic processing
282+
* CSV format for spreadsheet analysis
283+
* Sphinx-Needs compatible formats
284+
* Custom format definitions via templates
285+
* Batch export of multiple analyses
286+
* Filtering and transformation options
287+
* Integration with external reporting tools
288+
* Support for incremental exports
289+
290+
.. fault:: Exporting marked content fails
291+
:id: FAULT_CLI_WRITE_1
292+
293+
.. fault:: Sphinx-codelinks exports wrong content
294+
:id: FAULT_CLI_WRITE_2
295+
296+
.. fault:: Exported content is malformed
297+
:id: FAULT_CLI_WRITE_3

‎docs/source/components/oneline.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,6 @@ to simplify the effort required to create a need in source code.
1313

1414
For more comprehensive examples and advanced configurations, see the `test cases <https://github.com/useblocks/sphinx-codelinks/tree/main/tests>`__.
1515

16-
1716
Start and End sequences
1817
-----------------------
1918

‎docs/source/components/write.rst‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -34,16 +34,16 @@ The following RST file with :external+needs:ref:`needextend <needextend>` direct
3434

3535
.. code-block:: rst
3636
37-
.. needextend:: NEED_001
38-
:remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3
37+
.. needextend:: NEED_001
38+
:remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3
3939
40-
.. needextend:: NEED_002
41-
:remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3
40+
.. needextend:: NEED_002
41+
:remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3
4242
43-
.. needextend:: NEED_003
44-
:remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3
43+
.. needextend:: NEED_003
44+
:remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3
4545
46-
.. needextend:: NEED_004
47-
:remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3
46+
.. needextend:: NEED_004
47+
:remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3
4848
4949
More examples can be found in `test cases <https://github.com/useblocks/sphinx-codelinks/blob/main/tests/test_needextend_write.py>`__

‎docs/source/development/traceability.rst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
Traceability
2+
============
3+
4+
Implementation
5+
--------------
6+
7+
.. src-trace::
8+
:project: sphinx_codelinks
9+
:directory: sphinx_codelinks
10+
11+
Testing
12+
-------
13+
14+
.. src-trace::
15+
:project: sphinx_codelinks
16+
:directory: tests

‎docs/source/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ Contents
6666
components/analyse
6767
components/discover
6868
components/write
69+
components/features
6970

7071
.. toctree::
7172
:maxdepth: 1
@@ -74,3 +75,4 @@ Contents
7475
development/roadmap
7576
development/change_log
7677
development/contributing
78+
development/traceability

0 commit comments

Comments
 (0)