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'
]

Sphinx-CodeLinks reads its configuration from an ubproject.toml file next to conf.py by default (see src_trace_config_from_toml), so no further entry in conf.py is needed:

ubproject.toml¶

# Configuration for source tracing project "src"
[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" # Relative path from this TOML file to the source directory

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::
   :project: src

Example¶

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.