Quick Start¶

Three steps to quickly run CodeLinks to generate links to your source code:

Configure Sphinx
Add a one-line comment to your source code to define a Sphinx-Needs item.
Use the src-trace directive in your documentation.

Sphinx Config¶

conf.py¶

extensions = [
    'sphinx_needs',
    'sphinx_codelinks'
]
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"

One-line comment¶

dummy_src.cpp¶

#include <iostream>

// @ title here, IMPL_1, impl
void singleLineExample()
{
    std::cout << "Single-line comment example" << std::endl;
}

Directive¶

index.rst¶

.. src-trace:: dummy src
   :project: src

Example¶

Src-Trace: dummy src ST_670E3

project: src

Implementation: title here IMPL_1

local-url: ../minimum_config/dummy_src#L3;

remote-url: tests/doc_test/minimum_config/dummy_src.cpp#L3;

Note

local-url is not working on the website as it only supports local browse

Section Directive provides more advanced usage.