1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
|
# Cacheing
Nearly all caching happens in `$(pwd)/.trblcache` by default (hereafter `$CACHE`),
here's a reminder of the process `trblcache` uses when building documentation:
0. 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).
0. Extract: run each file through an AWK program that emits chunk files
into `$CACHE/chunks/`.
0. Render: for each chunk, strip directives, run the renderer, and append
output to `$CACHE/namespace/<namespace>/index.html`.
0. Assemble: write `main.layout`, `nav.partial`, `global.meta`, and CSS
into `$CACHE/namespace/`.
0. 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
```c
...
/* tools/checker.sh tools/graph.sh
strict graph {
a -- b
a -- b
b -- a [color=blue]
}
*/
...
```
checker.sh
```sh
#!/bin/sh
if [ -z "$(command $1 -V)" ]; then
echo "Could not find $1"
exit -1
fi
exec $1
```
graph.sh
```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.
|
