Skip to content

Commit 2dc1673

Browse files
juiwenchenubmarco
juiwenchen
and
ubmarco
authored
🚀 Release v1.0.0 (#12)
Release v1.0.0 Updated change logs and roadmap Updated docs --------- Co-authored-by: Marco Heinemann <marco.heinemann@useblocks.com>
1 parent bd1fae9 commit 2dc1673

10 files changed

Lines changed: 162 additions & 93 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ A Sphinx extension for discovering, linking, and documenting source code across
55
## Features
66

77
- **Source Discovery**: Automatically discover source files in your project
8-
- **Virtual Documentation**: Generate documentation from code without modifying source files
8+
- **Analyse**: Parse source codes and extract specified markers with their metadata
99
- **Code Linking**: Create intelligent links between code elements
1010
- **Sphinx Integration**: Seamless integration with existing Sphinx documentation
1111

@@ -19,6 +19,7 @@ Add to your `conf.py`:
1919

2020
```python
2121
extensions = ['sphinx_needs', 'sphinx_codelinks']
22+
src_trace_config_from_toml = "codelinks.toml"
2223
```
2324

2425
## Documentation
@@ -28,7 +29,7 @@ Full documentation: https://codelinks.useblocks.com
2829
## Components
2930

3031
- **Source Discovery** ([`src/sphinx_codelinks/source_discover`](src/sphinx_codelinks/source_discover)): Code analysis and discovery
31-
- **Virtual Docs** ([`src/sphinx_codelinks/virtual_docs`](src/sphinx_codelinks/virtual_docs)): Documentation generation
32+
- **Analyse** ([`src/sphinx_codelinks/analyse`](src/sphinx_codelinks/analyse)): Documentation generation
3233
- **Sphinx Extension** ([`src/sphinx_codelinks/sphinx_extension`](src/sphinx_codelinks/sphinx_extension)): Sphinx integration
3334
- **Command Line** ([`src/sphinx_codelinks/cmd.py`](src/sphinx_codelinks/cmd.py)): CLI interface
3435

‎docs/source/components/configuration.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ Specifies the path to a `TOML file <https://toml.io>`__ containing **Sphinx-Code
2828
.. code-block:: python
2929
3030
# In conf.py
31-
src_trace_config_from_toml = "src_trace.toml"
31+
src_trace_config_from_toml = "codelinks.toml"
3232
3333
When using a TOML configuration file:
3434

‎docs/source/components/directive.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,9 @@
33
Directive
44
=========
55

6-
``CodeLinks`` provides the ``src-trace`` directive and it can be used in the following ways:
6+
.. attention:: ``src-trace`` directive currently only supports :ref:`one-line need definition <oneline>`.
7+
8+
``CodeLinks`` provides ``src-trace`` directive and it can be used in the following ways:
79

810
.. code-block:: rst
911

‎docs/source/components/oneline.rst‎

Lines changed: 37 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -91,14 +91,25 @@ For example, with the following **needs_fields** configuration:
9191

9292
.. _`fields_config`:
9393

94-
.. code-block:: python
94+
.. tabs::
95+
96+
.. code-tab:: python
97+
98+
needs_fields = [
99+
{"name": "title"},
100+
{"name": "id"},
101+
{"name": "type", "default": "impl"},
102+
{"name": "links", "type": "list[str]", "default": []},
103+
],
104+
105+
.. code-tab:: toml
95106

96-
needs_fields=[
97-
{"name": "title"},
98-
{"name": "id"},
99-
{"name": "type", "default": "impl"},
100-
{"name": "links", "type": "list[str]", "default": []},
101-
],
107+
needs_fields = [
108+
{ name = "title" },
109+
{ name = "id" },
110+
{ name = "type", default = "impl" },
111+
{ name = "links", type = "list[str]", default = [] },
112+
]
102113

103114
the one-line comment shall be defined as follows:
104115

@@ -122,17 +133,26 @@ when it is not given in the need definition.
122133

123134
For example, with the following needs_fields definition,
124135

125-
.. code-block:: python
136+
.. tabs::
137+
138+
.. code-tab:: python
139+
140+
needs_fields = [
141+
{
142+
"name": "title"
143+
},
144+
{
145+
"name": "type",
146+
"default": "implementation"
147+
},
148+
]
149+
150+
.. code-tab:: toml
126151

127-
needs_fields = [
128-
{
129-
"name": "title"
130-
},
131-
{
132-
"name": "type",
133-
"default": "implementation"
134-
},
135-
]
152+
needs_fields = [
153+
{ name = "title" },
154+
{ name = "type", default = "implementation" }
155+
]
136156

137157
the following need definition in source code is equivalent to RST shown below:
138158

‎docs/source/components/write.rst‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
.. _write:
2+
3+
Write
4+
=====
5+
6+
The ``write`` command is used to generate file formats such as reStructuredText from the markers extracted by the ``analyse`` command.
7+
This allows you to create documentation that includes links to source code based on the need ids specified in your code comments.
8+
9+
Example usage
10+
-------------
11+
12+
With the following extracted markers fron the ``analyse`` command,
13+
14+
.. code-block:: json
15+
16+
{
17+
"my_project": [
18+
{
19+
"filepath": "/home/demo/git_repo/ub/sphinx-codelinks/tests/data/need_id_refs/dummy_1.cpp",
20+
"remote_url": "https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3",
21+
"source_map": {
22+
"start": {"row": 2, "column": 13},
23+
"end": {"row": 2, "column": 51}
24+
},
25+
"tagged_scope": "void dummy_func1(){\n //...\n }",
26+
"need_ids": ["NEED_001", "NEED_002", "NEED_003", "NEED_004"],
27+
"marker": "@need-ids:",
28+
"type": "need-id-refs"
29+
},
30+
],
31+
}
32+
33+
The following RST file with :external+needs:ref:`needextend <needextend>` directive can be generated by the ``write rst`` command:
34+
35+
.. code-block:: rst
36+
37+
.. needextend:: NEED_001
38+
:remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3
39+
40+
.. needextend:: NEED_002
41+
:remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3
42+
43+
.. needextend:: NEED_003
44+
:remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3
45+
46+
.. needextend:: NEED_004
47+
:remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3
48+
49+
More examples can be found in `test cases <https://github.com/useblocks/sphinx-codelinks/blob/main/tests/test_needextend_write.py>`__

‎docs/source/development/change_log.rst‎

Lines changed: 42 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,47 @@
33
Changelog
44
=========
55

6-
.. _release:0.1.2:
6+
.. _`release:1.0.0`:
7+
8+
1.0.0
9+
-----
10+
11+
:Released: 22.08.2025
12+
13+
New and Improved
14+
................
15+
16+
- ✨ Added a new ``analyse`` CLI command and corresponding API.
17+
18+
The ``analyse`` command parses source files (Python, C/C++) and extracts markers from comments.
19+
It can extract three types of markers, as documented in the :ref:`analyse <analyse>` section:
20+
21+
- One-line need definitions
22+
- Need ID references
23+
- Marked RST blocks
24+
25+
The extracted markers and their metadata are saved to a JSON file for further processing.
26+
27+
- ✨ Added a new ``write rst`` CLI command.
28+
29+
The ``write rst`` command write a reStructuredText file with :external+needs:ref:`needextend <needextend>` directive from the extracted markers generated by ``analyse``.
30+
The generated RST can be included in the Sphinx documentation to create the source code links in the existing needs
31+
32+
- 🔨 Replaced ``virtual_docs`` with the new ``analyse`` module.
33+
34+
The ``virtual_docs`` feature, which handled one-line need definitions (:ref:`OneLineCommentStyle <oneline>`),
35+
has been migrated into the new ``analyse`` module and removed from the core.
36+
The caching feature of ``virtual_docs`` is temporarily removed and may be reintroduced later.
37+
38+
- 🔨 Updated the ``src-trace`` Sphinx directive.
39+
40+
The ``src-trace`` directive now uses the new ``analyse`` API instead of the old ``virtual_docs`` one.
41+
42+
- 🔨 Unified configuration in TOML
43+
44+
The configuration for ``src-trace`` directive defined in TOML is now compatible with the new ``analyse`` module.
45+
46+
.. _`release:0.1.2`:
747

848
0.1.2
949
-----
@@ -24,7 +64,7 @@ Fixes
2464
Local links between docs and one-line need definitions work correctly, when :ref:`src_dir <source_dir>` in multiple
2565
project configurations point at different locations.
2666

27-
.. _release:0.1.1:
67+
.. _`release:0.1.1`:
2868

2969
0.1.1
3070
-----

‎docs/source/development/roadmap.rst‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -3,31 +3,31 @@
33
Roadmap
44
=======
55

6-
Other Comment styles
7-
--------------------
6+
Command-Line Interface
7+
----------------------
88

9-
Currently, only ``C/C++`` comment style is supported.
10-
The other comment styles for different programming languages are planed, such as:
9+
- Introduce configurable ``--verbose`` and ``--quiet`` logging options.
1110

12-
- Python
13-
- Rust
14-
- YAML
15-
- SyML
11+
Configuration Files
12+
-------------------
1613

17-
Nested .gitignore
18-
-----------------
14+
- Support automatic discovery of TOML configuration files (e.g., ``pyproject.toml``).
15+
- Improve integration with the ``ubCode`` and ``Sphinx-Needs`` ecosystems.
1916

20-
``CodeLinks`` respects ``.gitignore`` file, but if the .gitignore files are nested, it's not supported.
21-
Respecting nested ``.gitignore`` in the context of the git repositories is planned.
17+
Source Code Parsing
18+
-------------------
2219

23-
Flexible way to define Sphinx-Needs need items in source code
24-
-------------------------------------------------------------
20+
- Introduce a configurable option to strip leading characters (e.g., ``*``) from commented RST blocks.
21+
- Enrich tagged scopes with additional metadata.
22+
- Extend language support by adding parsers for more comment styles, including but not limited to:
2523

26-
The only way to define ``Sphinx-Needs`` need items is through ``one-line comment style``.
27-
Raw RST text and multi-lines comments style are planned to support
24+
- Rust
25+
- YAML
2826

29-
Export needs.json
30-
-----------------
27+
- Enhance ``.gitignore`` handling to support nested ``.gitignore`` files.
3128

32-
To facilitate CI workflow and enhance the portability of ``need items`` defined in source code,
33-
we plan to have the feature to export the needs defined in source code to a JSON file.
29+
Defining Needs in Source Code
30+
-----------------------------
31+
32+
- Introduce flexible ways to define ``Sphinx-Needs`` items in source code, such as using raw RST text and multi-line comments.
33+
- Implement a feature to export needs defined in source code to a ``needs.json`` file, improving CI workflows and portability.

‎docs/source/index.rst‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,11 @@
1212

1313
.. div:: sd-fs-5 sd-font-italic
1414

15-
``Sphinx-CodeLinks`` is designed for Engineering-as-Code workflows to facilitate Application Lifecycle Management (ALM).
16-
It enables users to define ``Sphinx-Needs`` need items within source code using a single line and automatically extract them
17-
into the documentation during the Sphinx build process.
15+
``Sphinx-CodeLinks`` is a lightweight solution for enabling traceability between source code and documentation.
16+
With a single line in your code, you can:
17+
18+
1. Defining new ``Sphinx-Needs`` - extracted and integrated into the Sphinx build
19+
2. Embedding existing need IDs - extracted for cross-referencing with need items in the documentation
1820

1921
.. grid:: 1 1 2 2
2022
:gutter: 2 2 3 3
@@ -63,6 +65,7 @@ Contents
6365
components/oneline
6466
components/analyse
6567
components/discover
68+
components/write
6669

6770
.. toctree::
6871
:maxdepth: 1

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "sphinx-codelinks"
3-
version = "0.1.2"
3+
version = "1.0.0"
44
description = "Fast Source Code Traceability for Sphinx-Needs"
55
authors = [{ name = "team useblocks", email = "info@useblocks.com" }]
66
maintainers = [

‎src/sphinx_codelinks/README.md‎

Lines changed: 0 additions & 46 deletions
This file was deleted.

0 commit comments

Comments
 (0)