Directive

The src-trace directive creates a need from every one-line need in the source files it traces and, in a project that extracts them (get_multiline_needs), from every multi-line need, its body rendered in the markup it declares.

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

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

or

.. src-trace::
   :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.

  • A file that is not an existing file below src_dir (a missing path, or a directory) traces nothing: the directive warns once (codelinks.missing_file) and the build goes on, and the directive traces the file once it exists.

Example

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

ubproject.toml
# Configuration for source tracing project "dcdc"
[codelinks.projects.dcdc]
remote_url_pattern = "https://github.com/useblocks/sphinx-needs/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 file 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" = [
  ] },
]

The file is read by default, without any entry in conf.py (see src_trace_config_from_toml).

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

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

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

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

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

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

Implementation: displayUI() func, so that it displays UI IMPL_displayUI
local-url: ../dcdc/discharge/demo_3#L26
remote-url: packages/sphinx-codelinks/tests/data/dcdc/discharge/demo_3.cpp#L26

Multi-line needs

With get_multiline_needs on, a project’s multi-line needs are rendered too. This project traces one file holding one block:

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

[codelinks.projects.multiline.source_discover]
src_dir = "../tests/data/multiline_needs"
include = ["rate_limit.cpp"]

[codelinks.projects.multiline.analyse]
get_need_id_refs = false
get_multiline_needs = true
rate_limit.cpp
#include <stdbool.h>

/**
 * @need impl: Lock an account after repeated failures
 * :id: IMPL_RATE_LIMIT_1
 * :links: FE_MULTILINE_NEEDS
 *
 * After **five** failed attempts the account is locked, as
 * :need:`FE_MULTILINE_NEEDS` lets a source comment say:
 *
 * - the count is kept in ``failed_attempts``;
 * - a successful login resets it.
 * @endneed
 */
bool login(const char *user, const char *password) {
    return false;
}

.. src-trace::
   :project: multiline
   :file: rate_limit.cpp

renders the need, its body parsed as reStructuredText – the bold text, the role linking to the feature, the list and the literal:

Implementation: Lock an account after repeated failures IMPL_RATE_LIMIT_1
local-url: ../multiline_needs/rate_limit#L4
remote-url: packages/sphinx-codelinks/tests/data/multiline_needs/rate_limit.cpp#L4
links outgoing: FE_MULTILINE_NEEDS

After five failed attempts the account is locked, as Extract multi-line needs wr... (FE_MULTILINE_NEEDS) lets a source comment say:

  • the count is kept in failed_attempts;

  • a successful login resets it.

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