scripts/dddoc
Matteo Cypriani 7e3d60ad25 Add dddoc/ 2018-05-04 17:02:32 +02:00
..
README.md Add dddoc/ 2018-05-04 17:02:32 +02:00
dddoc.sh Add dddoc/ 2018-05-04 17:02:32 +02:00

README.md

This documentation file was extracted from dddoc.sh using the following command:

./dddoc.sh -d . dddoc.sh && mv dddoc.sh.md README.md

dddoc -- Double-Dièse Documentation extractor

This script is designed to extract inline documentation from shell scripts or libraries, or any other language using the sharp (#) as a comment mark. It follows the tradition of POD (Plain Old Documentation), but permits an easier-to-read syntax, allowing you to use the markup language that suits you (such as MarkDown, txt2tags, etc.).

The only pre-requisite is that the comment lines to be extracted start with two sharps (##), hence the name of this script ("dièse" stands for "sharp" in French). The two sharps must be followed by at least one space or an end of line for the line to be extracted; for instance, lines starting with three sharps won't be extracted. Both sharps starting the line, and exactly one space (if any) will be stripped.

Each output file bares the name of the corresponding input file, with a user-defined suffix (-s switch), that defaults to "md".

The input file hierarchy is respected, and this script is best used along with find and xargs, for instance:

cd /project/path
find * -type f -print0 | xargs -0 dddoc /path/to/destdir

The destination directory could be a clone of a GitLab wiki (or Gitea, or GitHub...), which will allow you to easily publish a nice-looking set of docs.

License

Copyright 2018 Matteo Cypriani mcy@lm7.fr

This program is free software. It comes without any warranty, to the extent permitted by applicable law. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2, as published by Sam Hocevar. See http://sam.zoy.org/wtfpl/COPYING for more details.

Globals

This section and the followings document dddoc.sh; they are not particularly interesting, but are meant as a demonstration and documenting guide.

  • PROGNAME: this script's name
  • DESTDIR: output directory
  • VERBOSE: verbose level
  • SUFFIX: suffix (extension) of output files
  • REGEX: the regular expression that determines which lines will be extracted from input files

Functions

print_usage()

Prints the usage message.

bad_usage()

Prints the usage message to the standard error and exits with an error code.