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]>
ajdiaz · Sep 4, 2020 · 78c3a6a · 78c3a6a
1 parent 7d7778e
commit 78c3a6a
Show file tree

Hide file tree

Showing 6 changed files with 1,075 additions and 214 deletions.
diff --git a/Makefile b/Makefile
@@ -19,14 +19,14 @@ all:
 	@ls -l $(OUTBIN)
 
 test: all
-	 $(OUTBIN) -a bashdoc -f README.md -o test.html bashdoc
+	 $(OUTBIN) -T test -f README.md -o test.html bashdoc
 	 @if diff -Naurr test.html test/test.html; then \
 	    echo "Test OK"; \
 	 else \
 	    echo "Test KO"; \
 	    exit 1; \
 	 fi;
-	 rm -f test.html
+	 @rm -f test.html
 
 doc: all
 	$(OUTBIN) -T bashdoc -A bashdoc -f README.md -o doc/bashdoc.html bashdoc

diff --git a/README.md b/README.md
@@ -83,7 +83,7 @@ you can see that the api name in the first function is `sum`, and in the
 second one is `internal`. If we run bashdoc as following:
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.bash}
-bashdoc -a sum -o doc.html script.bash
+bashdoc -A sum -o doc.html script.bash
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We will create documentation only for functions tagged as API *sum*. Please

diff --git a/bashdoc b/bashdoc
@@ -932,6 +932,71 @@ std::str2array () {
 declare -xa str2array_ret
 BLIB_VERSION='1.2-5-g84801fd'
 #! /bin/bash
+# mod: main
+# txt: The ``main`` module contain the specified potion body.
+
+readonly VERSION="2.0.1"
+
+# fun: main::init
+# txt: print nice potion logo and some custom messages at the beginning.
+main::init () {
+
+out::user "    ${COLOR_WARN},   ,${COLOR_NONE}"
+out::user "   ${COLOR_WARN}/////|${COLOR_NONE}"
+out::user "  ${COLOR_WARN}///// |${COLOR_NONE} ${COLOR_INFO} _               _         _            ${COLOR_NONE}"
+out::user " ${COLOR_WARN}|~~~|  |${COLOR_NONE} ${COLOR_INFO}| |__   __ _ ___| |__   __| | ___   ___ ${COLOR_NONE}"
+out::user " ${COLOR_WARN}|===|  |${COLOR_NONE} ${COLOR_INFO}| '_ \\ / _\` / __| '_ \\ / _\` |/ _ \\ / __|${COLOR_NONE}"
+out::user " ${COLOR_WARN}|   |  |${COLOR_NONE} ${COLOR_INFO}| |_) | (_| \\__ \\ | | | (_| | (_) | (__ ${COLOR_NONE}"
+out::user " ${COLOR_WARN}|   |  |${COLOR_NONE} ${COLOR_INFO}|_.__/ \\__,_|___/_| |_|\\__,_|\\___/ \\___|${COLOR_NONE}"
+out::user " ${COLOR_WARN}|   | /${COLOR_NONE}  ${COLOR_USER}version ${VERSION}${COLOR_NONE}"
+out::user " ${COLOR_WARN}|===|/${COLOR_NONE}"
+out::user " ${COLOR_WARN}'---'${COLOR_NONE}"
+
+
+
+}
+
+opt_files=""
+# general options handlers
+main::opt_version () { out::info "Bashdoc $VERSION"; exit 0;}
+main::opt_title () { TITLE="$1"; return 2; }
+main::opt_author () { AUTHOR="$1"; return 2; }
+main::opt_output () { OUTPUT="$1"; return 2; }
+main::opt_date () { DATE="$(date +%Y-%m-%d)"; return 1; }
+main::opt_file () { opt_files="$opt_files $1"; return 2; }
+main::opt_api () { API="$1"; return 2; }
+main::opt_style () { __opt__style="$1"; echo "$@" ; return 2; }
+main::opt_template () { __opt__template="$1"; return 2; }
+main::opt_highlight () { __opt__highlight="$1"; return 2; }
+
+# main function really
+main::action () {
+  main::init
+  doc::generate "$@"
+}
+
+main () {
+  arg::opt MAIN -V --version main::opt_version 'show program version number'
+  arg::opt MAIN -T --title   main::opt_title   'set the title of the document'
+  arg::opt MAIN -a --author  main::opt_author  'set the author of the document'
+  arg::opt MAIN -o --output  main::opt_output  'set the output file name'
+  arg::opt MAIN -d --include-date  main::opt_date   'add date to the document'
+  arg::opt MAIN -f --file    main::opt_file         'add more section files'
+  arg::opt MAIN -A --api     main::opt_api          'set api to be documented'
+  arg::opt MAIN -s --style   main::opt_style        'path to CSS stylesheet'
+  arg::opt MAIN -t --template  main::opt_template   'path to HTML template'
+  arg::opt MAIN -H --highlight-theme  main::opt_highlight \
+    'theme name to highlight code'
+
+  arg::main::help "Generate documentation for bash programs"
+  arg::main::action main::action
+
+  arg::param MAIN "script+" \
+    'Path or URL to script to create documentation'
+
+  arg::parse "$@"
+}
+#! /bin/bash
 # mod: doc
 # api: bashdoc
 # txt: The `doc` module provides functions to convert bash source code to
@@ -1022,15 +1087,23 @@ DOC_CSS='
       font-style: italic;
     }
 
