Codelinks (source code tracing)

VS Code CLI MCP Beta

Added in version 0.29.0.

Every key, with its type and default: [codelinks].

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.

See also

Codelinks documentation

The full Sphinx-Codelinks documentation, covering the Sphinx extension, CLI, and marker formats in depth.

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}"

ref_url_field

Type: string (default: "code_url")

Name of the need field that receives the URL resolved from a @need-ids: reference marker (see analyse.need_id_refs).

When a source file carries a @need-ids: REQ_X marker, the marker’s remote URL (or its local URL, when no remote URL is configured) is written onto the already existing need REQ_X under this field. This differs from local_url_field / remote_url_field, which receive the URLs of needs defined in the source code (one-line markers and .. src-trace:: blocks); ref_url_field receives the URL back-attached onto a referenced need.

A need referenced from several places gets the URL of one reference: the one with the smallest path (relative to the project’s root — its git_root, else the git root above src_dir, else src_dir — compared as text), then row, then column, then project name, across every file and every codelinks project of the build. Sphinx-Codelinks keeps every reference, in that order, as a list; ubCode keeps the list’s first entry.

Point a tests/-scoped project at a different field (e.g. test_url) to keep links to test code separate from links to implementation code.

[codelinks.projects.my_app]
ref_url_field = "code_url"

[codelinks.projects.my_app_tests]
ref_url_field = "test_url"

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: language-dependent — see below)

Glob patterns for files and directories to exclude from discovery.

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

include and exclude patterns are matched against each file’s path relative to src_dir: build/** names <src_dir>/build, **/build/** a build directory at any depth below src_dir, and a directory above src_dir never matches.

Note

When exclude is not set, the default depends on this project’s comment_type:

• comment_type = "typescript" (which also discovers .js/.jsx/ .mjs/.cjs files) defaults to ["**/node_modules/**", "**/dist/**", "**/build/**", "**/out/**", "**/coverage/**"]. Without this default, checked-in bundler/tsc output would be scanned as source alongside the .ts it was generated from, producing duplicate need ids for the same marker.

• Every other comment_type — and projects that leave comment_type unset — default to an empty list, i.e. no exclusions at all.

This default is deliberately scoped to the TypeScript/JavaScript family rather than applied globally: the directory names above are specific to JS/TS build tooling and do not generalize. Applying them to every language would silently drop real source. In particular, **/lib/** is not in the default list even for TypeScript projects — lib is a common tsc/bundler outDir, but it is at least as common a name for a hand-written source directory, both within the JS/TS ecosystem and especially outside it (many C/C++ projects keep hand-written library source under lib/). A project whose build actually outputs to lib/ should add "**/lib/**" to exclude explicitly.

Setting exclude explicitly — including to [] — replaces whichever default would otherwise apply, rather than adding to it.

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

follow_links

Type: boolean (default: false)

When true, symbolic links are followed when traversing the source directory tree. By default, symbolic links are not followed.

[codelinks.projects.my_app.source_discover]
follow_links = true

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
Go	"go"	// (single-line), /* */ (multi-line)	.go
Bash / Shell	"bash"	# (single-line)	.sh, .bash, .zsh, .ksh
TypeScript / JavaScript	"typescript" (or "ts")	// (single-line), /* */ (multi-line), /** */ (JSDoc), <!-- (legacy single-line, JavaScript)	.ts, .tsx, .mts, .cts, .js, .jsx, .mjs, .cjs

