oct.docs.callgraph_command Namespace Reference

Functions
Path|None	_render_svg (Path dot_path, tuple[str,...] unflatten_args=())
int	run_docs_callgraph (Path project_root, str qualname, int|None depth=None, list[str]|None trace_args=None)
int	_static_only (StaticCallGraph static, CallGraph graph, Function root_fn, int|None depth, Path dot_path)
int	_traced (StaticCallGraph static, str root, int|None depth, list[str] trace_args, Path dot_path)

Detailed Description

Purpose
-------
``oct docs --callgraph QUALNAME [--depth N] [--trace -- ARGS...]``: chart C
of the overview-charts plan (docs/DOCS_OVERVIEW_CHARTS_PLAN_2026-09-27.md
in the workspace), the full call graph of one entry point.

Without ``--trace`` it draws the STATIC graph: every function reachable
from the root through calls :mod:`oct.deps.call_graph` resolves from the
source. With ``--trace`` it also runs ``oct ARGS`` in this process, records
what actually ran (:mod:`oct.docs.call_trace`), and draws the two against
each other: what ran, what ran that the static graph lacks, and what the
static graph has that this run did not reach.

This used to be ``oct deps --callgraph``; the operator asked for it to be a
documentation feature listed in ``oct docs --help`` and ``oct --help``
(2026-09-27), together with the trace's entry point.

Responsibilities
----------------
- :func:`run_docs_callgraph` - resolve the root, build the static graph,
  optionally trace, write DOT (and SVG when Graphviz is present) plus, for
  a trace, a JSON record, and print a summary.

Diagnostics
-----------
Domain: OCT-DOCS
Levels:
    L2 - command entry / exit
    L3 - root resolution, output paths
    L4 - deep tracing

Contracts
---------
- Output goes under ``docs/_build/callgraph/`` of the project the command
  runs in, which Option C projects gitignore.
- With ``--trace`` the static graph is built from oct's own source (the
  imported ``oct`` package), wherever the command runs, so a throwaway
  project can host a real ``oct git commit`` trace; without it, from the
  current project.
- Exit codes: 0 done; 2 the root is missing or ambiguous, or the arguments
  are inconsistent; 3 Graphviz is absent (DOT still written); 4 the root
  function did not run during the traced command.

Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
- oct.deps.call_graph (lazy; build_call_graph, to_callgraph - the static graph)
- oct.docs.callgraph (lazy; CALLGRAPH_REL, reachable, to_dot - the shared model)
- oct.docs.call_trace (lazy; trace_oct_command, compare, to_diff_dot - the trace)

Function Documentation

_render_svg()

Path | None oct.docs.callgraph_command._render_svg ( Path dot_path, tuple[str, ...] unflatten_args = () )

protected

Render *dot_path* beside itself as SVG; ``None`` when Graphviz is absent or fails.

With *unflatten_args* the DOT is first piped through Graphviz's
``unflatten`` (the file on disk stays as written); without ``unflatten``
on PATH it is rendered as it is.

Definition at line 75 of file callgraph_command.py.

Here is the caller graph for this function:

_static_only()

int oct.docs.callgraph_command._static_only ( StaticCallGraph static, CallGraph graph, Function root_fn, int | None depth, Path dot_path )

protected

The static graph alone, as ``oct deps --callgraph`` drew it.

Definition at line 144 of file callgraph_command.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_traced()

int oct.docs.callgraph_command._traced ( StaticCallGraph static, str root, int | None depth, list[str] trace_args, Path dot_path )

protected

Trace ``oct ARGS``, compare with the static graph below *root*, and report.

Definition at line 178 of file callgraph_command.py.

Here is the call graph for this function:

Here is the caller graph for this function:

run_docs_callgraph()

int oct.docs.callgraph_command.run_docs_callgraph	(	Path	project_root,
		str	qualname,
		int | None	depth = None,
		list[str] | None	trace_args = None )

Draw the call graph of *qualname*; with *trace_args*, trace ``oct ARGS`` too.

Definition at line 101 of file callgraph_command.py.

Here is the call graph for this function: