Add dddoc/

This commit is contained in:
Matteo Cypriani 2018-05-04 13:05:56 +02:00
parent f9ccbd3f92
commit 7e3d60ad25
2 changed files with 239 additions and 0 deletions

70
dddoc/README.md Normal file
View File

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

169
dddoc/dddoc.sh Executable file
View File

@ -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 <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.
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 <<EOF
Usage:
$PROGNAME [-h]
$PROGNAME -d <output_dir> [-s <suffix>] [-v] <file1> [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