🚀 Release v1.0.0

README.md

@@ -5,7 +5,7 @@ A Sphinx extension for discovering, linking, and documenting source code across
 ## Features
 
 - **Source Discovery**: Automatically discover source files in your project
-- **Virtual Documentation**: Generate documentation from code without modifying source files
+- **Analyse**: Parse source codes and extract specified markers with their metadata
 - **Code Linking**: Create intelligent links between code elements
 - **Sphinx Integration**: Seamless integration with existing Sphinx documentation
 
@@ -19,6 +19,7 @@ Add to your `conf.py`:
 
 ```python
 extensions = ['sphinx_needs', 'sphinx_codelinks']
+src_trace_config_from_toml = "codelinks.toml"
 ```
 
 ## Documentation
@@ -28,7 +29,7 @@ Full documentation: https://codelinks.useblocks.com
 ## Components
 
 - **Source Discovery** ([`src/sphinx_codelinks/source_discover`](src/sphinx_codelinks/source_discover)): Code analysis and discovery
-- **Virtual Docs** ([`src/sphinx_codelinks/virtual_docs`](src/sphinx_codelinks/virtual_docs)): Documentation generation
+- **Analyse** ([`src/sphinx_codelinks/analyse`](src/sphinx_codelinks/analyse)): Documentation generation
 - **Sphinx Extension** ([`src/sphinx_codelinks/sphinx_extension`](src/sphinx_codelinks/sphinx_extension)): Sphinx integration
 - **Command Line** ([`src/sphinx_codelinks/cmd.py`](src/sphinx_codelinks/cmd.py)): CLI interface
 

docs/source/components/configuration.rst

@@ -28,7 +28,7 @@ Specifies the path to a `TOML file <https://toml.io>`__ containing **Sphinx-Code
 .. code-block:: python
 
    # In conf.py
-   src_trace_config_from_toml = "src_trace.toml"
+   src_trace_config_from_toml = "codelinks.toml"
 
 When using a TOML configuration file:
 

docs/source/components/directive.rst

@@ -3,7 +3,9 @@
 Directive
 =========
 
-``CodeLinks`` provides the ``src-trace`` directive and it can be used in the following ways:
+.. attention:: ``src-trace`` directive currently only supports :ref:`one-line need definition <oneline>`.
+
+``CodeLinks`` provides ``src-trace`` directive and it can be used in the following ways:
 
 .. code-block:: rst
 

docs/source/components/oneline.rst

@@ -91,14 +91,25 @@ For example, with the following **needs_fields** configuration:
 
 .. _`fields_config`:
 
-.. code-block:: python
+.. tabs::
+
+   .. code-tab:: python
+
+      needs_fields = [
+         {"name": "title"},
+         {"name": "id"},
+         {"name": "type", "default": "impl"},
+         {"name": "links", "type": "list[str]", "default": []},
+      ],
+
+   .. code-tab:: toml
 
-   needs_fields=[
-       {"name": "title"},
-       {"name": "id"},
-       {"name": "type", "default": "impl"},
-       {"name": "links", "type": "list[str]", "default": []},
-   ],
+      needs_fields = [
+         { name = "title" },
+         { name = "id" },
+         { name = "type", default = "impl" },
+         { name = "links", type = "list[str]", default = [] },
+      ]
 
 the one-line comment shall be defined as follows:
 
@@ -122,17 +133,26 @@ when it is not given in the need definition.
 
 For example, with the following needs_fields definition,
 
-.. code-block:: python
+.. tabs::
+
+   .. code-tab:: python
+
+      needs_fields = [
+         {
+            "name": "title"
+         },
+         {
+            "name": "type",
+            "default": "implementation"
+         },
+      ]
+
+   .. code-tab:: toml
 
-   needs_fields = [
-       {
-           "name": "title"
-       },
-       {
-           "name": "type",
-           "default": "implementation"
-       },
-   ]
+      needs_fields = [
+         { name = "title" },
+         { name = "type", default = "implementation" }
+      ]
 
 the following need definition in source code is equivalent to RST shown below:
 

docs/source/components/write.rst

@@ -0,0 +1,49 @@
+.. _write:
+
+Write
+=====
+
+The ``write`` command is used to generate file formats such as reStructuredText from the markers extracted by the ``analyse`` command.
+This allows you to create documentation that includes links to source code based on the need ids specified in your code comments.
+
+Example usage
+-------------
+
+With the following extracted markers fron the ``analyse`` command,
+
+.. code-block:: json
+
+   {
+       "my_project": [
+           {
+               "filepath": "/home/demo/git_repo/ub/sphinx-codelinks/tests/data/need_id_refs/dummy_1.cpp",
+               "remote_url": "https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3",
+               "source_map": {
+                   "start": {"row": 2, "column": 13},
+                   "end": {"row": 2, "column": 51}
+               },
+               "tagged_scope": "void dummy_func1(){\n     //...\n }",
+               "need_ids": ["NEED_001", "NEED_002", "NEED_003", "NEED_004"],
+               "marker": "@need-ids:",
+               "type": "need-id-refs"
+           },
+       ],
+   }
+
+The following RST file with :external+needs:ref:`needextend <needextend>` directive can be generated by the ``write rst`` command:
+
+.. code-block:: rst
+
+    .. needextend:: NEED_001
+           :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3
+
+    .. needextend:: NEED_002
+           :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3
+
+    .. needextend:: NEED_003
+           :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3
+
+    .. needextend:: NEED_004
+           :remote-url: https://github.com/useblocks/sphinx-codelinks/blob/951e40e7845f06d5cfc4ca20ebb984308fdaf985/tests/data/need_id_refs/dummy_1.cpp#L3
+
+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

