Skip to content

Commit 481a69e

Browse files
juiwenchenjuiwenchen
authored
Merge pull request #11 from useblocks/analyser-cli
✨ Analyser CLI
2 parents 8b33b8d + 7597687 commit 481a69e

40 files changed

Lines changed: 3128 additions & 1250 deletions

‎.pre-commit-config.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ repos:
33
rev: v5.0.0
44
hooks:
55
- id: end-of-file-fixer
6+
exclude: tests/__snapshots__
67
- id: trailing-whitespace
78

89
- repo: https://github.com/astral-sh/ruff-pre-commit

‎.vscode/launch.json‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
{
2+
// Use IntelliSense to learn about possible attributes.
3+
// Hover to view descriptions of existing attributes.
4+
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
5+
"version": "0.2.0",
6+
"configurations": [
7+
{
8+
"name": "sphinx-build docs",
9+
"type": "debugpy",
10+
"request": "launch",
11+
"module": "sphinx",
12+
"args": [
13+
"-W",
14+
"--keep-going",
15+
"-v",
16+
"-b",
17+
"html",
18+
"-c",
19+
"docs",
20+
"docs/source",
21+
"docs/_build/html"
22+
],
23+
"console": "integratedTerminal",
24+
"cwd": "${workspaceFolder}",
25+
"justMyCode": false,
26+
},
27+
{
28+
"name": "sphinx-codelinks",
29+
"type": "debugpy",
30+
"request": "launch",
31+
"module": "sphinx",
32+
"args": [
33+
"-W",
34+
"--keep-going",
35+
"-v",
36+
"-b",
37+
"html",
38+
".",
39+
"_build/html"
40+
],
41+
"console": "integratedTerminal",
42+
"cwd": "${workspaceFolder}/tests/data/sphinx/",
43+
"justMyCode": false,
44+
},
45+
]
46+
}

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Full documentation: https://codelinks.useblocks.com
2727

2828
## Components
2929

30-
- **Source Discovery** ([`src/sphinx_codelinks/source_discovery`](src/sphinx_codelinks/source_discovery)): Code analysis and discovery
30+
- **Source Discovery** ([`src/sphinx_codelinks/source_discover`](src/sphinx_codelinks/source_discover)): Code analysis and discovery
3131
- **Virtual Docs** ([`src/sphinx_codelinks/virtual_docs`](src/sphinx_codelinks/virtual_docs)): Documentation generation
3232
- **Sphinx Extension** ([`src/sphinx_codelinks/sphinx_extension`](src/sphinx_codelinks/sphinx_extension)): Sphinx integration
3333
- **Command Line** ([`src/sphinx_codelinks/cmd.py`](src/sphinx_codelinks/cmd.py)): CLI interface

‎docs/source/basics/introduction.rst‎

Lines changed: 7 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,14 @@
11
Introduction
22
============
33

4-
``CodeLinks`` is a sphinx extension that provides a directive ``src-trace``
5-
to trace the :external+needs:doc:`Sphinx-Needs <index>` need items defined in source files.
4+
``CodeLinks`` is a Sphinx extension that provides the ``src-trace`` directive to establish traceability between source code and :external+needs:doc:`Sphinx-Needs <index>` items.
65

7-
Instead of putting RST syntax in the comment, the need definition in source code is simplified to one-liner only,
8-
so that users can just write their :ref:`customized one-line comment <oneline>` to have the traceability
9-
from the link between source code and documentation.
6+
At its core, ``CodeLinks`` uses a powerful ``Analyse`` to parse source code comments and extract valuable information. The ``Analyse`` can identify and extract three distinct types of content:
107

11-
The provided directive leverages the other two modules ``SourceDiscovery`` and ``VirtualDocs``,
12-
which are also packed in the extension,
13-
to discover source files and create the virtual documents for ``src-trace`` to consume.
8+
- **One-line need definitions**: Create new Sphinx-Needs directly from a single, :ref:`customized comment line <oneline>` in your source code.
9+
- **Need ID references**: Link code to existing need items without creating new ones, perfect for tracing implementations to requirements.
10+
- **Marked RST text**: Extract blocks of reStructuredText embedded within comments, allowing you to include rich documentation with associated metadata right next to your code.
1411

15-
Both ``SourceDiscovery`` and ``VirtualDocs`` provide the followings for the developers :
12+
``src-trace`` directive then consumes ``One-line need definitions`` to generate traceability between source code and your documentation.
1613

17-
- **Python API** to extend other further use cases.
18-
- **CLI** to have atomic steps in CI/CD pipelines.
14+
The ``Analyse``, along with the ``SourceDiscovery`` module, also provides both a **Python API** for extensibility and a **CLI** for integration into CI/CD pipelines.

‎docs/source/basics/quickstart.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,11 @@ Quick Start
33

44
.. image:: local_link.gif
55

6-
Three steps to quickly run ``CodeLinks`` to achieve **the above**:
6+
Three steps to quickly run ``CodeLinks`` to generate links to your source code:
77

