From 7e3d60ad25d8466ebd39646255e17cd594f64aa7 Mon Sep 17 00:00:00 2001 From: Matteo Cypriani Date: Fri, 4 May 2018 13:05:56 +0200 Subject: [PATCH] Add dddoc/ --- dddoc/README.md | 70 ++++++++++++++++++++ dddoc/dddoc.sh | 169 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 239 insertions(+) create mode 100644 dddoc/README.md create mode 100755 dddoc/dddoc.sh diff --git a/dddoc/README.md b/dddoc/README.md new file mode 100644 index 0000000..3e22b67 --- /dev/null +++ b/dddoc/README.md @@ -0,0 +1,70 @@ +_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 + +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. + diff --git a/dddoc/dddoc.sh b/dddoc/dddoc.sh new file mode 100755 index 0000000..7c46fad --- /dev/null +++ b/dddoc/dddoc.sh @@ -0,0 +1,169 @@ +#!/bin/sh +# +## _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 +## +## 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. + +set -e +#set -x + +## +## 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 +PROGNAME="$(basename "$0")" + +## - `DESTDIR`: output directory +DESTDIR= + +## - `VERBOSE`: verbose level +VERBOSE=1 + +## - `SUFFIX`: suffix (extension) of output files +SUFFIX=".md" + +## - `REGEX`: the regular expression that determines which lines will be +## extracted from input files +REGEX='^##( |$)' + +## +## Functions +## ========= +## + +## print_usage() +## ------------- +## Prints the usage message. +## +print_usage() +{ + cat < [-s ] [-v] [file2 ...] +Options: + -h: display this help and exit + -d: output files' destination directory + -s: output files' suffix (default: "$SUFFIX") + -q: set verbose level to 0 + -v: increment verbose level; this option can be provided several times +Verbose levels (default is $VERBOSE): + 0 = silent + 1 = display global options + 2 = print a message for each generated files + 3 = print a message for skipped files as well +EOF +} + +## bad_usage() +## ----------- +## Prints the usage message to the standard error and exits with an error code. +## +bad_usage() +{ + print_usage >&2 + exit 127 +} + + +### +### Main program +### ============ +### (Note that these triple-dashed comments won't be extracted by this script.) +### + +# Parse CLI options +while getopts d:hqs:v option ; do + case $option in + h) print_usage + exit 0 + ;; + d) DESTDIR="$OPTARG" ;; + q) VERBOSE=0 ;; + s) SUFFIX=".$OPTARG" ;; + v) VERBOSE=$((VERBOSE + 1)) ;; + *) bad_usage + esac +done +shift $((OPTIND - 1)) + +# Check CLI options +if [ -z "$DESTDIR" ] || [ $# -lt 1 ] ; then + bad_usage +fi + +if [ $VERBOSE -ge 1 ] ; then + printf 'Verbose level: %d\n' "$VERBOSE" + printf 'Will use "%s" as the destination directory.\n' "$DESTDIR" + printf 'Will use "%s" as a suffix for output files.\n' "$SUFFIX" +fi + +while [ -n "$1" ] ; do + src="$1" + shift + srcdir="$(dirname "$src")" + destdir="$DESTDIR/$srcdir" + dest="$destdir/$(basename "$src")$SUFFIX" + + if ! grep -Eq "$REGEX" "$src" ; then + [ $VERBOSE -ge 3 ] && printf \ + "\"%s\" doesn't seem to contain any double-sharp comments. Skipping.\\n" \ + "$src" + continue + fi + + [ $VERBOSE -ge 2 ] && \ + printf 'Extracting doc from "%s" to "%s"...\n' "$src" "$dest" + + mkdir -p "$destdir" + sed -rn "s/$REGEX//p" "$src" >"$dest" +done + +# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4