Browse Source

Add dddoc/

Matteo Cypriani 8 months ago
parent
commit
7e3d60ad25
2 changed files with 239 additions and 0 deletions
  1. 70
    0
      dddoc/README.md
  2. 169
    0
      dddoc/dddoc.sh

+ 70
- 0
dddoc/README.md View File

@@ -0,0 +1,70 @@
1
+_This documentation file was extracted from `dddoc.sh` using the following
2
+command:_
3
+
4
+    ./dddoc.sh -d . dddoc.sh && mv dddoc.sh.md README.md
5
+
6
+dddoc -- Double-Dièse Documentation extractor
7
+=============================================
8
+
9
+This script is designed to extract inline documentation from shell scripts
10
+or libraries, or any other language using the sharp (#) as a comment mark.
11
+It follows the tradition of POD (Plain Old Documentation), but permits an
12
+easier-to-read syntax, allowing you to use the markup language that suits 
13
+you (such as MarkDown, txt2tags, etc.).
14
+
15
+The only pre-requisite is that the comment lines to be extracted start with
16
+two sharps (##), hence the name of this script ("dièse" stands for "sharp"
17
+in French). The two sharps must be followed by at least one space or an end
18
+of line for the line to be extracted; for instance, lines starting with
19
+three sharps won't be extracted. Both sharps starting the line, and exactly
20
+one space (if any) will be stripped.
21
+
22
+Each output file bares the name of the corresponding input file, with a
23
+user-defined suffix (`-s` switch), that defaults to "md".
24
+
25
+The input file hierarchy is respected, and this script is best used along
26
+with `find` and `xargs`, for instance:
27
+
28
+    cd /project/path
29
+    find * -type f -print0 | xargs -0 dddoc /path/to/destdir
30
+
31
+The destination directory could be a clone of a GitLab wiki (or Gitea, or
32
+GitHub...), which will allow you to easily publish a nice-looking set of
33
+docs.
34
+
35
+License
36
+=======
37
+
38
+Copyright 2018 Matteo Cypriani <mcy@lm7.fr>
39
+
40
+This program is free software. It comes without any warranty, to the extent
41
+permitted by applicable law. You can redistribute it and/or modify it under
42
+the terms of the Do What The Fuck You Want To Public License, Version 2, as
43
+published by Sam Hocevar. See http://sam.zoy.org/wtfpl/COPYING for more
44
+details.
45
+
46
+Globals
47
+=======
48
+
49
+This section and the followings document `dddoc.sh`; they are not
50
+particularly interesting, but are meant as a demonstration and documenting
51
+guide.
52
+
53
+- `PROGNAME`: this script's name
54
+- `DESTDIR`: output directory
55
+- `VERBOSE`: verbose level
56
+- `SUFFIX`: suffix (extension) of output files
57
+- `REGEX`: the regular expression that determines which lines will be
58
+  extracted from input files
59
+
60
+Functions
61
+=========
62
+
63
+print_usage()
64
+-------------
65
+Prints the usage message.
66
+
67
+bad_usage()
68
+-----------
69
+Prints the usage message to the standard error and exits with an error code.
70
+

+ 169
- 0
dddoc/dddoc.sh View File

@@ -0,0 +1,169 @@
1
+#!/bin/sh
2
+#
3
+## _This documentation file was extracted from `dddoc.sh` using the following
4
+## command:_
5
+##
6
+##     ./dddoc.sh -d . dddoc.sh && mv dddoc.sh.md README.md
7
+##
8
+## dddoc -- Double-Dièse Documentation extractor
9
+## =============================================
10
+##
11
+## This script is designed to extract inline documentation from shell scripts
12
+## or libraries, or any other language using the sharp (#) as a comment mark.
13
+## It follows the tradition of POD (Plain Old Documentation), but permits an
14
+## easier-to-read syntax, allowing you to use the markup language that suits
15
+## you (such as MarkDown, txt2tags, etc.).
16
+##
17
+## The only pre-requisite is that the comment lines to be extracted start with
18
+## two sharps (##), hence the name of this script ("dièse" stands for "sharp"
19
+## in French). The two sharps must be followed by at least one space or an end
20
+## of line for the line to be extracted; for instance, lines starting with
21
+## three sharps won't be extracted. Both sharps starting the line, and exactly
22
+## one space (if any) will be stripped.
23
+##
24
+## Each output file bares the name of the corresponding input file, with a
25
+## user-defined suffix (`-s` switch), that defaults to "md".
26
+##
27
+## The input file hierarchy is respected, and this script is best used along
28
+## with `find` and `xargs`, for instance:
29
+##
30
+##     cd /project/path
31
+##     find * -type f -print0 | xargs -0 dddoc /path/to/destdir
32
+##
33
+## The destination directory could be a clone of a GitLab wiki (or Gitea, or
34
+## GitHub...), which will allow you to easily publish a nice-looking set of
35
+## docs.
36
+##
37
+## License
38
+## =======
39
+##
40
+## Copyright 2018 Matteo Cypriani <mcy@lm7.fr>
41
+##
42
+## This program is free software. It comes without any warranty, to the extent
43
+## permitted by applicable law. You can redistribute it and/or modify it under
44
+## the terms of the Do What The Fuck You Want To Public License, Version 2, as
45
+## published by Sam Hocevar. See http://sam.zoy.org/wtfpl/COPYING for more
46
+## details.
47
+
48
+set -e
49
+#set -x
50
+
51
+##
52
+## Globals
53
+## =======
54
+##
55
+## This section and the followings document `dddoc.sh`; they are not
56
+## particularly interesting, but are meant as a demonstration and documenting
57
+## guide.
58
+##
59
+
60
+## - `PROGNAME`: this script's name
61
+PROGNAME="$(basename "$0")"
62
+
63
+## - `DESTDIR`: output directory
64
+DESTDIR=
65
+
66
+## - `VERBOSE`: verbose level
67
+VERBOSE=1
68
+
69
+## - `SUFFIX`: suffix (extension) of output files
70
+SUFFIX=".md"
71
+
72
+## - `REGEX`: the regular expression that determines which lines will be
73
+##   extracted from input files
74
+REGEX='^##( |$)'
75
+
76
+##
77
+## Functions
78
+## =========
79
+##
80
+
81
+## print_usage()
82
+## -------------
83
+## Prints the usage message.
84
+##
85
+print_usage()
86
+{
87
+    cat <<EOF
88
+Usage:
89
+    $PROGNAME [-h]
90
+    $PROGNAME -d <output_dir> [-s <suffix>] [-v] <file1> [file2 ...]
91
+Options:
92
+    -h: display this help and exit
93
+    -d: output files' destination directory
94
+    -s: output files' suffix (default: "$SUFFIX")
95
+    -q: set verbose level to 0
96
+    -v: increment verbose level; this option can be provided several times
97
+Verbose levels (default is $VERBOSE):
98
+    0 = silent
99
+    1 = display global options
100
+    2 = print a message for each generated files
101
+    3 = print a message for skipped files as well
102
+EOF
103
+}
104
+
105
+## bad_usage()
106
+## -----------
107
+## Prints the usage message to the standard error and exits with an error code.
108
+##
109
+bad_usage()
110
+{
111
+    print_usage >&2
112
+    exit 127
113
+}
114
+
115
+
116
+###
117
+### Main program
118
+### ============
119
+### (Note that these triple-dashed comments won't be extracted by this script.)
120
+###
121
+
122
+# Parse CLI options
123
+while getopts d:hqs:v option ; do
124
+    case $option in
125
+        h)  print_usage
126
+            exit 0
127
+            ;;
128
+        d)  DESTDIR="$OPTARG" ;;
129
+        q)  VERBOSE=0 ;;
130
+        s)  SUFFIX=".$OPTARG" ;;
131
+        v)  VERBOSE=$((VERBOSE + 1)) ;;
132
+        *)  bad_usage
133
+    esac
134
+done
135
+shift $((OPTIND - 1))
136
+
137
+# Check CLI options
138
+if [ -z "$DESTDIR" ] || [ $# -lt 1 ] ; then
139
+    bad_usage
140
+fi
141
+
142
+if [ $VERBOSE -ge 1 ] ; then
143
+    printf 'Verbose level: %d\n' "$VERBOSE"
144
+    printf 'Will use "%s" as the destination directory.\n' "$DESTDIR"
145
+    printf 'Will use "%s" as a suffix for output files.\n' "$SUFFIX"
146
+fi
147
+
148
+while [ -n "$1" ] ; do
149
+    src="$1"
150
+    shift
151
+    srcdir="$(dirname "$src")"
152
+    destdir="$DESTDIR/$srcdir"
153
+    dest="$destdir/$(basename "$src")$SUFFIX"
154
+
155
+    if ! grep -Eq "$REGEX" "$src" ; then
156
+        [ $VERBOSE -ge 3 ] && printf \
157
+            "\"%s\" doesn't seem to contain any double-sharp comments. Skipping.\\n" \
158
+            "$src"
159
+        continue
160
+    fi
161
+
162
+    [ $VERBOSE -ge 2 ] && \
163
+        printf 'Extracting doc from "%s" to "%s"...\n' "$src" "$dest"
164
+
165
+    mkdir -p "$destdir"
166
+    sed -rn "s/$REGEX//p" "$src" >"$dest"
167
+done
168
+
169
+# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4

Loading…
Cancel
Save