From 54ed3c11d1d980aeeaa33a882b6487ed60125afe Mon Sep 17 00:00:00 2001
From: Marco Heinemann <marco.heinemann@useblocks.com>
Date: Tue, 5 May 2026 16:40:43 +0200
Subject: [PATCH] Migrate codelinks config into ubproject.toml

Consolidate the source-tracing config into the single ubproject.toml so
ubCode and sphinx-codelinks read from the same place, and add the
ubproject.redirect.toml in src/ introduced in ubCode 0.29.0b1 so the
language server can resolve the project config when editing source files
outside the docs folder.

Drop the parse.ignore_directives suppression for src-trace and the
'ubCode is not aware' limitation note now that codelinks support has
landed in ubCode.
---
 docs/conf.py                            |  2 +-
 docs/how-to-guides/trace-code/index.rst | 17 +++-------
 docs/src_trace.toml                     | 36 ---------------------
 docs/ubproject.toml                     | 43 +++++++++++++++++++++----
 src/ubproject.redirect.toml             |  1 +
 5 files changed, 44 insertions(+), 55 deletions(-)
 delete mode 100644 docs/src_trace.toml
 create mode 100644 src/ubproject.redirect.toml

diff --git a/docs/conf.py b/docs/conf.py
index f715299..298a10f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -63,7 +63,7 @@
     },
 }
 
-src_trace_config_from_toml = "src_trace.toml"
+src_trace_config_from_toml = "ubproject.toml"
 
 ###############################################################################
 # SPHINX-NEEDS Config END
diff --git a/docs/how-to-guides/trace-code/index.rst b/docs/how-to-guides/trace-code/index.rst
index 5bd6f5f..91bea04 100644
--- a/docs/how-to-guides/trace-code/index.rst
+++ b/docs/how-to-guides/trace-code/index.rst
@@ -12,12 +12,13 @@ Follow the installation instructions in the `CodeLinks documentation <https://co
 
 **Step 2: Configure CodeLinks**
 
-Create a file named ``src_trace.toml`` in your ``docs`` folder (next
-to ``conf.py``) with the following content:
+Add a ``[codelinks]`` section to your ``ubproject.toml`` (next to
+``conf.py``) with the following content:
 
-.. literalinclude:: ../../src_trace.toml
+.. literalinclude:: ../../ubproject.toml
    :language: toml
-   :caption: src_trace.toml
+   :caption: ubproject.toml (codelinks section)
+   :start-at: "[codelinks]"
 
 **Step 3: Add the src-trace Directive**
 
@@ -78,11 +79,3 @@ Finally you can link from/to the traced source code lines like this:
 
    This is a requirement that links to a need that has traced source code
    lines.
-
-.. note::
-
-   Current limitation: ``ubCode`` is not aware of this need id yet. This
-   means that the ``ubCode`` navigation inside Visual Studio Code will
-   not work and jumping from this ``rst`` file to the source code line
-   will not work. This will be implemented and supported in a future
-   release.
diff --git a/docs/src_trace.toml b/docs/src_trace.toml
deleted file mode 100644
index 69c7b66..0000000
--- a/docs/src_trace.toml
+++ /dev/null
@@ -1,36 +0,0 @@
-[codelinks]
-# Configuration for source tracing
-set_local_url = false             # Set to true to enable local code html and URL generation
-local_url_field = "local"        # Need's field name for local URL
-set_remote_url = true           # Set to true to enable remote url to be generated
-remote_url_field = "remote-url" # Need's field name for remote URL
-
-
-[codelinks.projects.x-as-code-cpp]
-remote_url_pattern = "https://github.com/useblocks/x-as-code/blob/{commit}/{path}#L{line}" # URL pattern for remote source code
-
-[codelinks.projects.x-as-code-cpp.source_discover]
-src_dir = "../src" # Relative path from this TOML config to the source directory
-include = [
-    "*.cpp",
-    "*.h"
-]
-exclude=[]
-gitignore = true
-comment_type = "cpp"
-
-[codelinks.projects.x-as-code-cpp.analyse]
-get_need_id_refs = true
-get_oneline_needs = true
-get_rst = true
-
-[codelinks.projects.x-as-code-cpp.analyse.oneline_comment_style]
-# start_sequence = "@"
-# end_sequence for the online comments; default is an os-dependant newline character
-field_split_char = ","
-needs_fields = [
-   { "name" = "title", "type" = "str" },
-   { "name" = "id", "type" = "str" },
-   { "name" = "type", "type" = "str", "default" = "impl" },
-   { "name" = "links", "type" = "list[str]", "default" = [] },
-]
\ No newline at end of file
diff --git a/docs/ubproject.toml b/docs/ubproject.toml
index 0975b09..4c78984 100644
--- a/docs/ubproject.toml
+++ b/docs/ubproject.toml
@@ -13,12 +13,6 @@ name = "X-as-Code (XaC)"
 description = "Showcases for working with Sphinx-Needs"
 srcdir = "."
 
-[parse]
-ignore_directives = [
-  # src-trace is not recognized by ubcode and produces a warning lint.
-  "src-trace"
-]
-
 # Rules for the ubCode formater, to get a nice looking documentation.
 [format_rst]
 fail_on_warning = []
@@ -408,3 +402,40 @@ src = "."
 # ubCode setting: run a script command
 [scripts]
 sphinx = "sphinx-build -b html . _build/html"
+
+[codelinks]
+# Configuration for source tracing
+set_local_url = false             # Set to true to enable local code html and URL generation
+local_url_field = "local"        # Need's field name for local URL
+set_remote_url = true           # Set to true to enable remote url to be generated
+remote_url_field = "remote-url" # Need's field name for remote URL
+
+
+[codelinks.projects.x-as-code-cpp]
+remote_url_pattern = "https://github.com/useblocks/x-as-code/blob/{commit}/{path}#L{line}" # URL pattern for remote source code
+
+[codelinks.projects.x-as-code-cpp.source_discover]
+src_dir = "../src" # Relative path from this TOML config to the source directory
+include = [
+    "*.cpp",
+    "*.h"
+]
+exclude=[]
+gitignore = true
+comment_type = "cpp"
+
+[codelinks.projects.x-as-code-cpp.analyse]
+get_need_id_refs = true
+get_oneline_needs = true
+get_rst = true
+
+[codelinks.projects.x-as-code-cpp.analyse.oneline_comment_style]
+# start_sequence = "@"
+# end_sequence for the online comments; default is an os-dependant newline character
+field_split_char = ","
+needs_fields = [
+   { "name" = "title", "type" = "str" },
+   { "name" = "id", "type" = "str" },
+   { "name" = "type", "type" = "str", "default" = "impl" },
+   { "name" = "links", "type" = "list[str]", "default" = [] },
+]
diff --git a/src/ubproject.redirect.toml b/src/ubproject.redirect.toml
new file mode 100644
index 0000000..19cee48
--- /dev/null
+++ b/src/ubproject.redirect.toml
@@ -0,0 +1 @@
+path = "../docs"