shellman 0.4.0

Write documentation in comments and render it with templates.

Shell Script Documentation

Write documentation in comments and render it with templates.

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

For example:

#!/bin/bash

## \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 ;;
  esac
}

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

Output when calling ./demo -h:

Usage: demo [-h]

This script actually does nothing.

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

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

• GitLab wiki
• GitHub wiki

Demo

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.

Installation

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

License

Software licensed under ISC license.

Changelog

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.0 (compare) - 2018-09-28

Added

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

Fixed

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

Misc

• Improve error messages (96ebb68).

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

Fixed

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

Misc

• Improve credits line (f7a7cae).

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

Fixed

• Fix manifest (missing setup.py) (62ccfaf).

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

Misc

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

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

Misc

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

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

Added

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

Changed

• Change README.rst to README.md (4628e76).

Fixed

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

Removed

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

Misc

• 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

Changed

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

Fixed

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

Misc

• 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

Misc

• Update README, fix help display (a131b82).

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

Added

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

Fixed

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

Misc

• Implement new structure (40b4806).
• Setup tests (5d50692).
• Write doc (1a8e0e4).