Maintaining documentation can be prone to error and cumbersome. Especially for demos, tutorials, and usage guides for command-line tools. To aid that, kmdo runs through a directory and executes command-files, storing stdout and stderr in corresponding output-files.

This documentation is an example of how this can be used in concert with Sphinx and Read the Docs.


Install kmdo system-wide via the pip:

sudo pip3 install kmdo

Or install it at user-level via the pip:

pip3 install --user kmdo


When doing user-level install, then include the pip binary install path in your PATH definition. For example PATH="$PATH:$HOME/.local/bin"


usage: kmdo [-h] [-r] [-s SHELL] path

Run commands from .cmd files, storing output in .out files

positional arguments:
  path                  Path to DIR containing .cmd files

optional arguments:
  -h, --help            show this help message and exit
  -r, --recursive       go deepah!
  -s SHELL, --shell SHELL
                        Absolute path to the Shell to use


kmdo has exit code 0 upon success, that is when all commands succeed, ignoring command errors from command-files with .uone in the file name. On error, kmdo has a non zero exit code.

Additionally, kmdo outputs a YAML representation of what it has executed to stdout. For example, when using kmdo to generate command output for the documentation you are reading now.

kmdo src/examples

Outputs the following YAML:

  path: '/home/safl/git/kmdo/docs/src/examples'
  recursive: False
- out_fp: '/home/safl/git/kmdo/docs/src/examples/kmdo.out'
  cmd_fp: '/home/safl/git/kmdo/docs/src/examples/kmdo.cmd'
  cmd: 'kmdo --help'
  rcode: 0
  uone: False
  err: False
- out_fp: '/home/safl/git/kmdo/docs/src/examples/kmdo.uone.out'
  cmd_fp: '/home/safl/git/kmdo/docs/src/examples/kmdo.uone.cmd'
  cmd: 'kmdo'
  rcode: 2
  uone: True
  err: False
nerrs: 0

Empty command-file and update-on-error

When the command-file is empty, then the fname part of the command-file file name is treated as the command to execute.

For example, the empty file named kmdo.uone.cmd, will execute the command kmdo, and because of .uone in the file name then it create the output file kmdo.uone.out:

usage: kmdo [-h] [-r] [-s SHELL] path
kmdo: error: the following arguments are required: path