Tracing Source Code

This guide explains how to use CodeLinks to trace source code files and lines to needs in your documentation.

Step 1: Install CodeLinks

Follow the installation instructions in the CodeLinks documentation.

Step 2: Configure CodeLinks

Create a file named src_trace.toml in your docs folder (next to conf.py) with the following content:

src_trace.toml

[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.eac-cpp]
remote_url_pattern = "https://github.com/useblocks/eac/blob/{commit}/{path}#L{line}" # URL pattern for remote source code

[codelinks.projects.eac-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.eac-cpp.analyse]
get_need_id_refs = true
get_oneline_needs = true
get_rst = true

[codelinks.projects.eac-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" = [] },
]

Step 3: Add the src-trace Directive

In your documentation files, add the following directive to display traced source code links:

.. src-trace::
     :project: eac-cpp
     :directory: .

Step 4: Annotate Your Source Code

Add comments to your source code files to link code lines to needs. For example, in src/main.cpp:

src/main.cpp

#include <iostream>

// @Adding two integers, IMPL_1, impl, [REQ_0815]
int add(int a, int b) {
    return a + b;
}

int main() {
  
    std::cout << "Hello World" << std::endl;

    return 0;
}

Step 5: View Traced Files and Lines

After following the steps above, the documentation will show the traced files and lines for each need in the specified project (eac-cpp). Here we show only the implementation files (not test files):

Implementation: Adding two integers IMPL_1

remote-url: src/main.cpp#L3; links outgoing: REQ_0815

Implementation: Calculate Factorial IMPL_2

remote-url: src/sample1.cpp#L4; links incoming: T_FACT_001, T_FACT_002, T_FACT_003

Implementation: Check if prime IMPL_3

remote-url: src/sample1.cpp#L15; links incoming: T_PRIME_001, T_PRIME_002, T_PRIME_003

Implementation: Clone C string IMPL_4

remote-url: src/sample2.cpp#L7;

Implementation: Set C string IMPL_5

remote-url: src/sample2.cpp#L20;

Note: Test files are traced separately in the testing guide to avoid duplicate need IDs.

Summary

By following these steps, you can easily trace source code to requirements, improving traceability and documentation quality.

Advanced configuration options and features are available in the CodeLinks documentation.

Linking Requirements to Code

Finally you can link from/to the traced source code lines like this:

Requirement: Requirement linking to source code REQ_0815

status: open links incoming: IMPL_1

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.