👌Remove the need item for src-trace (#39)

* remove the node from src-trace

- updated TCs
- updated docs

* updated chang_log

* updated fixture for the latest syrups

* Update docs/source/development/change_log.rst

Co-authored-by: Marco Heinemann <[email protected]>

* Update docs/source/development/change_log.rst

Co-authored-by: Marco Heinemann <[email protected]>

* Update docs/source/development/change_log.rst

Co-authored-by: Marco Heinemann <[email protected]>

* Update docs/source/development/change_log.rst

Co-authored-by: Marco Heinemann <[email protected]>

* Update docs/source/development/change_log.rst

Co-authored-by: Marco Heinemann <[email protected]>

* updated ubcode config

---------

Co-authored-by: Marco Heinemann <[email protected]>

Author: juiwenchen

docs/source/basics/quickstart.rst

@@ -45,7 +45,7 @@ Directive
 Example
 -------
 
-.. src-trace:: dummy src
+.. src-trace::
    :project: src
 
 .. note:: **local-url** is not working on the website as it only supports local browse

docs/source/components/directive.rst

@@ -9,15 +9,15 @@ Directive
 
 .. code-block:: rst
 
-   .. src-trace:: example_with_file
+   .. src-trace::
       :project: project_config
       :file: example.cpp
 
 or
 
 .. code-block:: rst
 
-   .. src-trace:: example_with_directory
+   .. src-trace::
       :project: project_config
       :directory: ./example
 
@@ -51,31 +51,27 @@ The ``src-trace`` directive can be used with the **file** option:
 
 .. code-block:: rst
 
-   .. src-trace:: dcdc demo_1
-      :id: SRC_001
+   .. src-trace::
       :project: dcdc
       :file: ./charge/demo_1.cpp
 
 The needs defined in source code are extracted and rendered to:
 
-.. src-trace:: dcdc demo_1
-   :id: SRC_001
+.. src-trace::
    :project: dcdc
    :file: ./charge/demo_1.cpp
 
 The ``src-trace`` directive can be used with the **directory** option:
 
 .. code-block:: rst
 
-   .. src-trace:: dcdc charge
-      :id: SRC_001
+   .. src-trace::
       :project: dcdc
       :directory: ./discharge
 
 The needs defined in source code are extracted and rendered to:
 
-.. src-trace:: dcdc charge
-   :id: SRC_002
+.. src-trace::
    :project: dcdc
    :directory: ./discharge
 

docs/source/development/change_log.rst

@@ -8,6 +8,27 @@ Changelog
 Unreleased
 ----------
 
+New and Improved
+................
+
+- ✨ Added C# parser for ``analyse`` module.
+
+  Need ID references and marked RST blocks can be extracted from C# source files.
+  The comments styles supported are:(``//``, ``/* */``, ``///``)
+
+- ✨ Added YAML parser for ``analyse`` module.
+
+  Need ID references can be extracted from YAML files.
+  The supported comment style is ``#`` as well as inline comment style, e.g. ``key: value # comment``.
+
+- 👌 Directive ``src-trace`` itself does not create need items anymore and only generate need items from the one-line need definition in the given source.
+
+  The need item is removed because:
+
+  - It has no use cases so far.
+  - It creates extra need items users may not actually want in their documentation
+  - It creates errors with some Sphinx-Needs configurations, e.g., when ``need_id_required`` or ``needs_statuses`` is defined.
+
 Fixes
 .....
 
@@ -40,17 +61,17 @@ New and Improved
   The ``write rst`` command writes 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.
+- 👌 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.
+- 👌 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
+- 👌 Unified configuration in TOML
 
   The configuration for ``src-trace`` directive defined in TOML is now compatible with the new ``analyse`` module.
 

docs/ubproject.toml

@@ -5,3 +5,37 @@ ignore = ["block.title_line"]
 
 [needs]
 id_required = true
+
+[parse.extend_directives.src-trace]
+argument = false
+options = true
+content = false
+content_required = false
+parse_content = false
+description = "A directive to generate need items from one-line definition"
+extension = "sphinx-codelinks"                                              # The extension that provides the directive
+
+[parse.extend_directives.video]
+argument = true
+content = false
+options = true
+
+[parse.extend_directives.tabs]
+argument = true
+content = true
+options = true
+
+[parse.extend_directives.typer]
+argument = true
+content = true
+options = true
+
+[parse.extend_directives.button-ref]
+argument = true
+content = true
+options = true
+
+[parse.extend_directives.button-link]
+argument = true
+content = true
+options = true

src/sphinx_codelinks/sphinx_extension/directives/src_trace.py

@@ -1,5 +1,4 @@
 from collections.abc import Callable
-import hashlib
 import os
 from pathlib import Path
 from typing import Any, ClassVar, cast
@@ -8,7 +7,6 @@
 from docutils.parsers.rst import directives
 from packaging.version import Version
 import sphinx
-from sphinx.config import Config as _SphinxConfig
 from sphinx.util.docutils import SphinxDirective
 from sphinx_needs.api import add_need  # type: ignore[import-untyped]
 from sphinx_needs.utils import add_doc  # type: ignore[import-untyped]
@@ -35,42 +33,6 @@
 logger = logging.getLogger(__name__)
 
 
-def _check_id(
-    config: _SphinxConfig,
-    id: str | None,
-    src_strings: list[str],
-    options: dict[str, str],
-    additional_options: dict[str, str],
-) -> None:
-    """Check and set the id for the need.
-
-    src_strings[0] is always the title.
-    src_strings[1] is always the project.
-    """
-    if config.needs_id_required:
-        if id:
-            additional_options["id"] = id
-        else:
-            if "directory" in options:
-                src_strings.append(options["directory"])
-            if "file" in options:
-                src_strings.append(options["file"])
-
-            additional_options["id"] = _make_hashed_id("SRCTRACE_", src_strings, config)
-
-
-def _make_hashed_id(
-    type_prefix: str, src_strings: list[str], config: _SphinxConfig
-) -> str:
-    """Create an ID based on the type and title of the need."""
-    full_title = src_strings[0]  # title is always the first element
-    hashable_content = "_".join(src_strings)
-    hashed = hashlib.sha256(hashable_content.encode("UTF-8")).hexdigest().upper()
-    if config.needs_id_from_title:
-        hashed = full_title.upper().replace(" ", "_") + "_" + hashed
-    return f"{type_prefix}{hashed[: config.needs_id_length]}"
-
-
 def get_rel_path(doc_path: Path, code_path: Path, base_dir: Path) -> tuple[Path, Path]:
     """Get the relative path from the document to the source code file and vice versa."""
     doc_depth = len(doc_path.parents) - 1
@@ -114,13 +76,12 @@ class SourceTracing(nodes.General, nodes.Element):
 
 
 class SourceTracingDirective(SphinxDirective):
-    required_arguments = 1
+    required_arguments = 0
     optional_arguments = 0
     final_argument_whitespace = True
     # this enables content in the directive
-    has_content = True
+    has_content = False
     option_spec: ClassVar[dict[str, Callable[[str], str]] | None] = {
-        "id": directives.unchanged_required,
         "project": directives.unchanged_required,
         "file": directives.unchanged_required,
         "directory": directives.unchanged_required,
@@ -131,8 +92,6 @@ def run(self) -> list[nodes.Node]:
         validate_option(self.options)
 
         project = self.options["project"]
-        id = self.options.get("id")
-        title = self.arguments[0]
         # get source tracing config
         src_trace_sphinx_config = CodeLinksConfig.from_sphinx(self.env.config)
 
@@ -147,12 +106,6 @@ def run(self) -> list[nodes.Node]:
         # the directory where the source files are copied to
         target_dir = out_dir / src_dir.name
 
-        additional_options = {"project": project}
-
-        _check_id(
-            self.env.config, id, [title, project], self.options, additional_options
-        )
-
         source_files = self.get_src_files(self.options, src_dir, src_discover_config)
 
         # add source files into the dependency
@@ -166,20 +119,6 @@ def run(self) -> list[nodes.Node]:
         src_analyse = SourceAnalyse(analyse_config)
         src_analyse.run()
 
-        needs = []
-
-        # create the need for src-trace directive
-        src_trace_need = add_need(
-            app=self.env.app,  # The Sphinx application object
-            state=self.state,  # The docutils state object
-            docname=self.env.docname,  # The current document name
-            lineno=self.lineno,  # The line number where the directive is used
-            need_type="srctrace",  # The type of the need
-            title=title,  # The title of the need
-            **additional_options,
-        )
-        needs.extend(src_trace_need)
-
         dirs = {
             "src_dir": src_dir,
             "out_dir": out_dir,
@@ -233,14 +172,12 @@ def run(self) -> list[nodes.Node]:
             remote_url_field,
             dirs,
         )
-        if rendered_needs:
-            needs.extend(rendered_needs)
 
         # for post-processing of need links
         # https://github.com/useblocks/sphinx-needs/issues/1210
         add_doc(self.env, self.env.docname)
 
-        return needs
+        return rendered_needs
 
     def get_src_files(
         self,

tests/__snapshots__/test_src_trace/test_build_html[sphinx_project0-source_code0].doctree.xml

@@ -1,6 +1,4 @@
 <document source="<source>">
-    <target anonymous="" ids="ST_776C6" refid="ST_776C6">
-    <Need classes="need need-srctrace" ids="ST_776C6" refid="ST_776C6">
     <target anonymous="" ids="IMPL_singleLineExample" refid="IMPL_singleLineExample">
     <Need classes="need need-impl" ids="IMPL_singleLineExample" refid="IMPL_singleLineExample">
     <target anonymous="" ids="IMPL_multiLineExample" refid="IMPL_multiLineExample">
@@ -9,8 +7,6 @@
     <Need classes="need need-impl" ids="IMPL_14" refid="IMPL_14">
     <target anonymous="" ids="IMPL_main_supercharge" refid="IMPL_main_supercharge">
     <Need classes="need need-impl" ids="IMPL_main_supercharge" refid="IMPL_main_supercharge">
-    <target anonymous="" ids="ST_FB728" refid="ST_FB728">
-    <Need classes="need need-srctrace" ids="ST_FB728" refid="ST_FB728">
     <target anonymous="" ids="IMPL_processAssemble" refid="IMPL_processAssemble">
     <Need classes="need need-impl" ids="IMPL_processAssemble" refid="IMPL_processAssemble">
     <target anonymous="" ids="IMPL_filterData" refid="IMPL_filterData">
@@ -21,8 +17,6 @@
     <Need classes="need need-impl" ids="IMPL_processAggregate" refid="IMPL_processAggregate">
     <target anonymous="" ids="IMPL_main_demo2" refid="IMPL_main_demo2">
     <Need classes="need need-impl" ids="IMPL_main_demo2" refid="IMPL_main_demo2">
-    <target anonymous="" ids="ST_9F1BA" refid="ST_9F1BA">
-    <Need classes="need need-srctrace" ids="ST_9F1BA" refid="ST_9F1BA">
     <target anonymous="" ids="IMPL_displayUI" refid="IMPL_displayUI">
     <Need classes="need need-impl" ids="IMPL_displayUI" refid="IMPL_displayUI">
     <target anonymous="" ids="IMPL_backupData" refid="IMPL_backupData">

tests/__snapshots__/test_src_trace/test_build_html[sphinx_project1-source_code1].doctree.xml

@@ -1,6 +1,4 @@
 <document source="<source>">
-    <target anonymous="" ids="ST_670E3" refid="ST_670E3">
-    <Need classes="need need-srctrace" ids="ST_670E3" refid="ST_670E3">
     <target anonymous="" ids="IMPL_1" refid="IMPL_1">
     <Need classes="need need-impl" ids="IMPL_1" refid="IMPL_1">
     <target anonymous="" ids="IMPL_2" refid="IMPL_2">

tests/__snapshots__/test_src_trace/test_build_html[sphinx_project2-source_code2].doctree.xml

@@ -1,5 +1,3 @@
 <document source="<source>">
-    <target anonymous="" ids="ST_670E3" refid="ST_670E3">
-    <Need classes="need need-srctrace" ids="ST_670E3" refid="ST_670E3">
     <target anonymous="" ids="IMPL_1" refid="IMPL_1">
     <Need classes="need need-impl" ids="IMPL_1" refid="IMPL_1">

tests/__snapshots__/test_src_trace/test_build_html[sphinx_project3-source_code3].doctree.xml

@@ -1,5 +1,3 @@
 <document source="<source>">
-    <target anonymous="" ids="SRCTRACE_F70E0" refid="SRCTRACE_F70E0">
-    <Need classes="need need-srctrace" ids="SRCTRACE_F70E0" refid="SRCTRACE_F70E0">
     <target anonymous="" ids="IMPL_1" refid="IMPL_1">
     <Need classes="need need-impl" ids="IMPL_1" refid="IMPL_1">

tests/conftest.py

@@ -58,7 +58,7 @@ def temporary_gitignore(source_directory: Path):
 
 class DoctreeSnapshotExtension(SingleFileSnapshotExtension):
     _write_mode = WriteMode.TEXT
-    _file_extension = "doctree.xml"
+    file_extension = "doctree.xml"
 
     def serialize(self, data, **_kwargs):
         if not isinstance(data, document):
@@ -84,7 +84,7 @@ def snapshot_doctree(snapshot):
 
 class AnchorsSnapshotExtension(SingleFileSnapshotExtension):
     _write_mode = WriteMode.TEXT
-    _file_extension = "anchors.json"
+    file_extension = "anchors.json"
 
     def serialize(self, data, **_kwargs):
         if not isinstance(data, list):