-  .module h2 { margin-bottom:0.2em; margin-top: 2.5em;}
+  .module h2 {
+    border-bottom:1px solid #444;
+    margin:2em 0 1em 0;
+  }
   .module h2:before {
      content: "module";
-     color: #888;
+     color: #444;
      font-family: monospace;
      font-size: 90%;
      padding-right:0.4em;
   }
 
+  .module h3 {
+    border-bottom:1px solid #dadada;
+    margin:2em 0 1em 0;
+  }
+
   .module h3:before {
      content: "function";
      color: #888;
@@ -1160,7 +1233,7 @@ DOCSTRING="${DOCSTRING:-# }"
 # use: doc::read_blocks v1 < script
 doc::read_blocks ()
 {
-  local block_name=MAIN func_name= key=
+  local block_name=MAIN func_name
   local in_opt=false in_env=false in_use=false in_pre=false indent=''
   __doc__apis=()
   __doc__mods=()
@@ -1177,7 +1250,7 @@ doc::read_blocks ()
   _reset_env () { in_env=false; }
   _reset_use () { in_use=false; }
 
-  while read line; do
+  while read -r line; do
     # some minor replacements required for markdown parser
     line="${line//</\<}"
     line="${line//>/\>}"
@@ -1276,6 +1349,7 @@ doc::read_blocks ()
 
   _reset_pre
 
+  declare -a sort_ret=()
   std::sort "${!__doc__mods[@]}"
 
   for x in "${sort_ret[@]}"; do
@@ -1315,10 +1389,16 @@ doc::output ()
   done
   for doc in "$@"; do
     local docname="${doc#./}"
-    for api in ${API//,/ }; do
-      echo "# $api API Reference" && echo
-      doc::read_blocks "$api" < "$doc"
-    done
+
+    if [[ "$API" ]]; then
+      for api in ${API//,/ }; do
+        echo "# $api API Reference" && echo
+        doc::read_blocks "$api" < "$doc"
+      done
+    else
+      echo "# API Reference" && echo
+      doc::read_blocks "" < "$doc"
+    fi
     echo -e "\n---\n"
   done
 }
@@ -1355,70 +1435,5 @@ doc::generate ()
     <(echo "$(doc::output "$@")") \
     $output
 }
-#! /bin/bash
-# mod: main
-# txt: The ``main`` module contain the specified potion body.
-
-readonly VERSION="2.0.1"
-
-# fun: main::init
-# txt: print nice potion logo and some custom messages at the beginning.
-main::init () {
-
-out::user "    ${COLOR_WARN},   ,${COLOR_NONE}"
-out::user "   ${COLOR_WARN}/////|${COLOR_NONE}"
-out::user "  ${COLOR_WARN}///// |${COLOR_NONE} ${COLOR_INFO} _               _         _            ${COLOR_NONE}"
-out::user " ${COLOR_WARN}|~~~|  |${COLOR_NONE} ${COLOR_INFO}| |__   __ _ ___| |__   __| | ___   ___ ${COLOR_NONE}"
-out::user " ${COLOR_WARN}|===|  |${COLOR_NONE} ${COLOR_INFO}| '_ \\ / _\` / __| '_ \\ / _\` |/ _ \\ / __|${COLOR_NONE}"
-out::user " ${COLOR_WARN}|   |  |${COLOR_NONE} ${COLOR_INFO}| |_) | (_| \\__ \\ | | | (_| | (_) | (__ ${COLOR_NONE}"
-out::user " ${COLOR_WARN}|   |  |${COLOR_NONE} ${COLOR_INFO}|_.__/ \\__,_|___/_| |_|\\__,_|\\___/ \\___|${COLOR_NONE}"
-out::user " ${COLOR_WARN}|   | /${COLOR_NONE}  ${COLOR_USER}version ${VERSION}${COLOR_NONE}"
-out::user " ${COLOR_WARN}|===|/${COLOR_NONE}"
-out::user " ${COLOR_WARN}'---'${COLOR_NONE}"
-
-
-
-}
-
-opt_files=""
-# general options handlers
-main::opt_version () { out::info "Bashdoc $VERSION"; exit 0;}
-main::opt_title () { TITLE="$1"; return 2; }
-main::opt_author () { AUTHOR="$1"; return 2; }
-main::opt_output () { OUTPUT="$1"; return 2; }
-main::opt_date () { DATE="$(date +%Y-%m-%d)"; return 1; }
-main::opt_file () { opt_files="$opt_files $1"; return 2; }
-main::opt_api () { API="$1"; return 2; }
-main::opt_style () { __opt__style="$1"; echo "$@" ; return 2; }
-main::opt_template () { __opt__template="$1"; return 2; }
-main::opt_highlight () { __opt__highlight="$1"; return 2; }
-
-# main function really
-main::action () {
-  main::init
-  doc::generate "$@"
-}
-
-main () {
-  arg::opt MAIN -V --version main::opt_version 'show program version number'
-  arg::opt MAIN -T --title   main::opt_title   'set the title of the document'
-  arg::opt MAIN -a --author  main::opt_author  'set the author of the document'
-  arg::opt MAIN -o --output  main::opt_output  'set the output file name'
-  arg::opt MAIN -d --include-date  main::opt_date   'add date to the document'
-  arg::opt MAIN -f --file    main::opt_file         'add more section files'
-  arg::opt MAIN -A --api     main::opt_api          'set api to be documented'
-  arg::opt MAIN -s --style   main::opt_style        'path to CSS stylesheet'
-  arg::opt MAIN -t --template  main::opt_template   'path to HTML template'
-  arg::opt MAIN -H --highlight-theme  main::opt_highlight \
-    'theme name to highlight code'
-
-  arg::main::help "Generate documentation for bash programs"
-  arg::main::action main::action
-
-  arg::param MAIN "script+" \
-    'Path or URL to script to create documentation'
-
-  arg::parse "$@"
-}
 std::installed 'pandoc' ||  err::trace 'pandoc is required but not found'
 main "$@"
diff --git a/doc/bashdoc.html b/doc/bashdoc.html
@@ -155,15 +155,23 @@
         font-style: italic;
       }
 
-    .module h2 { margin-bottom:0.2em; margin-top: 2.5em;}
+    .module h2 {
+      border-bottom:1px solid #444;
+      margin:2em 0 1em 0;
+    }
     .module h2:before {
        content: "module";
-       color: #888;
+       color: #444;
        font-family: monospace;
        font-size: 90%;
        padding-right:0.4em;
     }
 
+    .module h3 {
+      border-bottom:1px solid #dadada;
+      margin:2em 0 1em 0;
+    }
+
     .module h3:before {
        content: "function";
        color: #888;
@@ -297,7 +305,7 @@ <h2>Using API name</h2>
 <span id="cb3-6"><a href="#cb3-6" aria-hidden="true"></a>  <span class="bu">echo</span> 0</span>
 <span id="cb3-7"><a href="#cb3-7" aria-hidden="true"></a><span class="kw">}</span></span></code></pre></div>
 <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>
-<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>
+<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>
 <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>
 </section>
 <section id="using-custom-stylesheet" class="level2">

diff --git a/src/doc b/src/doc
@@ -89,15 +89,23 @@ DOC_CSS='
       font-style: italic;
     }
 
