Skip to main content

Write documentation in comments and render it with templates.

Project description

Shell Script Documentation

Write documentation in comments and render it with templates.

pipeline status coverage report pypi version python wheel gitter chat

shellman can generate man pages, wiki pages and help text using documentation written in shell scripts comments.

For example:


## \brief Just a demo
## \desc This script actually does nothing.

main() {
  case "$1" in
    ## \option -h, --help
    ## Print this help and exit.
    -h|--help) shellman "$0"; exit 0 ;;

## \usage demo [-h]
main "$@"

Output when calling ./demo -h:

Usage: demo [-h]

This script actually does nothing.

  -h, --help            Print this help and exit.

You can see more examples and all the documentation in the wiki!


In the demo above we saw the three builtin templates: helptext, manpage and wikipage.

You can use your own templates by specifying them with the --template path:my/template syntax.

You can also write a plugin: see the wiki page on GitLab or on GitHub.


shellman is written in Python, so you must install it with pip:

pip install shellman

Some projects using shellman

  • shellm — A collection of scripts and libraries built on a core inclusion-system, all installable with basher. Here are a few examples:
    • daemon — A library that facilitates the writing of daemonized scripts that consume files in a watched directory.
    • debug — A simple script that sets the verbose/dry-run/debug Bash flags before running another script.
    • format — Format your output with style and color.
    • home — A home for your shell scripts!
    • loop — Control the flow of your loops (pause/resume/etc.).


Software licensed under ISC license.


All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

v0.4.1 (compare) - 2018-10-10


  • Fix body filter for Python 2 (ce7d0ef).

v0.4.0 (compare) - 2018-09-28


  • Add context variable to avoid escaping lines starting with given values (742e023).
  • Add usagetext template (a7c20fc).


  • Fix escape filter condition (f32cd43).
  • Fix python 2 unicode decode error (0040028).
  • Fix variables for output (01155fb).


  • Improve error messages (96ebb68).

v0.3.4 (compare) - 2018-09-22


  • Fix writing UTF-8 contents to file for Python 2 (9e99b23).


v0.3.3 (compare) - 2018-09-18


  • Fix manifest (missing (62ccfaf).

v0.3.2 (compare) - 2018-09-18


  • Add logo and demo.svg to fix PyPI page (1e06662).

v0.3.1 (compare) - 2018-09-18


  • Reduce size of package, simplify manifest (f123b53).
  • Switch documents to markdown (f3917e9).

v0.3.0 (compare) - 2018-09-17


  • Add credits in wikipage template (e70b7c8).
  • Add groupby_unsorted filter to improve option rendering (2e42177).
  • Add logo (f9289a0).
  • Add new reader module (ea13cfb).
  • Add option to smart_width to indent first line or not (e625afb).
  • Add vcsroot name variable (f5db3b3).


  • Change README.rst to (4628e76).


  • Fix code block (de304ee).
  • Fix credits and readme url to gitlab plugins doc (9958019).
  • Fix get context from env (f1e2296).
  • Fix usage tag (4a47431).
  • Fix wikipage template (2f5a0ad).


  • Remove blank line in AUTHORS (e414282).
  • Remove formatter options, enforce user behavior (48c26d0).
  • Remove MPL2.0 notices in sources (now ISC) (87e92df).
  • Remove pyup file, remove option-description subtag (implicit) (4a08fa1).


  • Allow failure for style and spell on travis (4a7a60f).
  • Automatically compute indent_str from indent, cast indent to int (0a09554).
  • Handle multiple file input/output, fix some templates vars, format with black (2c6672b).
  • Ignore bandit warning as irrelevant (no html templates) (4947fe5).
  • Implement context abilities (5e7c9d4).
  • Implement plugin abilities (cd4723f).
  • Implement smart_width for text format, write more templates (bb15f51).
  • Improve helptext usage display, fix smartwrap indent (11f78bf).
  • Improve manpage groff template, fix various issues (b829593).
  • Link up with argparse (12f186d).
  • Rename tag to section (5e80735).
  • Update demo script and svg (ec0c282).
  • Update docs, simplify context usage (8c6c950).
  • Use GitLab-CI instead of Travis (de662d0).

v0.2.2 (compare) - 2017-05-02


  • Change license from MPL 2.0 to ISC (no 'same license' condition) (868b89e).


  • Fix cli main return None -> 0 (7beeecc).
  • Fix codacy badge (fe55efb).
  • Fix docs spelling (69988a2).
  • Fix installation instruction (--user does not install entry point...) (aa2037b).
  • Fix man synopsis section (d79db9a).


  • Begin to fix output option (f1e5488).
  • Hide sphinx warnings, travis install enchant (c216c78).
  • Use codacy instead of codecov (c024b1c).

v0.2.1 (compare) - 2016-12-06


  • Update README, fix help display (a131b82).

v0.2.0 (compare) - 2016-12-06


  • Add check feature, add tests (4916b51).
  • Add demo example (ec78d6b).
  • Add markdown format, improve python3 compatibility, add gitignore (6b8c295).
  • Add tests (4d08087).


  • Fix changing release date over upstream update (11738c4).
  • Fix command line usage and tests usage combination (bcef7c9).
  • Fix dangerous warning about sys.argv as default value (effe263).


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

shellman-0.4.1.tar.gz (28.8 kB view hashes)

Uploaded source

Built Distribution

shellman-0.4.1-py2.py3-none-any.whl (25.1 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page