Traced source code

A need can be written in a source file, as a comment marker, and brought into the documentation with the src-trace directive of Sphinx-Codelinks. ubCode reads the same markers and renders the same directive, in the editor preview and in its html and pdf builds. This page shows the markup; Tracing source code with Codelinks is the how-to (marker types, languages, configuration), and Codelinks (source code tracing) the configuration reference.

The traced source

This site’s own ubproject.toml declares a codelinks project, specimens, over one Python file:

[codelinks.projects.specimens.source_discover]
src_dir = "specimens/codelinks"
comment_type = "python"

[codelinks.projects.specimens.analyse]
get_oneline_needs = true
get_need_id_refs = true

The file holds the two markers a project reads with those two settings:

specimens/codelinks/greeter.py
"""A tiny source tree traced by the codelinks specimen."""


# @Greet a user by name, EX_IMPL_GREET, impl, [EX_REQ_GREET]
def greet(name: str) -> str:
    return f"Hello, {name}!"


def farewell(name: str) -> str:
    # @need-ids: EX_REQ_GREET
    return f"Goodbye, {name}!"

  • # @Greet a user by name, EX_IMPL_GREET, impl, [EX_REQ_GREET] is a one-line need: a title, an id, a need type and the needs it links to, after the @ (the default fields, in their default order).

  • # @need-ids: EX_REQ_GREET is a need-id reference: it ties that line of code to a need that already exists, and creates none.

The one-line need links to EX_REQ_GREET, which is written on this page as an ordinary need:

The requirement the code implements

.. req:: Greet the user
   :id: EX_REQ_GREET
   :status: open

   The application greets a user by name.
Requirement: Greet the user EX_REQ_GREET
status: open
links incoming: EX_IMPL_GREET

The application greets a user by name.

 
```{req} Greet the user
:id: EX_REQ_GREET
:status: open

The application greets a user by name.
```

A need’s MyST forms render live in Writing needs in MyST; this one has no twin, because a need id is unique in the project.

Tracing a project

src-trace draws one need card per one-line need of a project, where it is written. :project: names the codelinks project; :file: or :directory: (one of them) narrows it to one file or one directory of it.

The traced needs

.. src-trace::
   :project: specimens
   :file: greeter.py
Implementation: Greet a user by name EX_IMPL_GREET
links outgoing: EX_REQ_GREET
 
```{src-trace}
:project: specimens
:file: greeter.py
```

The MyST form has no live twin: a marker’s need is drawn by one src-trace only, and a second one over the same file is reported as a duplicate.

The traced need is a need like any other from here on: :need:`EX_IMPL_GREET` links to its card (Greet a user by name (EX_IMPL_GREET)), and EX_REQ_GREET lists it among its incoming links. How the cards are ordered, and where a ubCode build differs from a Sphinx-Codelinks one, is in the src-trace differences.