`[codelinks]`¶

Codelinks configuration (source-code marker extraction).

Guide: Codelinks (source code tracing).

codelinks.local_url_field¶

Type:: string
Default:: "local-url"

Field name for local URL.

codelinks.outdir¶

Type:: string

Optional output directory for standalone use.

codelinks.projects¶

Type:: table of tables
Default:: {}

Per-project configurations keyed by project name.

Each entry: Per-project configuration.

codelinks.projects.<name>.analyse¶

Type:: table

Analysis settings.

codelinks.projects.<name>.analyse.get_multiline_needs¶

Type:: boolean
Default:: false

Whether to extract multi-line needs: a need written across the lines of a comment, from an open line (@need[<markup>] <type>: <title> by default) to a close line (@endneed).

When enabled, the lines of each such block are no longer read for one-line needs or need-id references.

codelinks.projects.<name>.analyse.get_need_id_refs¶

Type:: boolean
Default:: true

Whether to extract need-id references.

codelinks.projects.<name>.analyse.get_oneline_needs¶

Type:: boolean
Default:: true

Whether to extract one-line needs.

codelinks.projects.<name>.analyse.git_root¶

Type:: string

Optional explicit git root (relative to TOML file).

codelinks.projects.<name>.analyse.multiline_needs¶

Type:: table

Multi-line need configuration: the open and close words and the markups a block’s body may declare.

codelinks.projects.<name>.analyse.multiline_needs.default_markup¶

Type:: string
Default:: "rst"

The markup of a block whose open line names none (or an unknown one). Must be a key of markups.

codelinks.projects.<name>.analyse.multiline_needs.end_sequence¶

Type:: string
Default:: "@endneed"

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

codelinks.projects.<name>.analyse.multiline_needs.markups¶

Type:: table of strings
Default:: { md = ".md", rst = ".rst" }

The markups a block may declare (@need[<markup>] ...), each mapped to the need’s doctype (a non-empty suffix). A table given here replaces the default one.

codelinks.projects.<name>.analyse.multiline_needs.start_sequence¶

Type:: string
Default:: "@need"

The word that opens a multi-line need, at the start of a comment line.

codelinks.projects.<name>.analyse.need_id_refs¶

Type:: table
Default:: { markers = ["@need-ids:"] }

Need-id reference marker configuration.

codelinks.projects.<name>.analyse.need_id_refs.markers¶

Type:: array of strings
Default:: ["@need-ids:"]

Marker strings that identify need-id references.

codelinks.projects.<name>.analyse.oneline_comment_style¶

Type:: table

One-line comment style configuration.

codelinks.projects.<name>.analyse.oneline_comment_style.end_sequence¶

Type:: string
Default:: "\n"

Character sequence that ends a one-line marker.

codelinks.projects.<name>.analyse.oneline_comment_style.field_split_char¶

Type:: string
Default:: ","

Character used to split fields.

codelinks.projects.<name>.analyse.oneline_comment_style.needs_fields¶

Type:: array of tables

Ordered list of field definitions.

Each entry: A single field definition in the one-line comment style.

codelinks.projects.<name>.analyse.oneline_comment_style.needs_fields[].default¶

Type:: string or array of strings

Default value applied when the field is omitted from the marker. None means the field is required (no default).

Forms:

a string: A string default value.
an array of strings: A list-of-strings default value.

codelinks.projects.<name>.analyse.oneline_comment_style.needs_fields[].name¶

Type:: string

Field name (e.g., “title”, “id”, “type”).

codelinks.projects.<name>.analyse.oneline_comment_style.needs_fields[].type¶

Type:: string
Default:: "str"

Field type. Defaults to Str if omitted.

Values:

"str": A plain string field.
"list[str]": A list of strings.

codelinks.projects.<name>.analyse.oneline_comment_style.start_sequence¶

Type:: string
Default:: "@"

Character sequence that starts a one-line marker.

codelinks.projects.<name>.analyse.preprocessor¶

Type:: table

Preprocessor-aware extraction for C/C++ source files.

Configuring this table — even with no keys inside it — switches C/C++ extraction from the default tree-sitter engine to the preprocessor-aware libclang engine, so only markers in active preprocessor branches are extracted.

codelinks.projects.<name>.analyse.preprocessor.compile_commands¶

Type:: string

Path to the compile_commands.json to read compiler flags from. When unset, it is discovered by walking up from each source file, stopping at the project root.

codelinks.projects.<name>.analyse.preprocessor.defines¶

Type:: array of strings
Default:: []

Fallback preprocessor defines, each NAME or NAME=VALUE, applied as -D. Used for files that no compile_commands.json entry applies to.

codelinks.projects.<name>.analyse.preprocessor.includes¶

Type:: array of strings
Default:: []

Fallback include directories, applied as -I. Used together with defines for files that no compile_commands.json entry applies to.

codelinks.projects.<name>.analyse.preprocessor.std¶

Type:: string
Default:: "c++17"

The C/C++ standard used for the standalone parse path, e.g. c++17, c++20 or c11; it also selects the language the file is parsed as. Files matched by a compile_commands.json entry use that entry’s own flags instead. Defaults to c++17 when unset.

codelinks.projects.<name>.ref_url_field¶

Type:: string
Default:: "code_url"

Need field that @need-ids: reference markers back-attach their URL to.

When a source file carries a @need-ids: REQ_X marker, the resolved remote/local URL of that marker is written onto the already existing need REQ_X under this field name (default code_url). Point a tests/-scoped project at a different field (e.g. test_url) to keep test-code links separate from implementation-code links.

codelinks.projects.<name>.remote_url_pattern¶

Type:: string

URL pattern for remote links (e.g., GitHub blob URLs).

codelinks.projects.<name>.source_discover¶

Type:: table

Source file discovery settings.

codelinks.projects.<name>.source_discover.comment_type¶

Type:: string

Language/comment type for this project.

Values:

"cpp": C++ language.
"python": Python language.
"rust": Rust language.
"csharp": C# language.
"yaml": YAML language.
"go": Go language.
"bash": Bash / POSIX shell.
"typescript": TypeScript language.
"ts": Alias for typescript, accepted so a configuration written for sphinx-codelinks keeps validating.

codelinks.projects.<name>.source_discover.exclude¶

Type:: array of strings

Glob patterns for files to exclude.

Unset, a TypeScript project (comment_type = "typescript", alias "ts", which discovers JavaScript too) excludes **/node_modules/**, **/dist/**, **/build/**, **/out/** and **/coverage/**; any other project excludes nothing. An explicit list, [] included, replaces that default; it is never merged with it.

codelinks.projects.<name>.source_discover.follow_links¶

Type:: boolean
Default:: false

If true, follow symbolic links when traversing source directories.

codelinks.projects.<name>.source_discover.gitignore¶

Type:: boolean
Default:: true

Whether to respect .gitignore files.

codelinks.projects.<name>.source_discover.include¶

Type:: array of strings
Default:: []

Glob patterns for files to include.

codelinks.projects.<name>.source_discover.src_dir¶

Type:: string
Default:: "."

Source directory (absolute or relative).

codelinks.remote_url_field¶

Type:: string
Default:: "remote-url"

Field name for remote URL.

codelinks.set_local_url¶

Type:: boolean
Default:: false

Whether to compute local file URLs.

codelinks.set_remote_url¶

Type:: boolean
Default:: false

Whether to compute remote (git) URLs.

[codelinks]¶

`[codelinks]`¶