Your tasks, documented¶
Footman ships a first-party plugin that renders a project's task tree as
markdown: the same names, params, docstring help, defaults, and examples
that fm --help shows, as pages you can publish. Everything on this page is
dogfooded: the task reference in this site's nav is
generated output, and the sample further down is embedded live.
Write plain prose¶
Footman surfaces a docstring, and a doc()
string, as plain text: verbatim in fm --help, so it reads in any terminal
and survives a pipe (fm --help build | less) byte for byte, and as plain
paragraphs in the exported markdown. It renders no rich markup in the terminal:
no bold, no headings, no reflowed tables. That is deliberate: footman is
zero-dependency, and plain text is the one format every
terminal, pager, and CI log agrees on.
So write your help as prose. A sentence or two that reads straight is worth more than markup footman won't paint, and it exports cleanly either way. The one styling footman does apply is colour, to what footman itself prints (names, receipts, the progress line) and, through the tools it spawns, to their output, never injected into your text. Your task's own stdout is yours; footman routes it untouched.
(A future opt-in could render markdown in the terminal too, see the roadmap, but it stays off by default and never becomes a dependency.)
Mount it¶
The plugin mounts like any other, in one line in your tasks file:
That's also the one-line demo of the plugin system: the
entry point is the identity, into= is your placement, and after the mount
fm --list shows docs.page and docs.site. (Cherry-pick
with only=, or pass into="footman" to nest the group deeper, as
footman.docs.page.)
One page: fm docs.page¶
fm docs.page > TASKS.md # the whole tree, one document
fm docs.page --target=docs # just one group…
fm docs.page --target=docs.build # …or one task
fm docs.page --out=TASKS.md # write the file directly
The page goes to stdout (stdout is the answer; footman's summary is stderr commentary), so it pipes:
--heading=2 (up to 6) makes the headings start deeper, so the output nests
under a host page's own title, which is exactly how the sample below is
embedded, via a pymdownx.snippets
include of a file the docs build regenerates:
### docs { #docs }
Generate markdown docs for this project's tasks
#### docs.page { #docs-page }
Render the task tree (or one group/task) as one markdown page.
Without --out the page is the task's stdout, ready to redirect or pipe
(into pandoc, say); with --out it is written to the file. The heading
level makes the page nest under a host site's own structure, so it
drops into zensical/mkdocs via a snippet include.
```text
fm docs.page [--target=VALUE] [--heading=INT] [--flavor={plain|material}] [--out=PATH] [--prog=VALUE] [--all]
| Parameter | Type | Default | Description |
|---|---|---|---|
--target=VALUE |
"" |
dotted task/group to scope to; empty = all | |
--heading=INT |
int | 1 |
top heading level |
--flavor={plain|material} |
plain | material |
"plain" |
plain CommonMark, or material/zensical extras |
--out=PATH |
path | file to write the page into; omitted = stdout | |
--prog=VALUE |
"fm" |
command name in usage and examples | |
--all |
flag | false |
include footman's own mounted tasks |
Returns: a list of text (or null)
docs.site¶
Render the task tree as linked pages: index.md per group, one file per task.
Made for docs sites — point
| Parameter | Type | Default | Description |
|---|---|---|---|
<out> |
path | required | directory to write the pages into |
--target=VALUE |
"" |
dotted group to scope to; empty = all | |
--flavor={plain|material} |
plain | material |
"material" |
material fits zensical/mkdocs; plain is portable |
--prog=VALUE |
"fm" |
command name in usage and examples | |
--all |
flag | false |
include footman's own mounted tasks |
Returns: a list of text
docs.shots¶
Run the CLI on a pseudo-terminal and save a framed SVG screenshot.
Runs <cmd> <argv…> on a real pty — colours, receipts, taught errors,
exactly as a terminal shows them — collapses live rewrites to their
final frame, and renders the capture with rich as an SVG in a
macOS-style window. Regenerate on every docs build and a screenshot
can never drift from the CLI: it is the CLI.
The command really executes, so don't screenshot tasks whose side effects you don't want. A failing command still renders — a taught error message is a perfectly good screenshot.
| Parameter | Type | Default | Description |
|---|---|---|---|
<argv>... |
variadic | ||
--out=PATH |
path | required | the SVG file to write |
--width=INT |
int | 72 |
terminal columns |
--cmd=VALUE |
"fm" |
executable to run | |
--title=VALUE |
window title |
Returns: a list of text
docs.cast¶
Record an animated SVG of a real interactive shell session.
Boots the shell from a scratch config with footman completion loaded
(via --setup-completion; nushell sources the generated hook), types
the script — everything after --, where <TAB>, <ENTER>,
<WAIT> and friends are keys — and replays
the capture through a terminal emulator into an animated, dependency-
free SVG with the session's real timing. TAB completion, in motion,
regenerated on every docs build so it cannot drift.
fm docs.cast [<keys> ...] --out=PATH [--shell={zsh|bash|fish|pwsh|nushell}] [--title=VALUE] [--width=INT] [--height=INT] [--prog=VALUE] [--cwd=PATH] [--pace=FLOAT] [--steady=FLOAT]
| Parameter | Type | Default | Description |
|---|---|---|---|
<keys>... |
variadic | ||
--out=PATH |
path | required | the animated SVG file to write |
--shell={zsh|bash|fish|pwsh|nushell} |
zsh | bash | fish | pwsh | nushell |
"zsh" |
interactive shell to drive |
--title=VALUE |
window title | ||
--width=INT |
int | 72 |
terminal columns |
--height=INT |
int | 14 |
terminal rows |
--prog=VALUE |
"fm" |
CLI whose completion is installed | |
--cwd=PATH |
path | directory the shell starts in; empty takes here | |
--pace=FLOAT |
float | 1.2 |
seconds each keypress stays on screen |
--steady=FLOAT |
float | 1.0 |
scale the quiet-detection windows; raise on a loaded machine |
Returns: a list of text
docs.errors¶
Render every runtime error and note as a markdown reference page.
The entries are read from the source itself rather than written by hand: every taught error and every teach-once note the runner can print, with the runtime-filled parts shown as ⟨like this⟩. A page that regenerates this on each docs build can never drift from what the runner actually says. Without --out the page is the task's stdout.
| Parameter | Type | Default | Description |
|---|---|---|---|
--out=PATH |
path | file to write the page into; omitted = stdout |
Returns: a list of text (or null)
docs.config¶
Render this runner's config keys as a markdown table.
The rows come from the runner's own list of recognised keys, so a
reference page that regenerates this on each docs build can neither
describe a key the runner lacks nor miss one it has — and it names the
table this runner reads ([tool.acme] under a branded CLI), because
a runner opens its own table and no other. Without --out the table is
the task's stdout; with --out it is written to the file.
| Parameter | Type | Default | Description |
|---|---|---|---|
--out=PATH |
path | file to write the table into; omitted = stdout | |
--prog=VALUE |
"fm" |
command name in the table |
Returns: a list of text (or null)
docs.notes¶
Render the note kinds as a markdown table.
The rows come from the runner's own kind registry — what the level system resolves against and the config validator refuses unknown kinds by — so a reference page that regenerates this on each docs build can neither list a kind footman lacks nor miss one it has. Without --out the table is the task's stdout; with --out it is written to the file.
| Parameter | Type | Default | Description |
|---|---|---|---|
--out=PATH |
path | file to write the table into; omitted = stdout | |
--prog=VALUE |
"fm" |
command name in the table |
Returns: a list of text (or null)
docs.globals¶
Render the runner's global options as a markdown table.
The rows come straight from the CLI grammar — the same table --help
prints — so a reference page that regenerates this on each docs build
can never drift from the runner. Without --out the table is the task's
stdout; with --out it is written to the file.
| Parameter | Type | Default | Description |
|---|---|---|---|
--out=PATH |
path | file to write the table into; omitted = stdout | |
--prog=VALUE |
"fm" |
command name in the table |
Returns: a list of text (or null)
`--flavor=plain` (the default) is pure CommonMark and pipe tables, safe for
pandoc and any renderer. `--flavor=material` opts into what a
zensical/mkdocs-material site already understands: heading anchors for
stable deep links and an `!!! example` admonition for the synthesized
invocation.
## A linked site: `fm docs.site`
```console
$ fm docs.site docs/tasks
wrote 20 pages under docs/tasks
One file per task, an index.md per group with relative links, directories
mirroring your group tree: drop it into your docs source and put the index
in your nav. This site's Task reference section is exactly that, wired
into zensical.toml's
nav. site defaults to --flavor=material because a docs site is where it
lands; pass --flavor=plain for anything else.
The runner itself: fm docs.globals¶
Your tasks aren't the only thing worth documenting; the runner's global
options deserve a page too. globals renders them as a markdown table
straight from the CLI grammar: the same rows, in the same order, with the
same words --help prints. This site's CLI reference table
is exactly that, regenerated on every docs build, so it cannot drift,
because it was never written by hand.
Terminal screenshots: fm docs.shots¶
Prose about colours drifts the moment the palette changes; a screenshot
generated from the CLI cannot. shots runs a command on a real
pseudo-terminal (colours, receipts, taught errors, exactly as a terminal
shows them), collapses the live rewrites to their final frame, and renders
the capture as an SVG in a macOS-style window:
$ fm docs.shots --out=docs/_generated/shots/run.svg -- format lint
wrote docs/_generated/shots/run.svg
Everything after -- is the command line to capture; --width sets the
terminal columns, --title the window title, and --cmd swaps the
executable (default: the CLI that invoked it, so a branded CLI screenshots
itself; App is a library, and the screenshotter simply runs your CLI).
The command really executes, so don't screenshot tasks whose side
effects you don't want. Every terminal image on this site is one of these,
regenerated by the docs build.
This task needs rich and a POSIX
pseudo-terminal. Neither is a footman dependency: the task is gated with
footman's own @requires_dep("rich"), so without rich it lists as
shots … (unavailable: requires rich) and refuses to run with that
message; add rich to your docs dependency group and it comes alive.
Footman documenting itself with its own availability machinery is exactly
the use @requires_dep was built for.
Animated sessions: fm docs.cast¶
A static frame can't show Tab completion. cast boots a real
interactive shell (zsh, bash, fish, pwsh, or nushell) from a scratch config
with footman's hook loaded, types a keystroke script, and replays the
captured bytes through a terminal emulator into an animated SVG: CSS
keyframes with the session's own timing, no JavaScript, plays anywhere an
image does. The session even answers its shell's terminal interrogations
(capability, cursor, and colour queries) the way a plain xterm would, since
modern shells refuse to paint a prompt into silence:
$ fm docs.cast --out=docs/_generated/shots/zsh-cast.svg \
--shell=zsh -- "fm " "<TAB>" "<WAIT>" "che" "<TAB>" "<ENTER>" "<WAIT:2500>"
wrote docs/_generated/shots/zsh-cast.svg (55 frames)
Everything after -- is the script: plain text is typed at a human-ish
cadence; <TAB>, <ENTER>, <SPACE>, <BACKSPACE>, <CTRL-C>,
<WAIT>, and <WAIT:ms> are keys. The shell really runs what you type:
the recording on the zsh completion page ends with a
real fm check. Needs rich and pyte
(the terminal emulator), gated the same way: without them the task lists
as unavailable and says which package to add.
Keep it fresh¶
Generated pages drift unless a build regenerates them. The tasks are plain functions, so footman's own docs task calls them directly. Copy the shape:
from pathlib import Path
from livery.footman import group
docs = group("docs", help="Documentation")
@docs.task(name="build")
def docs_build(check: bool = False):
"Build the docs site; regenerates the task reference first."
from livery.footman.docs import globals_, page, site
from livery.toolroom.tools import zensical
site(Path("docs/tasks"))
page(target="docs", heading=3, out=Path("_generated/tasks-page.md"))
globals_(out=Path("_generated/globals.md"))
zensical.build(clean=True, strict=check)
Add the generated paths to .gitignore: they're build output, not source.
Under --json, both tasks return the list of files they wrote,
so returned carries it for CI to verify.
Two flags to know. Usage lines and examples carry the CLI you invoked, so
a branded CLI documents itself as acme with no flag at
all, and --prog overrides the name when you need to. --all includes the
mounted footman group itself (excluded by default, since the documenter
doesn't document itself unless asked).
Link the terminal back to the pages¶
Once the pages are published, close the loop: a docs-url template under
[tool.footman] turns every task and group name in --list, --tree and
the --help pages into a terminal hyperlink to its own docs, and puts a
docs_url field on each task's --json row for readers that
cannot click.
[tool.footman]
docs-url = "https://docs.example.dev/tasks/{path}/" # docs.site: page per task
# docs-url = "https://docs.example.dev/reference/#{slug}" # docs.page: anchors
{path} is the task's slash-joined address (docs.build → docs/build),
matching the per-task pages docs.site writes; {slug} is the dash-joined
one (docs-build), matching the heading anchors the one-page docs.page
export carries. An unknown placeholder is refused by name. The links ride
the colour switch — piped output stays plain, and a terminal without
hyperlink support simply ignores them — and each --help page also prints
the URL as visible text, so there is always something to copy.
A plugin that writes the task pages knows their address, so it can set the
template itself from a pre_tasks hook, through the invocation's
docs_url:
from livery.footman import Invocation, pre_tasks
@pre_tasks
def link_task_pages(inv: Invocation) -> None:
if inv.docs_url is None:
inv.docs_url = "https://docs.example.dev/tasks/{slug}/"
The invocation starts with the configured docs-url, so a hook that sets the
template only while it is None keeps the project's own setting first. Set it
in the hook, not while the module imports: the hook runs on every invocation,
and a provider module imports once per process. A template footman cannot fill
is refused by name, as the configuration key's is.
The live sample¶
Everything below this line is fm docs.page --target=docs --all
--heading=3 --flavor=material, regenerated on every docs build:
docs¶
Generate markdown docs for this project's tasks
docs.page¶
Render the task tree (or one group/task) as one markdown page.
Without --out the page is the task's stdout, ready to redirect or pipe (into pandoc, say); with --out it is written to the file. The heading level makes the page nest under a host site's own structure, so it drops into zensical/mkdocs via a snippet include.
fm docs.page [--target=VALUE] [--heading=INT] [--flavor={plain|material}] [--out=PATH] [--prog=VALUE] [--all]
| Parameter | Type | Default | Description |
|---|---|---|---|
--target=VALUE |
"" |
dotted task/group to scope to; empty = all | |
--heading=INT |
int | 1 |
top heading level |
--flavor={plain|material} |
plain | material |
"plain" |
plain CommonMark, or material/zensical extras |
--out=PATH |
path | file to write the page into; omitted = stdout | |
--prog=VALUE |
"fm" |
command name in usage and examples | |
--all |
flag | false |
include footman's own mounted tasks |
Returns: a list of text (or null)
docs.site¶
Render the task tree as linked pages: index.md per group, one file per task.
Made for docs sites — point
| Parameter | Type | Default | Description |
|---|---|---|---|
<out> |
path | required | directory to write the pages into |
--target=VALUE |
"" |
dotted group to scope to; empty = all | |
--flavor={plain|material} |
plain | material |
"material" |
material fits zensical/mkdocs; plain is portable |
--prog=VALUE |
"fm" |
command name in usage and examples | |
--all |
flag | false |
include footman's own mounted tasks |
Returns: a list of text
docs.shots¶
Run the CLI on a pseudo-terminal and save a framed SVG screenshot.
Runs <cmd> <argv…> on a real pty — colours, receipts, taught errors,
exactly as a terminal shows them — collapses live rewrites to their
final frame, and renders the capture with rich as an SVG in a
macOS-style window. Regenerate on every docs build and a screenshot
can never drift from the CLI: it is the CLI.
The command really executes, so don't screenshot tasks whose side effects you don't want. A failing command still renders — a taught error message is a perfectly good screenshot.
| Parameter | Type | Default | Description |
|---|---|---|---|
<argv>... |
variadic | ||
--out=PATH |
path | required | the SVG file to write |
--width=INT |
int | 72 |
terminal columns |
--cmd=VALUE |
"fm" |
executable to run | |
--title=VALUE |
window title |
Returns: a list of text
docs.cast¶
Record an animated SVG of a real interactive shell session.
Boots the shell from a scratch config with footman completion loaded
(via --setup-completion; nushell sources the generated hook), types
the script — everything after --, where <TAB>, <ENTER>,
<WAIT> and friends are keys — and replays
the capture through a terminal emulator into an animated, dependency-
free SVG with the session's real timing. TAB completion, in motion,
regenerated on every docs build so it cannot drift.
fm docs.cast [<keys> ...] --out=PATH [--shell={zsh|bash|fish|pwsh|nushell}] [--title=VALUE] [--width=INT] [--height=INT] [--prog=VALUE] [--cwd=PATH] [--pace=FLOAT] [--steady=FLOAT]
| Parameter | Type | Default | Description |
|---|---|---|---|
<keys>... |
variadic | ||
--out=PATH |
path | required | the animated SVG file to write |
--shell={zsh|bash|fish|pwsh|nushell} |
zsh | bash | fish | pwsh | nushell |
"zsh" |
interactive shell to drive |
--title=VALUE |
window title | ||
--width=INT |
int | 72 |
terminal columns |
--height=INT |
int | 14 |
terminal rows |
--prog=VALUE |
"fm" |
CLI whose completion is installed | |
--cwd=PATH |
path | directory the shell starts in; empty takes here | |
--pace=FLOAT |
float | 1.2 |
seconds each keypress stays on screen |
--steady=FLOAT |
float | 1.0 |
scale the quiet-detection windows; raise on a loaded machine |
Returns: a list of text
docs.errors¶
Render every runtime error and note as a markdown reference page.
The entries are read from the source itself rather than written by hand: every taught error and every teach-once note the runner can print, with the runtime-filled parts shown as ⟨like this⟩. A page that regenerates this on each docs build can never drift from what the runner actually says. Without --out the page is the task's stdout.
| Parameter | Type | Default | Description |
|---|---|---|---|
--out=PATH |
path | file to write the page into; omitted = stdout |
Returns: a list of text (or null)
docs.config¶
Render this runner's config keys as a markdown table.
The rows come from the runner's own list of recognised keys, so a
reference page that regenerates this on each docs build can neither
describe a key the runner lacks nor miss one it has — and it names the
table this runner reads ([tool.acme] under a branded CLI), because
a runner opens its own table and no other. Without --out the table is
the task's stdout; with --out it is written to the file.
| Parameter | Type | Default | Description |
|---|---|---|---|
--out=PATH |
path | file to write the table into; omitted = stdout | |
--prog=VALUE |
"fm" |
command name in the table |
Returns: a list of text (or null)
docs.notes¶
Render the note kinds as a markdown table.
The rows come from the runner's own kind registry — what the level system resolves against and the config validator refuses unknown kinds by — so a reference page that regenerates this on each docs build can neither list a kind footman lacks nor miss one it has. Without --out the table is the task's stdout; with --out it is written to the file.
| Parameter | Type | Default | Description |
|---|---|---|---|
--out=PATH |
path | file to write the table into; omitted = stdout | |
--prog=VALUE |
"fm" |
command name in the table |
Returns: a list of text (or null)
docs.globals¶
Render the runner's global options as a markdown table.
The rows come straight from the CLI grammar — the same table --help
prints — so a reference page that regenerates this on each docs build
can never drift from the runner. Without --out the table is the task's
stdout; with --out it is written to the file.
| Parameter | Type | Default | Description |
|---|---|---|---|
--out=PATH |
path | file to write the table into; omitted = stdout | |
--prog=VALUE |
"fm" |
command name in the table |
Returns: a list of text (or null)