Skip to content

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:

from livery.footman import plugin

plugin("footman.docs")

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:

fm docs.page | pandoc -o tasks.pdf     # or .html, .docx, …

--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)

Example

$ fm docs.page --all

docs.site

Render the task tree as linked pages: index.md per group, one file per task.

Made for docs sites — point into your docs tree and add the pages to the nav. Regenerate on each docs build so they can't drift.

fm docs.site <out> [--target=VALUE] [--flavor={plain|material}] [--prog=VALUE] [--all]
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

Example

$ fm docs.site <out> --all

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.

fm docs.shots [<argv> ...] --out=PATH [--width=INT] [--cmd=VALUE] [--title=VALUE]
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

Example

$ fm docs.shots <argv> --out=<out>

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

Example

$ fm docs.cast <keys> --out=<out>

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.

fm docs.errors [--out=PATH]
Parameter Type Default Description
--out=PATH path file to write the page into; omitted = stdout

Returns: a list of text (or null)

Example

$ fm docs.errors

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.

fm docs.config [--out=PATH] [--prog=VALUE]
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)

Example

$ fm docs.config

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.

fm docs.notes [--out=PATH] [--prog=VALUE]
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)

Example

$ fm docs.notes

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.

fm docs.globals [--out=PATH] [--prog=VALUE]
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)

Example

$ fm docs.globals
`--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.

$ fm docs.globals --out=_generated/globals.md
wrote _generated/globals.md

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).

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)

Example

$ fm docs.page --all

docs.site

Render the task tree as linked pages: index.md per group, one file per task.

Made for docs sites — point into your docs tree and add the pages to the nav. Regenerate on each docs build so they can't drift.

fm docs.site <out> [--target=VALUE] [--flavor={plain|material}] [--prog=VALUE] [--all]
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

Example

$ fm docs.site <out> --all

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.

fm docs.shots [<argv> ...] --out=PATH [--width=INT] [--cmd=VALUE] [--title=VALUE]
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

Example

$ fm docs.shots <argv> --out=<out>

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

Example

$ fm docs.cast <keys> --out=<out>

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.

fm docs.errors [--out=PATH]
Parameter Type Default Description
--out=PATH path file to write the page into; omitted = stdout

Returns: a list of text (or null)

Example

$ fm docs.errors

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.

fm docs.config [--out=PATH] [--prog=VALUE]
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)

Example

$ fm docs.config

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.

fm docs.notes [--out=PATH] [--prog=VALUE]
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)

Example

$ fm docs.notes

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.

fm docs.globals [--out=PATH] [--prog=VALUE]
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)

Example

$ fm docs.globals