Tracing Source Code with Codelinks

Added in version 0.29.0.

This guide walks you through embedding traceability markers in source code and bringing those markers into your documentation as Sphinx-Needs objects. For the full configuration reference, see Codelinks (Source Code Tracing).

What is source code tracing?

In a Docs-as-Code workflow, requirements, specifications, and test cases usually live in reStructuredText files. But the code that implements those requirements lives somewhere else — in .py, .cpp, .rs, or other source files. When you need to prove that a requirement is covered by code (or that a piece of code relates to a specific requirement), you have to maintain that mapping by hand.

Source code tracing solves this by letting you embed traceability markers directly in code comments. ubCode’s Rust engine scans those comments, extracts the markers, and converts them into proper need objects — complete with IDs, types, links, and metadata. You get a live, bidirectional link between your documentation and your code without any manual bookkeeping.

Marker types

Codelinks supports three kinds of markers. Each one serves a different purpose.

One-line need definitions

A one-line marker creates a new need from a single comment line. Fields are positional, separated by the field_split_char (comma by default).

Source code (Python)

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

Resulting need (equivalent RST)

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

With the default configuration this produces a need with:

• Title: Function Bar

• ID: IMPL_4

• Type: impl

• Links: SPEC_1

The field order, separator, and start/end sequences are all configurable via [codelinks.projects.<name>.analyse.oneline_comment_style] — see analyse.oneline_comment_style for the full reference.

Defaults and optional fields: Fields with a default value can be omitted from the right-hand side. For example, if type defaults to "impl" and links defaults to [], then:

# @Function Bar, IMPL_4

is enough to create the same impl need, just without links.

Escaping: If a field value contains the split character (,) or square brackets, escape them with a backslash:

# @Title\, with comma, IMPL_5, impl, []

This produces a need titled Title, with comma.

Need ID references

A need-ID reference links a code location to existing needs without creating new ones. It records that this spot in the code is related to the listed requirements.

Source code (C++)

// @need-ids: REQ_001, REQ_002

Effect

The code location is linked to needs REQ_001 and REQ_002. No new needs are created.

The marker keyword (@need-ids: by default) is configurable in [codelinks.projects.<name>.analyse.need_id_refs] — see analyse.need_id_refs.

Supported languages

Codelinks recognises the comment syntax of several programming languages. Set the comment_type in [codelinks.projects.<name>.source_discover] to tell ubCode which language to expect.

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

The .. src-trace:: directive

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

.. src-trace::
   :project: my_app

This inserts all needs discovered by the my_app codelinks project.

Scope the results to a single file or a subdirectory:

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

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

Multiple .. src-trace:: directives can appear in the same document to combine needs from different projects or scopes.

Note

The :file: and :directory: options are mutually exclusive — use one or the other, not both.

See The .. src-trace:: directive for the full directive reference.

How it works under the hood

When ubCode encounters a .. src-trace:: directive, it runs the codelinks pipeline:

1. Discover — walk the configured src_dir, applying include/exclude patterns and .gitignore rules, to find source files.

2. Parse — read each file and extract markers (one-line needs, need-ID references) according to the language’s comment syntax.

3. Cache — store results per file. On subsequent runs, only changed files are re-parsed (based on modification time), so incremental updates are fast.

4. Attach URLs — if set_local_url or set_remote_url is enabled, compute file URLs using the configured patterns.

5. Convert — transform extracted markers into proper need items and merge them into the needs index.

The entire pipeline runs in Rust and executes in parallel, so even large codebases are traced in milliseconds.

ubCode vs. Sphinx-Codelinks

The codelinks marker format was introduced by Sphinx-Codelinks, a Sphinx extension. ubCode reimplements the same analysis pipeline in Rust and integrates it directly into its engine.

Aspect	Sphinx-Codelinks	ubCode codelinks
Installation	pip install sphinx-codelinks	Built into ubCode (VS Code extension, ubc CLI, MCP)
Configuration	codelinks.toml referenced from conf.py	[codelinks] section in ubproject.toml
When it runs	During sphinx-build	In real time as you edit (VS Code), on demand (CLI), or via MCP
Performance	Python-based, runs during Sphinx build	Rust-based, incremental, parallel; millisecond-scale updates
Marker format	Same (one-line needs, need-ID refs)	Same (one-line needs, need-ID refs)

Both can coexist. Use ubCode for fast feedback while editing, and Sphinx-Codelinks for the final Sphinx build. The marker format is identical, so source files do not need any changes.

Getting started

Follow these steps to set up codelinks in your project.

1. Define a codelinks project in your ubproject.toml:

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

2. Configure source discovery so ubCode knows where to look and what language to expect:

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

3. Configure the analysis to select the marker types you want:

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

4. Add markers in your source code:

   # @Validate user input, IMPL_AUTH, impl, [REQ_AUTH]
   

5. Include traced needs in your documentation:

   .. src-trace::
      :project: my_app
   

6. Enable remote URLs (optional) so each traced need links back to GitHub/GitLab:

   [codelinks]
   set_remote_url = true
   

See Codelinks (Source Code Tracing) for the full configuration reference and Complete example for a complete example.

Real-time diagnostics

Added in version 0.30.0.

When you open or edit a source file that belongs to a codelinks project, ubCode validates one-line markers in real time and reports problems as warnings directly in the editor. Diagnostics appear inline and in the Problems panel, just like RST lint rules.

The following warning codes are reported:

Code	Description
too_few_fields	The marker has fewer fields than the configured field layout requires.
too_many_fields	The marker has more fields than expected.
missing_square_brackets	A list field (e.g. links) is missing its surrounding [ ].
not_start_or_end_with_square_brackets	A list field has brackets on only one side.
newline_in_field	A field value contains a line break, which is not allowed in one-line markers.

All diagnostics use the source label ubcode-codelinks.

Note

Diagnostics require the VS Code extension’s document selector to include the language of the source file. The default selector covers all languages listed in Supported languages above. If you have overridden ubcode.server.documentSelector in your settings, make sure the relevant language IDs are included.

Source code outside the docs folder

In most projects, source code lives in a different directory tree than the documentation. ubCode normally discovers configuration by walking up parent directories until it finds a ubproject.toml. For files outside that tree (such as ../src/main.py), the walk fails because no ubproject.toml exists above them.

To handle this, place a ubproject.redirect.toml in the source directory:

# src/ubproject.redirect.toml
path = "../docs"

This tells ubCode to look for the configuration in the docs/ directory. See Configuration redirect with ubproject.redirect.toml for details.

Further reading

• Codelinks (Source Code Tracing) — the full [codelinks] configuration reference.

• Complete example — a complete, annotated ubproject.toml example.

• Key Concepts — source code tracing concepts alongside needs, links, and RST.

• Codelinks documentation — the standalone Sphinx-Codelinks reference, covering the Sphinx extension, CLI, and advanced topics.