Codelinks (Source Code Tracing)¶

Added in version 0.29.0.

The [codelinks] section configures source code tracing — scanning your source files for traceability markers and converting them into needs. Use this when you want to create or link needs directly from code comments, without writing reStructuredText by hand.

Minimal example¶

[codelinks]
set_remote_url = true

[codelinks.projects.my_app]
remote_url_pattern = "https://github.com/org/repo/blob/{commit}/{path}#L{line}"

[codelinks.projects.my_app.source_discover]
src_dir = "../src"
comment_type = "python"

[codelinks.projects.my_app.analyse]
get_oneline_needs = true

This tells ubCode to scan the ../src directory for Python files, extract one-line need markers from comments, and generate remote URLs pointing to GitHub.

In your reStructuredText files you then include the traced needs with the .. src-trace:: directive:

.. src-trace::
   :project: my_app

Global options¶

These options sit directly under [codelinks] and apply to every project defined within it.

set_local_url

Type: boolean (default: false)

When true, ubCode computes a file:// URL pointing to the local source file for every traced need. The URL is stored in the field named by local_url_field.

[codelinks]
set_local_url = true

local_url_field

Type: string (default: "local-url")

Name of the need field that receives the local file URL. The field is auto-registered in [needs.fields] when set_local_url is enabled; if it already exists with a non-string type, a diagnostic is emitted.

[codelinks]
local_url_field = "local-url"

set_remote_url

Type: boolean (default: false)

When true, ubCode computes a remote URL (e.g. GitHub, GitLab, Bitbucket) for every traced need using the remote_url_pattern defined on each project. The URL is stored in the field named by remote_url_field.

[codelinks]
set_remote_url = true

remote_url_field

Type: string (default: "remote-url")

Name of the need field that receives the remote URL. The field is auto-registered in [needs.fields] when set_remote_url is enabled; if it already exists with a non-string type, a diagnostic is emitted.

[codelinks]
remote_url_field = "remote-url"

outdir

Type: string or null (default: null)

Optional output directory for generated artifacts such as extracted markers and warnings (standalone use only). Most users do not need to set this.

[codelinks]
outdir = "output"

Project-specific options¶

Each source code project is defined under [codelinks.projects.<name>], where <name> is a unique identifier you choose (e.g. my_app, backend). You can define multiple projects when your repository contains several codebases with different languages or configurations.

[codelinks.projects.my_app]
# options for "my_app"

[codelinks.projects.backend]
# options for "backend"

remote_url_pattern¶

Type: string or null (default: null)

URL pattern used to generate links to a remote source code repository. The pattern uses placeholders that ubCode replaces with the actual values at analysis time.

Placeholders:

{commit} — the current Git commit hash
{path} — relative path to the source file (from the repository root)
{line} — 1-based line number of the marker

Common patterns:

GitHub: https://github.com/user/repo/blob/{commit}/{path}#L{line}
GitLab: https://gitlab.com/user/repo/-/blob/{commit}/{path}#L{line}
Bitbucket: https://bitbucket.org/user/repo/src/{commit}/{path}#lines-{line}

[codelinks.projects.my_app]
remote_url_pattern = "https://github.com/org/repo/blob/{commit}/{path}#L{line}"

source_discover¶

Configures how ubCode discovers source files within this project.

[codelinks.projects.my_app.source_discover]
src_dir = "../src"
include = ["**/*.cpp", "**/*.h"]
exclude = ["build/**"]
gitignore = true
comment_type = "cpp"

src_dir

Type: string (default: ".")

Root directory for source file discovery. Paths are resolved relative to the directory containing the ubproject.toml file.

[codelinks.projects.my_app.source_discover]
src_dir = "../src"

include

Type: array of strings (default: [])

Glob patterns for files to include. When non-empty, only files matching at least one pattern are processed. An empty list includes all files (subject to exclude and gitignore filtering).

Files must match at least one include pattern to be considered, but exclude patterns and gitignore rules still apply afterward.

[codelinks.projects.my_app.source_discover]
include = ["**/*.py"]

exclude

Type: array of strings (default: [])

Glob patterns for files and directories to exclude from discovery.

[codelinks.projects.my_app.source_discover]
exclude = ["build/**", "vendor/**"]