88
- Configure Sphinx
9-
- Apply One-line comment for a ``Sphinx-Needs`` need item
10-
- Use ``src-trace`` directive
9+
- Add a one-line comment to your source code to define a ``Sphinx-Needs`` item.
10+
- Use the ``src-trace`` directive in your documentation.
1111

1212
Sphinx Config
1313
-------------
@@ -51,4 +51,4 @@ Example
5151

5252
.. note:: **local-url** is not working on the website as it only supports local browse
5353

54-
Section :ref:`Directive <directive>` provides more adavanced usage.
54+
Section :ref:`Directive <directive>` provides more advanced usage.

‎docs/source/components/analyse.rst‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
Analyse
2+
=======
3+
4+
The ``Analyse`` is a :ref:`CLI tool <cli>` that also provides an API for programmatic use. Its primary function is to extract specific, marked content from comments within source code files.
5+
6+
It can extract three types of content:
7+
8+
- Sphinx-Needs ID References
9+
- Oneline needs (see :ref:`OneLineCommentStyle <oneline>`)
10+
- Marked reStructuredText (RST) blocks
11+
12+
Configuration
13+
-------------
14+
15+
The ``Analyse`` is configured using a ``toml`` file. The examples throughout this document are based on the following configuration:
16+
17+
.. literalinclude:: ./../../../tests/data/analyse/default_config.toml
18+
:caption: default_config.toml
19+
:language: toml
20+
21+
This configuration instructs the analyse to extract ``Sphinx-Needs ID Refs`` and ``Marked rst text`` using the defined markers.
22+
23+
Sphinx-Needs ID Refs
24+
--------------------
25+
26+
Below is an example of a C++ source file containing need ID references and the corresponding JSON output from the analyse.
27+
28+
.. tabs::
29+
30+
.. code-tab:: cpp
31+
32+
#include <iostream>
33+
34+
// @need-ids: need_001, need_002, need_003, need_004
35+
void dummy_func1(){
36+
//...
37+
}
38+
39+
// @need-ids: need_003
40+
int main() {
41+
std::cout << "Starting demo_1..." << std::endl;
42+
dummy_func1();
43+
std::cout << "Demo_1 finished." << std::endl;
44+
return 0;
45+
}
46+
47+
.. code-tab:: json
48+
49+
[
50+
{
51+
"filepath": "tests/data/need_id_refs/dummy_1.cpp",
52+
"remote_url": "https://github.com/useblocks/sphinx-codelinks/blob/fa5a9129d60203355ae9fe4a725246a88522c60c/tests/data/need_id_refs/dummy_1.cpp#L3",
53+
"source_map": {
54+
"start": { "row": 2, "column": 13 },
55+
"end": { "row": 2, "column": 51 }
56+
},
57+
"tagged_scope": "void dummy_func1(){\n //...\n }",
58+
"need_ids": ["need_001", "need_002", "need_003", "need_004"],
59+
"marker": "@need-ids:",
60+
"type": "need-id-refs"
61+
},
62+
{
63+
"filepath": "tests/data/need_id_refs/dummy_1.cpp",
64+
"remote_url": "https://github.com/useblocks/sphinx-codelinks/blob/fa5a9129d60203355ae9fe4a725246a88522c60c/tests/data/need_id_refs/dummy_1.cpp#L8",
65+
"source_map": {
66+
"start": { "row": 7, "column": 13 },
67+
"end": { "row": 7, "column": 21 }
68+
},
69+
"tagged_scope": "int main() {\n std::cout << \"Starting demo_1...\" << std::endl;\n dummy_func1();\n std::cout << \"Demo_1 finished.\" << std::endl;\n return 0;\n }",
70+
"need_ids": ["need_003"],
71+
"marker": "@need-ids:",
72+
"type": "need-id-refs"
73+
}
74+
]
75+
76+
Marked RST
77+
----------
78+
79+
This example demonstrates how the analyse extracts RST blocks from comments.
80+
81+
.. tabs::
82+
83+
.. code-tab:: cpp
84+
85+
#include <iostream>
86+
87+
/*
88+
@rst
89+
.. impl:: implement dummy function 1
90+
:id: IMPL_71
91+
@endrst
92+
*/
93+
void dummy_func1(){
94+
//...
95+
}
96+
97+
// @rst..impl:: implement main function @endrst
98+
int main() {
99+
std::cout << "Starting demo_1..." << std::endl;
100+
dummy_func1();
101+
std::cout << "Demo_1 finished." << std::endl;
102+
return 0;
103+
}
104+
105+
106+
.. code-tab:: json
107+
108+
[
109+
{
110+
"filepath": "marked_rst/dummy_1.cpp",
111+
"remote_url": "https://github.com/useblocks/sphinx-codelinks/blob/26b301138eef25c5130518d96eaa7a29a9c6c9fe/marked_rst/dummy_1.cpp#L4",
112+
"source_map": {
113+
"start": { "row": 3, "column": 8 },
114+
"end": { "row": 3, "column": 61 }
115+
},
116+
"tagged_scope": "void dummy_func1(){\n //...\n }",
117+
"rst": ".. impl:: implement dummy function 1\n :id: IMPL_71\n",
118+
"type": "rst"
119+
},
120+
{
121+
"filepath": "marked_rst/dummy_1.cpp",
122+
"remote_url": "https://github.com/useblocks/sphinx-codelinks/blob/26b301138eef25c5130518d96eaa7a29a9c6c9fe/marked_rst/dummy_1.cpp#L14",
123+
"source_map": {
124+
"start": { "row": 13, "column": 7 },
125+
"end": { "row": 13, "column": 40 }
126+
},
127+
"tagged_scope": "int main() {\n std::cout << \"Starting demo_1...\" << std::endl;\n dummy_func1();\n std::cout << \"Demo_1 finished.\" << std::endl;\n return 0;\n }",
128+
"rst": "..impl:: implement main function ",
129+
"type": "rst"
130+
}
131+
]
132+
133+
Limitations
134+
-----------
135+
136+
Please be aware of the following limitations:
137+
138+
- **Supported Languages**: The analyse only supports comment styles for C/C++ (``//``, ``/*...*/``) and Python (``#``).
139+
- **Single Comment Style**: An analysis run can only process a single comment style at a time.
140+
- **Configuration Incompatibility**: The TOML configuration file cannot be shared with the ``CodeLink`` Sphinx extensions.

‎docs/source/components/cli.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _cli:
2+
13
Command Line Interface (CLI)
24
============================
35

‎docs/source/components/configuration.rst‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
.. _configuration:
22

3-
Configuration
4-
=============
3+
Configuration[Sphinx]
4+
=====================
55

6-
The configuration for ``CodeLinks`` take place in the project's :external+sphinx:ref:`conf.py file <build-config>`.
6+
The configuration for ``CodeLinks`` takes place in the project's :external+sphinx:ref:`conf.py file <build-config>`.
77

88
Each source code project may have different configurations because of its programming language or its locations.
99
Therefore, based on such consideration, there are **global options** and **project-specific options** for ``CodeLinks``
1010

11-
All configuration options starts with the prefix ``src_trace_`` for **Sphinx-CodeLinks**.
11+
All configuration options start with the prefix ``src_trace_`` for **Sphinx-CodeLinks**.
1212

1313
Global Options
1414
--------------
@@ -143,7 +143,7 @@ and its corresponding value is a dictionary containing the options specific to t
143143
comment_type
144144
~~~~~~~~~~~~
145145

146-
The option defined the comment type used in source code of the project.
146+
This option defines the comment type used in the source code of the project.
147147

148148
Default: **cpp**
149149

@@ -360,4 +360,4 @@ it is equivalent to the following RST
360360

361361
.. caution:: **type** and **title** must be configured in **needs_fields** as they are mandatory for Sphinx-Needs
362362

363-
More uses cases can be found in `tests <https://github.com/useblocks/sphinx-codelinks/tests>`__
363+
More uses cases can be found in `tests <https://github.com/useblocks/sphinx-codelinks/tree/main/tests>`__

‎docs/source/components/oneline.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,20 @@ One Line Comment Style
44
======================
55

66
Many users have raised concerns about the complexity of defining ``Sphinx-Needs`` need items with RST in source code.
7-
Therefore, ``CodeLinks`` provides a customizable one-line comment style pattern to define ``a need items``
7+
Therefore, ``CodeLinks`` provides a customizable one-line comment style pattern to define ``need items``
88
to simplify the effort required to create a need in source code.
99

1010
:ref:`Here <oneline_comment_style>` is the default one-line comment style.
1111

1212
Start and End sequences
1313
-----------------------
1414

15-
To have better understanding of its the syntax of one-line comment, we will break it down to the following:
15+
To have a better understanding of the syntax of a one-line comment, we will break it down into the following:
1616

1717
**start_sequence** defines the characters where the one-line comment starts.
1818
**end_sequence** defines the characters where the one-line comment ends.
1919

20-
The text between **start_sequence** and **end_sequence** contains the fields of ``need items``
20+
The text between **start_sequence** and **end_sequence** contains the fields of a ``need item``.
2121

2222
field_split_char
2323
----------------
@@ -95,7 +95,7 @@ For example, with the following **needs_fields** configuration:
9595
{"name": "links", "type": "list[str]", "default": []},
9696
],
9797
98-
the online line comment shall be defined as the following
98+
the one-line comment shall be defined as the following
9999

100100
.. tabs::
101101

‎docs/source/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ Contents
6161
components/configuration
6262
components/directive
6363
components/oneline
64-
64+
components/analyse
6565

6666
.. toctree::
6767
:maxdepth: 1

0 commit comments

Comments
 (0)