@@ -3,7 +3,47 @@
 Changelog
 =========
 
-.. _release:0.1.2:
+.. _`release:1.0.0`:
+
+1.0.0
+-----
+
+:Released: 22.08.2025
+
+New and Improved
+................
+
+- ✨ Added a new ``analyse`` CLI command and corresponding API.
+
+  The ``analyse`` command parses source files (Python, C/C++) and extracts markers from comments.
+  It can extract three types of markers, as documented in the :ref:`analyse <analyse>` section:
+
+  - One-line need definitions
+  - Need ID references
+  - Marked RST blocks
+
+  The extracted markers and their metadata are saved to a JSON file for further processing.
+
+- ✨ Added a new ``write rst`` CLI command.
+
+  The ``write rst`` command write a reStructuredText file with :external+needs:ref:`needextend <needextend>` directive from the extracted markers generated by ``analyse``.
+  The generated RST can be included in the Sphinx documentation to create the source code links in the existing needs
+
+- 🔨 Replaced ``virtual_docs`` with the new ``analyse`` module.
+
+  The ``virtual_docs`` feature, which handled one-line need definitions (:ref:`OneLineCommentStyle <oneline>`),
+  has been migrated into the new ``analyse`` module and removed from the core.
+  The caching feature of ``virtual_docs`` is temporarily removed and may be reintroduced later.
+
+- 🔨 Updated the ``src-trace`` Sphinx directive.
+
+  The ``src-trace`` directive now uses the new ``analyse`` API instead of the old ``virtual_docs`` one.
+
+- 🔨 Unified configuration in TOML
+
+  The configuration for ``src-trace`` directive defined in TOML is now compatible with the new ``analyse`` module.
+
+.. _`release:0.1.2`:
 
 0.1.2
 -----
@@ -24,7 +64,7 @@ Fixes
   Local links between docs and one-line need definitions work correctly, when :ref:`src_dir <source_dir>` in multiple
   project configurations point at different locations.
 
-.. _release:0.1.1:
+.. _`release:0.1.1`:
 
 0.1.1
 -----

docs/source/development/roadmap.rst

@@ -3,31 +3,31 @@
 Roadmap
 =======
 
-Other Comment styles
---------------------
+Command-Line Interface
+----------------------
 
-Currently, only ``C/C++`` comment style is supported.
-The other comment styles for different programming languages are planed, such as:
+- Introduce configurable ``--verbose`` and ``--quiet`` logging options.
 
-- Python
-- Rust
-- YAML
-- SyML
+Configuration Files
+-------------------
 
-Nested .gitignore
------------------
+- Support automatic discovery of TOML configuration files (e.g., ``pyproject.toml``).
+- Improve integration with the ``ubCode`` and ``Sphinx-Needs`` ecosystems.
 
-``CodeLinks`` respects ``.gitignore`` file, but if the .gitignore files are nested, it's not supported.
-Respecting nested ``.gitignore`` in the context of the git repositories is planned.
+Source Code Parsing
+-------------------
 
-Flexible way to define Sphinx-Needs need items in source code
--------------------------------------------------------------
+- Introduce a configurable option to strip leading characters (e.g., ``*``) from commented RST blocks.
+- Enrich tagged scopes with additional metadata.
+- Extend language support by adding parsers for more comment styles, including but not limited to:
 
-The only way to define ``Sphinx-Needs`` need items is through ``one-line comment style``.
-Raw RST text and multi-lines comments style are planned to support
+  - Rust
+  - YAML
 
-Export needs.json
------------------
+- Enhance ``.gitignore`` handling to support nested ``.gitignore`` files.
 
-To facilitate CI workflow and enhance the portability of ``need items`` defined in source code,
-we plan to have the feature to export the needs defined in source code to a JSON file.
+Defining Needs in Source Code
+-----------------------------
+
+- Introduce flexible ways to define ``Sphinx-Needs`` items in source code, such as using raw RST text and multi-line comments.
+- Implement a feature to export needs defined in source code to a ``needs.json`` file, improving CI workflows and portability.

docs/source/index.rst

@@ -12,9 +12,11 @@
 
       .. div:: sd-fs-5 sd-font-italic
 
-         ``Sphinx-CodeLinks`` is designed for Engineering-as-Code workflows to facilitate Application Lifecycle Management (ALM).
-         It enables users to define ``Sphinx-Needs`` need items within source code using a single line and automatically extract them
-         into the documentation during the Sphinx build process.
+         ``Sphinx-CodeLinks`` is a lightweight solution for enabling traceability between source code and documentation.
+         With a single line in your code, you can:
+
+         1. Defining new ``Sphinx-Needs`` - extracted and integrated into the Sphinx build
+         2. Embedding existing need IDs - extracted for cross-referencing with need items in the documentation
 
       .. grid:: 1 1 2 2
          :gutter: 2 2 3 3
@@ -63,6 +65,7 @@ Contents
    components/oneline
    components/analyse
    components/discover
+   components/write
 
 .. toctree::
    :maxdepth: 1

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sphinx-codelinks"
-version = "0.1.2"
+version = "1.0.0"
 description = "Fast Source Code Traceability for Sphinx-Needs"
 authors = [{ name = "team useblocks", email = "info@useblocks.com" }]
 maintainers = [