Cacheing

Nearly all caching happens in $(pwd)/.trblcache by default (hereafter $CACHE), here's a reminder of the process trblcache uses when building documentation:

Scan: find all source files under the input folders whose extension has a registered comment form (c, h, cpp, hpp, lua, py, sql, md, dot, plus any -f additions).
Extract: run each file through an AWK program that emits chunk files into $CACHE/chunks/.
Render: for each chunk, strip directives, run the renderer, and append output to $CACHE/namespace/<namespace>/index.html.
Assemble: write main.layout, nav.partial, global.meta, and CSS into $CACHE/namespace/.
Build: apply the layout/template tokens to each namespace page and write the final site to -o <dest> (default $CACHE/built).

Of these, only chunk extraction can be cached. Cacheing works by first creating a file under $CACHE/last_processed/<path> when a file is processed, and then on subsequent processing, ignore files if their $CACHE/last_processed/<path> file timestamp is newer than the <path> timestamp. If your filesystem does not support file timestamps, trbldoc will never assume the cache is invalid, and will serve stale data. If you are on such a system, always run with -C to force trbldoc to generate new chunks.

Notes

No cached chunks

The rendered chunks, generally, cannot be cached. If the user provided their own tooling (i.e. bash scripts) for trbldoc, trbldoc cannot check for updates to the scripts in order to invalidate the cached rendered chunk. Checking file last updated times won't work, if a script invokes another script or relies on any system environment the user's updates won't take. Example:

project
| src/
| | file1.c - last updated 1d ago
| tools/
| | checker.sh - last updated 1d ago
| | graph.sh - last updated 30s ago

file1.c

...
/* tools/checker.sh tools/graph.sh
strict graph { 
  a -- b
  a -- b
  b -- a [color=blue]
}
*/
...

checker.sh

#!/bin/sh

if [ -z "$(command $1 -V)" ]; then
    echo "Could not find $1"
    exit -1
fi

exec $1

graph.sh

#!/bin/sh

exec dot

It would be impossible for trbldoc to determine that tools/checker.sh uses tools/graph.sh without forcing it to run in a hermetically sealed sandbox that carefully controls what environment, filesystem, and other programs may be run. Such heavy sandboxing is against the vision of trbldoc as a simple, single-file documentation generator.