versioned and update docs

Author: juiwenchen

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
 
@@ -28,7 +28,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/development/change_log.rst

@@ -3,7 +3,39 @@
 Changelog
 =========
 
-.. _release:0.1.2:
+.. _`release:1.0.0`:
+
+1.0.0
+-----
+
+:Released: 12.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.
+
+- 🔨 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.
+  Note that the configuration files for ``src-trace`` and the ``analyse`` CLI are not yet compatible; this will be addressed in a future release.
+
+.. _`release:0.1.2`:
 
 0.1.2
 -----
@@ -24,7 +56,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,34 @@
 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
------------------
+- Unify TOML configuration for the ``src-trace`` directive and the ``analyse`` CLI.
+- Support automatic discovery of TOML configuration files (e.g., ``pyproject.toml``).
+- Discourage global configuration in TOML files to promote project-specific settings.
+- 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:
 
-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
+  - SyML
 
-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.

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 = [