Skip to content

Commit 78c3a6a

Browse files
ajdiazajdiaz
committed
fix: allow non API in args
Running bashdoc without -A flag return no content. This patch solve that issue. If not API is provided all documentation blocks as considered part of the same default API. Also add some improvements in readability in the provided CSS, and fix test. Thanks to Alan Transon for point me the missing API bug! Signed-off-by: Andrés J. Díaz <[email protected]>
1 parent 7d7778e commit 78c3a6a

6 files changed

Lines changed: 1075 additions & 214 deletions

File tree

‎Makefile‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,14 +19,14 @@ all:
1919
@ls -l $(OUTBIN)
2020

2121
test: all
22-
$(OUTBIN) -a bashdoc -f README.md -o test.html bashdoc
22+
$(OUTBIN) -T test -f README.md -o test.html bashdoc
2323
@if diff -Naurr test.html test/test.html; then \
2424
echo "Test OK"; \
2525
else \
2626
echo "Test KO"; \
2727
exit 1; \
2828
fi;
29-
rm -f test.html
29+
@rm -f test.html
3030

3131
doc: all
3232
$(OUTBIN) -T bashdoc -A bashdoc -f README.md -o doc/bashdoc.html bashdoc

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ you can see that the api name in the first function is `sum`, and in the
8383
second one is `internal`. If we run bashdoc as following:
8484

8585
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.bash}
86-
bashdoc -a sum -o doc.html script.bash
86+
bashdoc -A sum -o doc.html script.bash
8787
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8888

8989
We will create documentation only for functions tagged as API *sum*. Please

‎bashdoc‎

