Python CLI Toolcraft

Input & UX

Generating Man Pages and Docs from a CLI

Generate reference docs and man pages from a Python command tree - Typer and Click generators, packaging man pages, and a CI check that stops drift.

Updated

Reference documentation retyped into a README is wrong within one release. The command tree already knows every command, option, default and help string, so the reference should be generated from it — and the only interesting question is how to stop the generated copy drifting from the code.

TL;DR

  • typer mytool.cli utils docs generates markdown; click-man and sphinx-click cover Click.
  • Generate into the repository, commit the result, and fail CI when regenerating changes it.
  • A man page needs sections the generator does not know: EXIT STATUS, ENVIRONMENT, FILES.
  • Install man pages through your package manager formula, not the wheel.
  • Keep hand-written guides for the why; generation only covers the what.

Prerequisites

A Click or Typer application with help text worth publishing (see writing help text), and somewhere to put the output — a docs directory, a site, or a man/ folder.

Generating the reference

Generating docs from the command tree The command definitions are the source of truth: a generator walks them and emits markdown pages and a man page during the build. Generating docs from the command tree Command tree the code itself Generator walks it names, options, help Markdown + roff written at build time Published site and man pages introspect render ship Generated reference cannot drift; hand-written guides explain why, which generation cannot.

Typer ships a generator:

uv run typer mytool.cli utils docs --name mytool --output docs/reference.md

It walks the command tree and emits one markdown section per command with its usage line, options and help text. For Click, two tools split the job:

click-man --target man/ mytool             # roff man pages

# docs/conf.py — Sphinx
extensions = ["sphinx_click"]

.. click:: mytool.cli:cli
   :prog: mytool
   :nested: full

All three read the same objects your CLI is built from, which is the point: a renamed flag changes the documentation in the same commit, with no human step in between.

Stopping drift with a CI check

Generating is only half the value. If the output is generated locally and committed by hand, it falls behind the first time somebody forgets.

Catching documentation drift in CI A continuous integration job regenerates the reference documentation and fails when the result differs from what is committed. Catching documentation drift in CI CI job Generator Repo copy Result regenerate from the command tree diff against docs/reference.md identical → pass different → fail, commit the update The check turns "the docs are stale" from something you discover into something the build refuses. 
- name: docs are up to date
  run: |
    uv run typer mytool.cli utils docs --name mytool --output docs/reference.md
    git diff --exit-code docs/reference.md

Three lines, and the failure message tells the author exactly what to do: run the generator and commit the result. It is the same pattern as a formatter check, and it works for the same reason — the fix is mechanical, so the check never becomes an argument.

Commit the generated file rather than building it only on the docs site. It makes the change visible in review, which is where somebody notices that a renamed flag is a breaking change.

What a man page needs that a generator cannot know

The sections a man page is expected to have The conventional structure of a Unix manual page: name, synopsis, description, options, exit status, environment, files, examples and see also. The sections a man page is expected to have NAME / SYNOPSIS generated One line each; the synopsis mirrors the usage line. DESCRIPTION / OPTIONS generated Straight from your command and option help text. EXIT STATUS write it The documented codes. Readers of man pages expect this section. ENVIRONMENT / FILES write it Variables you read and config paths you search. EXAMPLES / SEE ALSO reuse The same examples as the epilog, plus links. the middle two are what most generated man pages omit Exit status and environment are the sections that make a man page worth installing.

Generated man pages are usually thin in the same three places, and they are exactly the sections a man page reader looks for.

EXIT STATUS. Anyone reading a man page is likely writing a script. Document every code:

.SH EXIT STATUS
.TP
.B 0
Success.
.TP
.B 2
The command line was invalid.
.TP
.B 78
The configuration was invalid.

ENVIRONMENT. Every variable your tool reads, including the ones you honour by convention (NO_COLOR, MYTOOL_CONFIG). A variable that changes behaviour and is undocumented is indistinguishable from a bug.

FILES. The configuration paths you search, in order. This is the section that answers "why is it not using my settings" without a support conversation.

The practical approach is to keep these three as a small hand-written roff fragment and concatenate it onto the generated page during the build, so the generated parts stay generated and the human parts stay human.

click-man --target man/ mytool
cat man/mytool.1 man/_sections.1.in > man/mytool.1.tmp && mv man/mytool.1.tmp man/mytool.1
gzip -kf man/mytool.1