[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_multiline_needs = 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_multiline_needs

Type: boolean (default: false)

Added in version 0.37.0.

Whether to extract multi-line needs from comments. A multi-line need is one need written across the lines of a comment: an open line @need[<markup>] <type>: <title>, option lines :<key>: <value>, a body in the declared markup, and a close line @endneed:

/**
 * @need req: Login must be rate limited
 * :id: REQ_LOGIN_1
 * :links: SPEC_AUTH
 *
 * After **five** failed attempts the account is locked.
 * @endneed
 */

def backoff():
    """@need[md] impl: Exponential back-off
    :id: IMPL_BACKOFF

    Doubles the delay after each failure.
    @endneed
    """

A block forms inside one block comment, one Python docstring, or a run of line comments (//, ///, //!, #) on consecutive rows with the same delimiter and nothing but whitespace before each. The comment prefix is stripped by the comment’s kind (a line comment loses its delimiter and one space; a * leader is stripped only when every line of the block comment carries one). An option line may be indented; a line indented deeper than its option line continues the value; a blank line ends the options. The body is dedented, and a body line starting with \@endneed keeps the close word as text. Refused blocks are reported as warnings (see the codelinks warnings).

With this option on, the lines of a formed block are no longer read for one-line needs or need-ID references. Each formed block a src-trace reads becomes a need (see the multi-line needs a src-trace renders): its options are read like a need directive’s, its body is parsed in the block’s markup — the doctype its markups entry names, routed through [parse.parsers] as a document of that suffix would be (a markup no parser claims falls back to the page’s, with a warning) — and rendered on its card, and every finding about it is reported at the source file and line. The labels its body defines register with the page that renders the card, after the page’s own (see the multi-line needs a src-trace renders). A body is restricted: it cannot read files (include, literalinclude, csv-table with :file:, raw are refused), its images and other assets are not resolved — there is no setting that allows them yet — and a need directive written in it is reported and not executed. The words and markups are configured via multiline_needs. Turning the option on also enables the shared-marker check for the one-line words: a one-line start or end sequence equal to a need-ID reference marker is a fatal configuration check (as Sphinx-Codelinks always refuses it). A file claimed by two codelinks projects is parsed once, with the settings of whichever project parses it first.

The removed get_rst key (the never-implemented marked-RST blocks) is reported: get_rst = true (or any value but false) is reported (warning[config]), and that codelinks project is skipped — its src-trace directives create nothing; under the default --deny warning the build fails, under --deny error it does not. get_rst = false asks for nothing, but it is still a warning[config], once per codelinks project, under the code config.codelinks_removed_key: it fails a default --deny warning build until the line is deleted or the code is ignored (ignore = ["config.codelinks_removed_key"] under [lint]). Projects scaffolded by ubc agent before this release carry the line twice; ubc agent update does not rewrite ubproject.toml.

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.

Note

For C/C++, C# and Go, the default start_sequence = "@" meets the languages’ @-prefixed documentation commands (Doxygen’s @param, swaggo’s @Description), and a comma in their text makes a phantom need; ubCode warns about it. Set start_sequence = "@@". Not "[[" for C/C++: commented-out attribute syntax such as // [[nodiscard]] int add(int a, int b); would be read as a marker.

Note

For comment_type = "typescript", the default start_sequence = "@" is JSDoc’s own sigil (@param, @returns, @deprecated): a JSDoc tag line the one-line parser would read as a marker or warn about (a comma, say) is a jsdoc_tag warning rather than a need, and one it would ignore stays silent. Under any other start sequence the check does not run. Set a start_sequence JSDoc does not use, such as "@@" or "[[" (not "@need": with get_multiline_needs on, that is the multi-line open word, and the configuration is refused). Under "[[", a JSDoc line that names ECMAScript’s internal-slot notation ([[Prototype]] and a comma) is read as a marker.

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.multiline_needs

Added in version 0.37.0.

Configures the words and markups of multi-line needs (read only when get_multiline_needs is on).

[codelinks.projects.my_app.analyse.multiline_needs]
start_sequence = "@need"
end_sequence = "@endneed"
default_markup = "rst"
markups = { rst = ".rst", md = ".md" }

start_sequence

Type: string (default: "@need")

The word that opens a multi-line need, at the start of a comment line. It counts only as a whole word, followed by [, whitespace or the line end, so @need-ids: never opens a block.

end_sequence

Type: string (default: "@endneed")

The word that closes a multi-line need, alone on its line.

default_markup

Type: string (default: "rst")

The markup of a block whose open line names none, or names one markups does not know. It must be a key of markups.

markups

Type: table of string (default: { rst = ".rst", md = ".md" })

The markups an open line may declare (@need[md] impl: ...), each mapped to the doctype the need’s content is parsed with (a non-empty suffix). A table given here replaces the default one: it is not merged into it.

With get_multiline_needs on, these are fatal checks for the codelinks project (each is reported as warning[config], and the project is skipped): the two words being equal, an empty word or default_markup, an empty markups table or suffix, a default_markup that is no key of markups, and either word equal to a one-line start_sequence or end_sequence or to a need-ID reference marker. A word that merely starts with another marker is fine: the default one-line start @ is a prefix of @need, and a formed block’s lines are never read by the one-line parser.

The removed [analyse.marked_rst] table is reported the same way (warning[config], and that codelinks project is skipped); use [analyse.multiline_needs] instead.

analyse.preprocessor

Added in version 0.31.0.

By default, C/C++ files are scanned with a tree-sitter parser that finds markers in every comment — including comments inside #if / #ifdef branches that the compiler would never build.

Adding the [codelinks.projects.<name>.analyse.preprocessor] table, even when it is empty, switches C/C++ files to a preprocessor-aware libclang engine that sees the source as a compiler does: markers in inactive #if / #ifdef branches are excluded, and only markers in the branches that are actually compiled become needs.

[codelinks.projects.my_app.analyse.preprocessor]
# An empty table is enough — its presence selects the libclang engine.

Only files discovered as C/C++ (comment_type = "cpp") use this engine; files of every other language continue to use tree-sitter.

compile_commands

Type: string or null (default: null)

Path to a compile_commands.json compilation database, from which each file’s real compiler flags are taken. When null, the database is discovered by walking up from each source file’s directory, stopping at the project root. Paths are resolved relative to the ubproject.toml file.

[codelinks.projects.my_app.analyse.preprocessor]
compile_commands = "../build/compile_commands.json"

defines

Type: array of strings (default: [])

Preprocessor defines, each written as NAME or NAME=VALUE, applied as -D flags. These are the fallback used for files that no compile_commands.json entry applies to.

[codelinks.projects.my_app.analyse.preprocessor]
defines = ["FEATURE_X", "MAX_ITEMS=32"]

includes

Type: array of strings (default: [])

Include directories, applied as -I flags on the same fallback path as defines. Paths are resolved relative to the ubproject.toml file.

[codelinks.projects.my_app.analyse.preprocessor]
includes = ["../include", "../vendor/include"]

std

Type: string (default: "c++17")

The C/C++ standard used on the fallback parse path (e.g. "c++17", "c++20", "c11"); it also decides whether a file is parsed as C or as C++. Files matched by a compile_commands.json entry use that entry’s own flags instead, including its own standard.

[codelinks.projects.my_app.analyse.preprocessor]
std = "c++20"

A worked example — an out-of-source build directory for the flags, plus fallback flags for the headers the build does not compile directly:

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

[codelinks.projects.my_app.analyse.preprocessor]
compile_commands = "../build/compile_commands.json"
defines = ["FEATURE_X=1", "NDEBUG"]
includes = ["../include"]
std = "c++17"

How the compilation database is applied:

For every C/C++ file, ubCode looks for a matching entry in the applicable compile_commands.json (the explicit compile_commands path, or the one found by walking up):

• The file has an entry — it is parsed with that entry’s own flags, and defines, includes and std are not used for it.

• A translation-unit source (.c, .cpp, .cc, .cxx) with no entry — it is skipped, and no markers are extracted from it. A compilation database lists every source the build compiles, so a source that is missing from it is one the build does not compile, and there is no correct set of flags to parse it with.

• A header (e.g. .h, .hpp, .hh, .hxx) with no entry — it is parsed standalone with defines, includes and std. Compilation databases never list headers, so this is the normal case for them.

When no database is found at all, every file is parsed standalone with defines, includes and std.

Warning

Only GCC/Clang-style flags in compile_commands.json are interpreted. MSVC cl.exe syntax (/D NAME, /I dir, /std:c++17) is not: such flags are dropped rather than translated, and because the file does have a database entry the defines / includes / std fallback does not apply to it either, so it is parsed with no defines or include paths at all. For MSVC projects, either generate a Clang-style database (for example with clang-cl, or a CMake Ninja/Makefile generator), or drop compile_commands and set defines, includes and std explicitly.

Providing libclang:

The libclang engine needs a libclang library, version 16 or newer, the first time it parses a C/C++ file. It is located in this order:

1. LIBCLANG_PATH, if you have set it. This is treated as a deliberate choice: if the library it names cannot be loaded, or is older than version 16, the parse fails with an error rather than falling back.

2. A libclang already installed on the system, provided it is version 16 or newer. An older system library is not used — ubCode falls through to the next step instead.

3. Otherwise, ubCode downloads the pinned libclang wheel from PyPI, verifies it against pinned SHA-256 checksums, and caches the extracted library per user so later runs need no network access.

Once step 3 has run on a machine, the cached pinned library is used in preference to a system libclang on every later run, because it is the version extraction is verified against. Set LIBCLANG_PATH if you want a specific library instead.

Note

For an internal mirror or an air-gapped environment, point the download at a PyPI-compatible index with UBC_LIBCLANG_INDEX_URL. If it is unset, ubCode also honours the index variables you may already have configured for your Python tooling, in this order: UV_DEFAULT_INDEX, UV_INDEX_URL, then PIP_INDEX_URL. The index only decides where the library is fetched from — what is accepted is fixed by the pinned checksums, so a mirror serving a different artifact is rejected.

Alternatively, install libclang 16 or newer yourself and set LIBCLANG_PATH to the directory containing the library.

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.

The directive renders one need card per traced need at its own position, in ascending id order, and traced needs are :need: targets like any other. What the directive renders describes what a card shows, and the two cases that render an empty container.

In the editor preview, each site shows at most needs.import_preview_max cards (50 by default) and says so when it truncates; ubc build html always renders every card.

Making the source URLs clickable

With set_local_url or set_remote_url enabled, each traced need gains a URL field (local-url / remote-url by default) that renders as an ordinary metadata row — as text, not as a link.

Sphinx-Codelinks registers a needs_string_links rule for those fields itself, so its rows are clickable with no configuration. ubCode does not do that yet; for remote-url you can add the rule yourself to get the same result:

[needs.string_links.remote-url]
regex = "^(?P<url>.+)$"
link_url = "{{url}}"
link_name = "source"
options = ["remote-url"]

The rule is an identity one because ubCode stores the fully resolved URL in the field, with remote_url_pattern’s {commit}, {path} and {line} already substituted — so the template has nothing left to build. Rename the key and the options entry to match if you changed remote_url_field. All four of regex, link_url, link_name and options are required; a rule missing any of them is ignored with a config.string_link_incomplete diagnostic.

local-url cannot be made clickable this way. It is a file:// URL, and string links render only https:, http: and mailto: targets — any other scheme is refused, and a rule that tries reports config.string_link_unknown_field (or build.need_string_link_invalid if you declare the field first) and still shows the value as plain text. Sphinx-Codelinks’ local-url row links because it points at a page that build generates inside the built site, not at a file on your disk; Differences from a Sphinx build records that difference.

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_multiline_needs = true

[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.multiline_needs]
start_sequence = "@need"
end_sequence = "@endneed"
default_markup = "rst"
markups = { rst = ".rst", md = ".md" }

# Optional: use the preprocessor-aware libclang engine for the C/C++ files,
# so that markers in inactive #if / #ifdef branches are excluded.
[codelinks.projects.my_app.analyse.preprocessor]
compile_commands = "../build/compile_commands.json"
defines = ["FEATURE_X=1"]
includes = ["../include"]
std = "c++17"