Lines changed: 88 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -932,6 +932,71 @@ std::str2array () {
932932
declare -xa str2array_ret
933933
BLIB_VERSION='1.2-5-g84801fd'
934934
#! /bin/bash
935+
# mod: main
936+
# txt: The ``main`` module contain the specified potion body.
937+
938+
readonly VERSION="2.0.1"
939+
940+
# fun: main::init
941+
# txt: print nice potion logo and some custom messages at the beginning.
942+
main::init () {
943+
944+
out::user " ${COLOR_WARN}, ,${COLOR_NONE}"
945+
out::user " ${COLOR_WARN}/////|${COLOR_NONE}"
946+
out::user " ${COLOR_WARN}///// |${COLOR_NONE} ${COLOR_INFO} _ _ _ ${COLOR_NONE}"
947+
out::user " ${COLOR_WARN}|~~~| |${COLOR_NONE} ${COLOR_INFO}| |__ __ _ ___| |__ __| | ___ ___ ${COLOR_NONE}"
948+
out::user " ${COLOR_WARN}|===| |${COLOR_NONE} ${COLOR_INFO}| '_ \\ / _\` / __| '_ \\ / _\` |/ _ \\ / __|${COLOR_NONE}"
949+
out::user " ${COLOR_WARN}| | |${COLOR_NONE} ${COLOR_INFO}| |_) | (_| \\__ \\ | | | (_| | (_) | (__ ${COLOR_NONE}"
950+
out::user " ${COLOR_WARN}| | |${COLOR_NONE} ${COLOR_INFO}|_.__/ \\__,_|___/_| |_|\\__,_|\\___/ \\___|${COLOR_NONE}"
951+
out::user " ${COLOR_WARN}| | /${COLOR_NONE} ${COLOR_USER}version ${VERSION}${COLOR_NONE}"
952+
out::user " ${COLOR_WARN}|===|/${COLOR_NONE}"
953+
out::user " ${COLOR_WARN}'---'${COLOR_NONE}"
954+
955+
956+
957+
}
958+
959+
opt_files=""
960+
# general options handlers
961+
main::opt_version () { out::info "Bashdoc $VERSION"; exit 0;}
962+
main::opt_title () { TITLE="$1"; return 2; }
963+
main::opt_author () { AUTHOR="$1"; return 2; }
964+
main::opt_output () { OUTPUT="$1"; return 2; }
965+
main::opt_date () { DATE="$(date +%Y-%m-%d)"; return 1; }
966+
main::opt_file () { opt_files="$opt_files $1"; return 2; }
967+
main::opt_api () { API="$1"; return 2; }
968+
main::opt_style () { __opt__style="$1"; echo "$@" ; return 2; }
969+
main::opt_template () { __opt__template="$1"; return 2; }
970+
main::opt_highlight () { __opt__highlight="$1"; return 2; }
971+
972+
# main function really
973+
main::action () {
974+
main::init
975+
doc::generate "$@"
976+
}
977+
978+
main () {
979+
arg::opt MAIN -V --version main::opt_version 'show program version number'
980+
arg::opt MAIN -T --title main::opt_title 'set the title of the document'
981+
arg::opt MAIN -a --author main::opt_author 'set the author of the document'
982+
arg::opt MAIN -o --output main::opt_output 'set the output file name'
983+
arg::opt MAIN -d --include-date main::opt_date 'add date to the document'
984+
arg::opt MAIN -f --file main::opt_file 'add more section files'
985+
arg::opt MAIN -A --api main::opt_api 'set api to be documented'
986+
arg::opt MAIN -s --style main::opt_style 'path to CSS stylesheet'
987+
arg::opt MAIN -t --template main::opt_template 'path to HTML template'
988+
arg::opt MAIN -H --highlight-theme main::opt_highlight \
989+
'theme name to highlight code'
990+
991+
arg::main::help "Generate documentation for bash programs"
992+
arg::main::action main::action
993+
994+
arg::param MAIN "script+" \
995+
'Path or URL to script to create documentation'
996+
997+
arg::parse "$@"
998+
}
999+
#! /bin/bash
9351000
# mod: doc
9361001
# api: bashdoc
9371002
# txt: The `doc` module provides functions to convert bash source code to
@@ -1022,15 +1087,23 @@ DOC_CSS='
10221087
font-style: italic;
10231088
}
10241089
1025-
.module h2 { margin-bottom:0.2em; margin-top: 2.5em;}
1090+
.module h2 {
1091+
border-bottom:1px solid #444;
1092+
margin:2em 0 1em 0;
1093+
}
10261094
.module h2:before {
10271095
content: "module";
1028-
color: #888;
1096+
color: #444;
10291097
font-family: monospace;
10301098
font-size: 90%;
10311099
padding-right:0.4em;
10321100
}
10331101
1102+
.module h3 {
1103+
border-bottom:1px solid #dadada;
1104+
margin:2em 0 1em 0;
1105+
}
1106+
10341107
.module h3:before {
10351108
content: "function";
10361109
color: #888;
@@ -1160,7 +1233,7 @@ DOCSTRING="${DOCSTRING:-# }"
11601233
# use: doc::read_blocks v1 < script
11611234
doc::read_blocks ()
11621235
{
1163-
local block_name=MAIN func_name= key=
1236+
local block_name=MAIN func_name
11641237
local in_opt=false in_env=false in_use=false in_pre=false indent=''
11651238
__doc__apis=()
11661239
__doc__mods=()
@@ -1177,7 +1250,7 @@ doc::read_blocks ()
11771250
_reset_env () { in_env=false; }
11781251
_reset_use () { in_use=false; }
11791252

1180-
while read line; do
1253+
while read -r line; do
11811254
# some minor replacements required for markdown parser
11821255
line="${line//</\<}"
11831256
line="${line//>/\>}"
@@ -1276,6 +1349,7 @@ doc::read_blocks ()
12761349

12771350
_reset_pre
12781351

1352+
declare -a sort_ret=()
12791353
std::sort "${!__doc__mods[@]}"
12801354

12811355
for x in "${sort_ret[@]}"; do
@@ -1315,10 +1389,16 @@ doc::output ()
13151389
done
13161390
for doc in "$@"; do
13171391
local docname="${doc#./}"
1318-
for api in ${API//,/ }; do
1319-
echo "# $api API Reference" && echo
1320-
doc::read_blocks "$api" < "$doc"
1321-
done
1392+
1393+
if [[ "$API" ]]; then
1394+
for api in ${API//,/ }; do
1395+
echo "# $api API Reference" && echo
1396+
doc::read_blocks "$api" < "$doc"
1397+
done
1398+
else
1399+
echo "# API Reference" && echo
1400+
doc::read_blocks "" < "$doc"
1401+
fi
13221402
echo -e "\n---\n"
13231403
done
13241404
}
@@ -1355,70 +1435,5 @@ doc::generate ()
13551435
<(echo "$(doc::output "$@")") \
13561436
$output
13571437
}
1358-
#! /bin/bash
1359-
# mod: main
1360-
# txt: The ``main`` module contain the specified potion body.
1361-
1362-
readonly VERSION="2.0.1"
1363-
1364-
# fun: main::init
1365-
# txt: print nice potion logo and some custom messages at the beginning.
1366-
main::init () {
1367-
1368-
out::user " ${COLOR_WARN}, ,${COLOR_NONE}"
1369-
out::user " ${COLOR_WARN}/////|${COLOR_NONE}"
1370-
out::user " ${COLOR_WARN}///// |${COLOR_NONE} ${COLOR_INFO} _ _ _ ${COLOR_NONE}"
1371-
out::user " ${COLOR_WARN}|~~~| |${COLOR_NONE} ${COLOR_INFO}| |__ __ _ ___| |__ __| | ___ ___ ${COLOR_NONE}"
1372-
out::user " ${COLOR_WARN}|===| |${COLOR_NONE} ${COLOR_INFO}| '_ \\ / _\` / __| '_ \\ / _\` |/ _ \\ / __|${COLOR_NONE}"
1373-
out::user " ${COLOR_WARN}| | |${COLOR_NONE} ${COLOR_INFO}| |_) | (_| \\__ \\ | | | (_| | (_) | (__ ${COLOR_NONE}"
1374-
out::user " ${COLOR_WARN}| | |${COLOR_NONE} ${COLOR_INFO}|_.__/ \\__,_|___/_| |_|\\__,_|\\___/ \\___|${COLOR_NONE}"
1375-
out::user " ${COLOR_WARN}| | /${COLOR_NONE} ${COLOR_USER}version ${VERSION}${COLOR_NONE}"
1376-
out::user " ${COLOR_WARN}|===|/${COLOR_NONE}"
1377-
out::user " ${COLOR_WARN}'---'${COLOR_NONE}"
1378-
1379-
1380-
1381-
}
1382-
1383-
opt_files=""
1384-
# general options handlers
1385-
main::opt_version () { out::info "Bashdoc $VERSION"; exit 0;}
1386-
main::opt_title () { TITLE="$1"; return 2; }
1387-
main::opt_author () { AUTHOR="$1"; return 2; }
1388-
main::opt_output () { OUTPUT="$1"; return 2; }
1389-
main::opt_date () { DATE="$(date +%Y-%m-%d)"; return 1; }
1390-
main::opt_file () { opt_files="$opt_files $1"; return 2; }
1391-
main::opt_api () { API="$1"; return 2; }
1392-
main::opt_style () { __opt__style="$1"; echo "$@" ; return 2; }
1393-
main::opt_template () { __opt__template="$1"; return 2; }
1394-
main::opt_highlight () { __opt__highlight="$1"; return 2; }
1395-
1396-
# main function really
1397-
main::action () {
1398-
main::init
1399-
doc::generate "$@"
1400-
}
1401-
1402-
main () {
1403-
arg::opt MAIN -V --version main::opt_version 'show program version number'
1404-
arg::opt MAIN -T --title main::opt_title 'set the title of the document'
1405-
arg::opt MAIN -a --author main::opt_author 'set the author of the document'
1406-
arg::opt MAIN -o --output main::opt_output 'set the output file name'
1407-
arg::opt MAIN -d --include-date main::opt_date 'add date to the document'
1408-
arg::opt MAIN -f --file main::opt_file 'add more section files'
1409-
arg::opt MAIN -A --api main::opt_api 'set api to be documented'
1410-
arg::opt MAIN -s --style main::opt_style 'path to CSS stylesheet'
1411-
arg::opt MAIN -t --template main::opt_template 'path to HTML template'
1412-
arg::opt MAIN -H --highlight-theme main::opt_highlight \
1413-
'theme name to highlight code'
1414-
1415-
arg::main::help "Generate documentation for bash programs"
1416-
arg::main::action main::action
1417-
1418-
arg::param MAIN "script+" \
1419-
'Path or URL to script to create documentation'
1420-
1421-
arg::parse "$@"
1422-
}
14231438
std::installed 'pandoc' || err::trace 'pandoc is required but not found'
14241439
main "$@"

‎doc/bashdoc.html‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -155,15 +155,23 @@
155155
font-style: italic;
156156
}
157157

158-
.module h2 { margin-bottom:0.2em; margin-top: 2.5em;}
158+
.module h2 {
159+
border-bottom:1px solid #444;
160+
margin:2em 0 1em 0;
161+
}
159162
.module h2:before {
160163
content: "module";
161-
color: #888;
164+
color: #444;
162165
font-family: monospace;
163166
font-size: 90%;
164167
padding-right:0.4em;
165168
}
166169

170+
.module h3 {
171+
border-bottom:1px solid #dadada;
172+
margin:2em 0 1em 0;
173+
}
174+
167175
.module h3:before {
168176
content: "function";
169177
color: #888;
@@ -297,7 +305,7 @@ <h2>Using API name</h2>
297305
<span id="cb3-6"><a href="#cb3-6" aria-hidden="true"></a> <span class="bu">echo</span> 0</span>
298306
<span id="cb3-7"><a href="#cb3-7" aria-hidden="true"></a><span class="kw">}</span></span></code></pre></div>
299307
<p>If we generate the HTML in the same way that we do previously, the result HTML will contain two documented functions: <code>sum</code> and <code>internal_sum</code>, but we don’t want the second one in the documentation. Of course we can remove the doc strings from there, but then we loose the documentation in the code too. To avoid this problem we can use the API name. If you look carefully, you can see that the api name in the first function is <code>sum</code>, and in the second one is <code>internal</code>. If we run bashdoc as following:</p>
300-
<div class="sourceCode" id="cb4"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true"></a><span class="ex">bashdoc</span> -a sum -o doc.html script.bash</span></code></pre></div>
308+
<div class="sourceCode" id="cb4"><pre class="sourceCode bash"><code class="sourceCode bash"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true"></a><span class="ex">bashdoc</span> -A sum -o doc.html script.bash</span></code></pre></div>
301309
<p>We will create documentation only for functions tagged as API <em>sum</em>. Please note that if you force a specific API tag, then functions or modules without declared API will be not documented.</p>
302310
</section>
303311
<section id="using-custom-stylesheet" class="level2">

‎src/doc‎

Lines changed: 23 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -89,15 +89,23 @@ DOC_CSS='
8989
font-style: italic;
9090
}
9191
92-
.module h2 { margin-bottom:0.2em; margin-top: 2.5em;}
92+
.module h2 {
93+
border-bottom:1px solid #444;
94+
margin:2em 0 1em 0;
95+
}
9396
.module h2:before {
9497
content: "module";
95-
color: #888;
98+
color: #444;
9699
font-family: monospace;
97100
font-size: 90%;
98101
padding-right:0.4em;
99102
}
100103
104+
.module h3 {
105+
border-bottom:1px solid #dadada;
106+
margin:2em 0 1em 0;
107+
}
108+
101109
.module h3:before {
102110
content: "function";
103111
color: #888;
@@ -227,7 +235,7 @@ DOCSTRING="${DOCSTRING:-# }"
227235
# use: doc::read_blocks v1 < script
228236
doc::read_blocks ()
229237
{
230-
local block_name=MAIN func_name= key=
238+
local block_name=MAIN func_name
231239
local in_opt=false in_env=false in_use=false in_pre=false indent=''
232240
__doc__apis=()
233241
__doc__mods=()
@@ -244,7 +252,7 @@ doc::read_blocks ()
244252
_reset_env () { in_env=false; }
245253
_reset_use () { in_use=false; }
246254

247-
while read line; do
255+
while read -r line; do
248256
# some minor replacements required for markdown parser
249257
line="${line//</\<}"
250258
line="${line//>/\>}"
@@ -343,6 +351,7 @@ doc::read_blocks ()
343351

344352
_reset_pre
345353

354+
declare -a sort_ret=()
346355
std::sort "${!__doc__mods[@]}"
347356

348357
for x in "${sort_ret[@]}"; do
@@ -382,10 +391,16 @@ doc::output ()
382391
done
383392
for doc in "$@"; do
384393
local docname="${doc#./}"
385-
for api in ${API//,/ }; do
386-
echo "# $api API Reference" && echo
387-
doc::read_blocks "$api" < "$doc"
388-
done
394+
395+
if [[ "$API" ]]; then
396+
for api in ${API//,/ }; do
397+
echo "# $api API Reference" && echo
398+
doc::read_blocks "$api" < "$doc"
399+
done
400+
else
401+
echo "# API Reference" && echo
402+
doc::read_blocks "" < "$doc"
403+
fi
389404
echo -e "\n---\n"
390405
done
391406
}

0 commit comments

Comments
 (0)