-  .module h2 { margin-bottom:0.2em; margin-top: 2.5em;}
+  .module h2 {
+    border-bottom:1px solid #444;
+    margin:2em 0 1em 0;
+  }
   .module h2:before {
      content: "module";
-     color: #888;
+     color: #444;
      font-family: monospace;
      font-size: 90%;
      padding-right:0.4em;
   }
 
+  .module h3 {
+    border-bottom:1px solid #dadada;
+    margin:2em 0 1em 0;
+  }
+
   .module h3:before {
      content: "function";
      color: #888;
@@ -227,7 +235,7 @@ DOCSTRING="${DOCSTRING:-# }"
 # use: doc::read_blocks v1 < script
 doc::read_blocks ()
 {
-  local block_name=MAIN func_name= key=
+  local block_name=MAIN func_name
   local in_opt=false in_env=false in_use=false in_pre=false indent=''
   __doc__apis=()
   __doc__mods=()
@@ -244,7 +252,7 @@ doc::read_blocks ()
   _reset_env () { in_env=false; }
   _reset_use () { in_use=false; }
 
-  while read line; do
+  while read -r line; do
     # some minor replacements required for markdown parser
     line="${line//</\<}"
     line="${line//>/\>}"
@@ -343,6 +351,7 @@ doc::read_blocks ()
 
   _reset_pre
 
+  declare -a sort_ret=()
   std::sort "${!__doc__mods[@]}"
 
   for x in "${sort_ret[@]}"; do
@@ -382,10 +391,16 @@ doc::output ()
   done
   for doc in "$@"; do
     local docname="${doc#./}"
-    for api in ${API//,/ }; do
-      echo "# $api API Reference" && echo
-      doc::read_blocks "$api" < "$doc"
-    done
+
+    if [[ "$API" ]]; then
+      for api in ${API//,/ }; do
+        echo "# $api API Reference" && echo
+        doc::read_blocks "$api" < "$doc"
+      done
+    else
+      echo "# API Reference" && echo
+      doc::read_blocks "" < "$doc"
+    fi
     echo -e "\n---\n"
   done
 }