What documentation can Bashly auto-generate for a bash script?

Updated

Bashly can automatically generate two forms of documentation for the bash script it produces: Markdown documentation and man page documentation. Both are generated as part of the tool's output, so you don't write them by hand — they are derived from the same YAML configuration that defines your commands, subcommands, arguments, and flags.

Where the documentation comes from

Bashly's workflow is configuration-driven. You describe your tool in a YAML file (commands, subcommands, arguments, and flags), and Bashly uses that description to generate a single standalone bash script. Because the YAML already contains the structure of your CLI, Bashly can reuse it to produce documentation that matches the actual behavior of the generated script.

The relevant sequence, per the Bashly site:

  1. You provide a YAML configuration file describing commands, subcommands, arguments, and flags.
  2. bashly init creates an initial sample YAML file for you.
  3. bashly generate produces the bash script that parses and validates user input, provides help messages, and runs your code for each command.

Documentation generation sits alongside this generation step — it is listed among the features Bashly is responsible for, together with script generation, usage texts, and help screens.

The two documentation formats

Format What it is Typical use
Markdown documentation A Markdown file describing your script's commands, arguments, and flags README files, wikis, docs sites, repositories
Man page documentation A man page for the script Terminal-based reference via man

Both are described as auto-generated for your script. The site does not specify file names, output directories, or command-line flags for controlling documentation output, so check the generated output or the project's documentation for the exact paths in your version.

How this relates to the built-in help

Auto-generated documentation is distinct from the runtime help that Bashly builds into the script itself. The generated script includes:

  • Usage texts and help screens showing your tool's arguments, flags, and commands — including subcommands.
  • Standard flags such as --help and --version.

So a user running your tool with --help sees help generated from the same configuration, while the Markdown and man page files serve as external reference material. All three stay consistent because they share one source: the YAML definition.

Practical implications

  • Single source of truth. Because documentation is generated from the YAML config, updating a command or flag in the config and regenerating keeps docs in sync — provided you regenerate rather than hand-edit the output.
  • No separate doc-writing step. You focus on your command code (kept in separate files per command and merged into the final script); Bashly handles usage texts, help screens, and documentation.
  • Consistent with script quality. Bashly states the generated script is human-readable and compliant with shellcheck and shfmt; the documentation is generated from the same structured definition.

What the site does not specify

The available material does not describe:

  • The exact filenames or locations of the generated Markdown and man page files.
  • Any configuration options to customize or disable documentation generation.
  • Whether documentation is generated by default on every bashly generate run or requires a separate step.

For those details, consult the Bashly documentation or inspect the output of bashly generate in your project.