Directive

Attention

src-trace directive currently only supports one-line need definition.

CodeLinks provides src-trace directive and it can be used in the following ways:

.. src-trace:: example_with_file
   :project: project_config
   :file: example.cpp

or

.. src-trace:: example_with_directory
   :project: project_config
   :directory: ./example

The src-trace directive has the following options:

• project: the project config specified in conf.py or TOML file to be used for source tracing.

• file: the source file to be traced.

• directory: the source files in the directory to be traced recursively.

Regarding the file and directory options:

• They are optional and mutually exclusive.

• The given paths are relative to src_dir defined in the source tracing configuration.

• If not given, the whole project will be examined.

Example

With the following configuration for a demo source code project dcdc,

conf.py

src_trace_config_from_toml = "src_trace.toml"

src_trace.toml

[codelinks]
# Configuration for source tracing
set_local_url = true            # Set to true to enable local code html and URL generation
local_url_field = "local-url"   # 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

# Configuration for source tracing project "dcdc"
[codelinks.projects.dcdc]
remote_url_pattern = "https://github.com/useblocks/sphinx-codelinks/blob/{commit}/{path}#L{line}" # URL pattern for remote source code

[codelinks.projects.dcdc.source_discover]
src_dir = "../tests/data/dcdc" # Relative path from this TOML config to the source directory

[codelinks.projects.dcdc.analyse]
get_need_id_refs = false
get_oneline_needs = true

[codelinks.projects.dcdc.analyse.oneline_comment_style]
# Configuration for oneline comment style
start_sequence = "[["  # Start sequence for oneline comments
end_sequence = "]]"    # End sequence for the online comments; default is newline character
field_split_char = "," # Character to split fields in the comment
# Fields that are defined in the oneline comment style
needs_fields = [
  { "name" = "id", "type" = "str" },
  { "name" = "title", "type" = "str" },
  { "name" = "type", "type" = "str", "default" = "impl" },
  { "name" = "links", "type" = "list[str]", "default" = [
  ] },
]

[codelinks.projects.src]
remote_url_pattern = "https://github.com/useblocks/sphinx-codelinks/blob/{commit}/{path}#L{line}"

[codelinks.projects.src.source_discover]
src_dir = "../tests/doc_test/minimum_config"

The src-trace directive can be used with the file option:

.. src-trace:: dcdc demo_1
   :project: dcdc
   :file: ./charge/demo_1.cpp

The needs defined in source code are extracted and rendered to:

Src-Trace: dcdc demo_1 ST_EE933

project: dcdc

Implementation: processAssemble function IMPL_processAssemble

local-url: ../dcdc/charge/demo_1#L16; remote-url: tests/data/dcdc/charge/demo_1.cpp#L16;

Implementation: main function IMPL_main_demo1

local-url: ../dcdc/charge/demo_1#L22; remote-url: tests/data/dcdc/charge/demo_1.cpp#L22;

The src-trace directive can be used with the directory option:

.. src-trace:: dcdc charge
   :project: dcdc
   :directory: ./discharge

The needs defined in source code are extracted and rendered to:

Src-Trace: dcdc charge ST_71972

project: dcdc

Implementation: displayUI() func, so that it displays UI IMPL_displayUI

local-url: ../dcdc/discharge/demo_3#L26; remote-url: tests/data/dcdc/discharge/demo_3.cpp#L26;

Implementation: back up data IMPL_backupData

local-url: ../dcdc/discharge/demo_3#L42; remote-url: tests/data/dcdc/discharge/demo_3.cpp#L42;

Implementation: main func in demo_3.cpp IMPL_main_demo_3

local-url: ../dcdc/discharge/demo_3#L48; remote-url: tests/data/dcdc/discharge/demo_3.cpp#L48;

To have a more customized configuration of CodeLinks, please refer to configuration.