gitignore

Type: boolean (default: true)

When true, files matched by .gitignore (and .ignore, .git/info/exclude, and global gitignore) are automatically excluded.

[codelinks.projects.my_app.source_discover]
gitignore = false

comment_type

Type: string or null (default: null)

The programming language / comment style used in this project’s source files. This determines which file extensions are discovered and how comments are parsed for markers.

This field is required for file discovery. When null, the discovery step fails with an error; set it to one of the supported values below.

Supported values:

Language	Value	Comment syntax	Discovered file extensions
C / C++	`"cpp"`	`//` (single-line), `/* */` (multi-line)	`.cpp`, `.hpp`, `.h`, `.cc`, `.hh`, `.c++`, `.h++`
Python	`"python"`	`#` (single-line), `""" """` (docstrings)	`.py`
Rust	`"rust"`	`//` (single-line), `/* */` (multi-line), `///` and `//!` (doc comments)	`.rs`
C#	`"csharp"`	`//` (single-line), `/* */` (multi-line), `///` (XML doc comments)	`.cs`
YAML	`"yaml"`	`#` (single-line)	`.yaml`, `.yml`

[codelinks.projects.my_app.source_discover]
comment_type = "python"

analyse¶

Configures how ubCode analyses source files to extract markers from comments.

[codelinks.projects.my_app.analyse]
get_oneline_needs = true
get_need_id_refs = true
get_rst = false

get_oneline_needs

Type: boolean (default: true)

Whether to extract one-line needs from comments. A one-line need is a compact marker like:

// @Function Bar, IMPL_4, impl, [SPEC_1]

which ubCode converts to a need with title “Function Bar”, ID IMPL_4, type impl, and a link to SPEC_1. The marker format is controlled by oneline_comment_style below.

get_need_id_refs

Type: boolean (default: true)

Whether to extract need-ID reference markers from comments. A need-ID reference links a code location to existing needs without creating new ones:

// @need-ids: REQ_001, REQ_002

The marker strings are configured via need_id_refs.markers.

get_rst

Type: boolean (default: false)

Whether to extract marked RST blocks from comments. A marked RST block lets you embed full reStructuredText inside a source code comment:

// @rst
// .. req:: My Requirement
//    :id: REQ_INLINE
//
//    This requirement lives in source code.
// @endrst

The start and end sequences are configured via marked_rst.

git_root

Type: string or null (default: null)

Explicit path to the Git repository root. Useful in non-standard layouts (e.g. Bazel builds, monorepo sub-projects) where auto-detection of .git would fail. When null, ubCode traverses parent directories automatically. Paths are resolved relative to the ubproject.toml file.

[codelinks.projects.my_app.analyse]
git_root = "/path/to/repo"

analyse.oneline_comment_style¶

Defines the format of one-line markers. Fields are positional: the order in needs_fields determines which comma-separated value maps to which need field.

[codelinks.projects.my_app.analyse.oneline_comment_style]
start_sequence = "@"
end_sequence = "\n"
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 = [] },
]

With this configuration, the comment:

// @Function Bar, IMPL_4, impl, [SPEC_1, SPEC_2]

produces a need equivalent to:

.. impl:: Function Bar
   :id: IMPL_4
   :links: SPEC_1, SPEC_2

start_sequence

Type: string (default: "@")

Character sequence that begins a one-line marker inside a comment.

end_sequence

Type: string (default: "\n")

Character sequence that ends a one-line marker. The default (newline) means each marker occupies a single comment line.

field_split_char

Type: string (default: ",")

Character used to split the marker into individual field values.

needs_fields

Type: array of objects (at least 1 entry required)

Ordered list of field definitions. Each entry describes one positional field in the marker:

name

Type: string (required)

The need field to populate (e.g. "title", "id", "type").

"str"-typed fields must exist in [needs.fields], and "list[str]"-typed fields must exist in [needs.links]; missing entries produce a warning diagnostic at startup.

type

Type: "str" or "list[str]" (default: "str")

"str" — a plain string value.
"list[str]" — a bracketed, comma-separated list (e.g. [SPEC_1, SPEC_2]).

default

Type: string, array of strings, or null (default: null)

Default value when the field is omitted from the marker. null means the field is required.