Shipping the man page

A wheel is not a good vehicle for a man page: there is no standard location inside a Python package that man will search, and installing into system paths from a wheel is unwelcome.

The routes that work:

  • Homebrew formula: man1.install "man/mytool.1" in the install block.
  • Distribution package: the packaging metadata places it in /usr/share/man/man1/.
  • A mytool docs man subcommand that prints the roff to stdout, so a user can install it themselves: mytool docs man | sudo tee /usr/local/share/man/man1/mytool.1 >/dev/null.

The last is a nice fallback for pipx installs, where nothing else will place the file for you.

UX considerations

Do not generate a page per command as separate files unless your tool is very large. One reference page with anchors is easier to search, and Ctrl-F beats navigating a tree of twenty stub pages.

Link from the epilog to the docs, not the other way round. A user in a terminal needs a URL; a user on the docs site already has navigation.

Keep hand-written guides separate from generated reference. Mixing them means the generator either overwrites your prose or has to be taught to merge, and both end badly. Two directories — docs/guides/ and docs/reference.md — keep the boundary obvious.

Version the docs with the tool. If you publish a site, the reference for 1.4 should stay available when 2.0 ships, because people run old versions for years.

Testing the behaviour

Beyond the CI diff check, two assertions are worth having in the test suite:

def test_every_command_appears_in_the_reference():
    reference = Path("docs/reference.md").read_text()
    for command in app.registered_commands:
        assert f"## {command.name}" in reference, f"{command.name} missing from the reference"

def test_documented_exit_codes_match_the_code():
    documented = set(re.findall(r"^\.B (\d+)$", Path("man/_sections.1.in").read_text(), re.M))
    assert {str(code) for code in EXIT_CODES.values()} <= {int(c) for c in documented} | set()

The second one is the useful oddity: it compares the codes in your error-boundary mapping with the codes in the man page, so adding a code without documenting it fails the build. Given that exit codes are part of your public interface, that is a check worth having.

Conclusion

Generate the reference from the command tree, commit it, and let CI fail when the two disagree. Write by hand only what generation cannot know — exit codes, environment variables, config paths and the reasoning behind commands — and keep those in files the generator never touches. The result is documentation that cannot quietly become wrong.

Frequently asked questions

Should generated docs be committed or built on the fly?

Committed. A generated file in the repository makes an interface change visible in review, which is where it should be noticed, and it means the documentation exists even when the site build is broken. The CI diff check is what keeps the committed copy honest.

How do I document subcommand trees several levels deep?

One page with nested headings, generated with --nested full or the equivalent. Deep trees are harder to read as separate pages, and a single page lets a reader search across the whole interface — which is usually what they are trying to do.

Can I generate documentation for argparse?

argparse-manpage produces man pages, and sphinx-argparse covers Sphinx. Both are less polished than the Click and Typer equivalents, which is one of the smaller reasons people move to a framework once a tool has documentation obligations.

What about a docs site — is generated reference enough?

No. Reference tells someone what a flag does; it never tells them which command to reach for or why. Aim for a short set of hand-written task guides ("how do I sync a directory", "how do I recover from a failed migration") plus the generated reference underneath them.

How do I keep the man page and the help output consistent?

By generating both from the same source. If you hand-edit the roff, you have created a second copy that will drift. The only sections worth writing by hand are the ones with no equivalent in the command tree, which is why keeping them in a separate fragment matters.

Should the docs site be versioned?

If people run old versions — and for a CLI they always do — yes. A /latest/ alias plus a directory per minor version costs a little build configuration and answers the question "what did --mode do in 1.4" without archaeology. If you only ever publish one version, at least state which one the site describes, prominently.

How do I generate documentation for plugin commands?

Only for the plugins installed in the environment doing the generation, which is exactly what makes this awkward. The usual arrangement is to generate the host's reference from the host alone, and let each plugin document its own commands — with a page on your site listing known plugins and linking to them.

Is a generated reference enough for a docs site?

It is the foundation, not the whole thing. Readers arriving from a search engine are looking for a task ("how do I mirror a directory") rather than a flag, so a handful of hand-written task pages linking into the generated reference is what turns a wall of options into something navigable. The reference answers the follow-up question, which is the right division of labour.