Important

The title and type fields (or their equivalents) must always be present in needs_fields, as they are mandatory for every need.

analyse.need_id_refs¶

Configures how need-ID reference markers are recognised.

[codelinks.projects.my_app.analyse.need_id_refs]
markers = ["@need-ids:"]

markers

Type: array of strings (at least 1 entry required, default: ["@need-ids:"])

Marker strings that identify need-ID references in comments. When ubCode encounters a comment containing one of these markers, everything after the marker is parsed as a comma-separated list of need IDs.

// @need-ids: REQ_001, REQ_002

analyse.marked_rst¶

Configures the delimiters for marked RST blocks embedded in comments.

[codelinks.projects.my_app.analyse.marked_rst]
start_sequence = "@rst"
end_sequence = "@endrst"

start_sequence

Type: string (default: "@rst")

Sequence that begins a marked RST block inside a comment.

end_sequence

Type: string (default: "@endrst")

Sequence that ends a marked RST block.

The `.. src-trace::` directive¶

Once you have configured a codelinks project, include the traced needs in your documentation using the .. src-trace:: directive:

.. src-trace::
   :project: my_app

The directive accepts the following options:

:project:

Required. The project name as defined under [codelinks.projects.<name>].

:file:

Limit tracing to a single source file (relative to src_dir).

.. src-trace::
   :project: my_app
   :file: main.cpp

:directory:

Limit tracing to files within a subdirectory (relative to src_dir).

.. src-trace::
   :project: my_app
   :directory: core/

When neither :file: nor :directory: is given, all files under src_dir are included. Multiple .. src-trace:: directives can appear in the same document to combine needs from different projects or scopes.

Note

The :file: and :directory: options cannot be used together on the same directive.

Automatic field registration¶

When set_local_url or set_remote_url is enabled, ubCode automatically adds the corresponding URL field (local_url_field / remote_url_field) to [needs.fields] as a string field. You do not need to declare it manually.

If the field already exists with a compatible string type, the existing definition is kept unchanged. If it exists with a non-string type, a warning diagnostic is emitted.

Similarly, "str"-typed entries in needs_fields are cross-validated against [needs.fields], and "list[str]"-typed entries are cross-validated against [needs.links]. Missing entries produce warning diagnostics at startup so you can add the field or link type definition before tracing fails.

Complete example¶

"$schema" = "https://ubcode.useblocks.com/ubproject.schema.json"

[needs]
id_required = true

[[needs.types]]
directive = "impl"
title = "Implementation"
prefix = "IMPL_"

[[needs.types]]
directive = "req"
title = "Requirement"
prefix = "REQ_"

[needs.fields.source_file]
description = "Source file for codelinks needs"

[needs.links.implements]
incoming = "implemented by"
outgoing = "implements"

# --- Codelinks configuration ---

[codelinks]
set_remote_url = true
remote_url_field = "remote-url"

[codelinks.projects.my_app]
remote_url_pattern = "https://github.com/org/repo/blob/{commit}/{path}#L{line}"

[codelinks.projects.my_app.source_discover]
src_dir = "../src"
include = ["**/*.cpp", "**/*.h"]
gitignore = true
comment_type = "cpp"

[codelinks.projects.my_app.analyse]
get_oneline_needs = true
get_need_id_refs = true
get_rst = false

[codelinks.projects.my_app.analyse.oneline_comment_style]
start_sequence = "@"
field_split_char = ","
needs_fields = [
    { name = "title", type = "str" },
    { name = "id", type = "str" },
    { name = "type", type = "str", default = "impl" },
    { name = "implements", type = "list[str]", default = [] },
]

[codelinks.projects.my_app.analyse.need_id_refs]
markers = ["@need-ids:"]

[codelinks.projects.my_app.analyse.marked_rst]
start_sequence = "@rst"
end_sequence = "@endrst"

Codelinks (Source Code Tracing)¶

Minimal example¶

Global options¶

Project-specific options¶

remote_url_pattern¶

source_discover¶

analyse¶

analyse.oneline_comment_style¶

analyse.need_id_refs¶

analyse.marked_rst¶

The .. src-trace:: directive¶

Automatic field registration¶

Complete example¶

The `.. src-trace::` directive¶