Skip to Content.
Sympa Menu

sm-commit - [SM-Commit] GIT changes to master bashdoc by Jaka Kranjc (7c0463a790fd9eed5671f83bb6bf958fe70a191d)

sm-commit AT lists.ibiblio.org

Subject: Source Mage code commit list

List archive

Chronological Thread  
  • From: Jaka Kranjc <scm AT sourcemage.org>
  • To: sm-commit AT lists.ibiblio.org
  • Subject: [SM-Commit] GIT changes to master bashdoc by Jaka Kranjc (7c0463a790fd9eed5671f83bb6bf958fe70a191d)
  • Date: Wed, 2 Apr 2008 05:25:03 -0500

GIT changes to master bashdoc by Jaka Kranjc <lynxlynxlynx AT sourcemage.org>:

ChangeLog | 18 +
bashdoc.sh | 576
++++++++++++++++++++++++++++++++++++--------------
generate-smgl-docs.sh | 9
3 files changed, 444 insertions(+), 159 deletions(-)

New commits:
commit 7c0463a790fd9eed5671f83bb6bf958fe70a191d
Author: Jaka Kranjc <lynxlynxlynx AT sourcemage.org>
Commit: Jaka Kranjc <lynxlynxlynx AT sourcemage.org>

added missing scripts to g-s-d

commit 750417bc5ec178bb00aadcaa5cf606d057d6e774
Author: Jaka Kranjc <lynxlynxlynx AT sourcemage.org>
Commit: Jaka Kranjc <lynxlynxlynx AT sourcemage.org>

bashdoc: chmod +x

commit d42085ce6d9c47eeb6475b4f644af3c743fd3558
Author: Jaka Kranjc <lynxlynxlynx AT sourcemage.org>
Commit: Jaka Kranjc <lynxlynxlynx AT sourcemage.org>

* generate-smgl-docs.sh: fixed long standing HTMl typo
* started documenting changes the standard smgl way

commit 4504ee52587b7098c5aee4e3984b4ada510f2882
Author: Jaka Kranjc <lynxlynxlynx AT sourcemage.org>
Commit: Jaka Kranjc <lynxlynxlynx AT sourcemage.org>

plenty of old changes from Arvid Norlander, see ChangeLog

diff --git a/ChangeLog b/ChangeLog
index 00dc3d8..33969da 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,9 +1,23 @@
-Sun Aug 13 13:08:12 PDT 2006
+2008-04-02 Jaka Kranjc <lynxlynxlynx AT sourcemage.org>
+ * generate-smgl-docs.sh: fixed long standing HTMl typo
+ added missing scripts
+ * started documenting changes the standard smgl way
+ * bashdoc: chmod +x
+
+Sun Oct 14 17:24:19 CEST 2007; Arvid Norlander
+ The last two days I have changed so much on bashdoc that I lost count of it
+ Some nice things:
+ Cleaned up code.
+ XHTML and CSS.
+ Made bashdoc able to document variables.
+ Fix many bugs.
+
+Sun Aug 13 13:08:12 PDT 2006; Paul Mahon
Fix bug which caused either extra garbage around function links in src or
skipped some interlinks.
Release bashdoc-0.1.8

-Sun Jan 22 16:22:45 EST 2006
+Sun Jan 22 16:22:45 EST 2006; Paul Mahon
ChangeLog: Started
src2html: changed sed to fix the weird invalid range end erors
Changes suggested by Jaka Kranjc
diff --git a/bashdoc.sh b/bashdoc.sh
index 9b8ef06..821f9b3 100755
--- a/bashdoc.sh
+++ b/bashdoc.sh
@@ -1,17 +1,15 @@
-#!/bin/bash
-
-VERSION="0.1.6"
-HEADER="<!-- Generated by bashdoc version $VERSION, on $(date). -->"
-
+#!/usr/bin/env bash
+# -*- coding: utf-8 -*-
#--------------------------
## @Synopsis Reads specialy formated shell scripts and creates docs
## @Copyright Copyright 2003, Paul Mahon
+## @Copyright Copyright 2007, Arvid Norlander
## @License GPL v2
## Parses comments between lines of '#---'
## Lines to be parsed start with ##. All tags start with @.
## Lines without a tag are considered simple description of the section.
## If the line following the comment block doesn't start with 'function'
-## the it's assumed that the comment is for the whole file. Only the
first
+## the it's assumed that the comment is for the whole file. Only the
first
## non-function comment block will be used, the other will be ignored.
## <p>
## Multiple identical tags are allowed, the contents are appended and
separated
@@ -21,18 +19,85 @@ HEADER="<!-- Generated by bashdoc version $VERSION, on
$(date). -->"
## in any bashdoc comment. It will be transformed into a link to that
function.
## Note, this will only work for functions that are defined in the same
script.
## <p><pre>
-## Usage: [-p project] [-o directory] [-e tag] [--] script [ script ...]
-## '-p project' Name of the project
-## '-o directory' Specifies the directory you want the
-## resulting html to go into
-## '-e tag' Only output if the block has this tag
-## '-q' Quiet things down
-## '--' No more arguments, only scripts
-## 'script' The script you want documented
+## Usage: [OPTIONS] [--] script [ script ...]
+## -p, --project project Name of the project
+## -o, --output directory Specifies the directory you want the
resulting html to go into
+## -c, --nocss Do not write default CSS file.
+## -e, --exclusive tag Only output if the block has this tag
+## -q, --quiet Quiet the output
+## -h, --help Display this help and exit
+## -V, --version Output version information and exit
+## -- No more arguments, only scripts
+## script The script you want documented
##</pre>
##
#--------------------------

+# Make env sane
+unset LC_CTYPE LC_NUMERIC LC_TIME LC_COLLATE LC_MONETARY
+unset LC_MESSAGES LC_PAPER LC_NAME LC_ADDRESS
+unset LC_TELEPHONE LC_MEASUREMENT LC_IDENTIFICATION
+export LC_ALL=C
+export LANG=C
+
+# Check bash version. We need at least 3.2.x
+# Lets not use anything like =~ here because
+# that may not work on old bash versions.
+if [[ "$(awk -F. '{print $1 $2}' <<< $BASH_VERSION)" -lt 32 ]]; then
+ echo "Sorry your bash version is too old!"
+ echo "You need at least version 3.2 of bash"
+ echo "Please install a newer version:"
+ echo " * Either use your distro's packages"
+ echo " * Or see http://www.gnu.org/software/bash/";
+ exit 2
+fi
+
+# To make set -x more usable
+export PS4='(${BASH_SOURCE}:${LINENO}): ${FUNCNAME[0]} : '
+
+VERSION="0.1.8"
+HEADERS="<!-- Generated by bashdoc version $VERSION, on $(date +'%Y-%m-%d').
-->
+<link rel=\"stylesheet\" href=\"style.css\" type=\"text/css\" />
+<meta http-equiv=\"Content-Type\" content=\"text/html; charset=UTF-8\" />"
+
+GOOD=$'\e[32;01m'
+WARN=$'\e[33;01m'
+BAD=$'\e[31;01m'
+NORMAL=$'\e[0m'
+
+#--------------------------
+## Output error message
+## @param Message
+## @Stderr Formated message
+#--------------------------
+print_error () {
+ echo -e " ${BAD}*${NORMAL} $*" >&2
+}
+#--------------------------
+## Output warning message
+## @param Message
+## @Stderr Formated message
+#--------------------------
+print_warn () {
+ echo -e " ${WARN}*${NORMAL} $*" >&2
+}
+#--------------------------
+## Output info message
+## @param Message
+## @Stderr Formated message
+#--------------------------
+print_info () {
+ echo -e " ${GOOD}*${NORMAL} $*" >&2
+}
+#--------------------------
+## Output debug message
+## @param Message
+## @Stderr Formated message
+#--------------------------
+print_debug () {
+ echo -e " $*" >&2
+}
+
#--------------------------
## @Arguments -r: recursive, -o [directory]: output html
## Parses arguments for this script
@@ -43,53 +108,102 @@ function args()
local retVal=0
QUIET=0
while true ; do
- case $1 in
- -p) PROJECT="$2"
- let retVal+=2
- shift 2 ;;
- -o) OUT_DIR=$2
- let retVal+=2
- shift 2 ;;
- --help|-h) usage
- exit 0 ;;
- --exclusive|-e)
+ case $1 in
+ -p|--project)
+ PROJECT="$2"
+ (( retVal+=2 ))
+ shift 2
+ ;;
+ -o|--output)
+ OUT_DIR="$2"
+ (( retVal+=2 ))
+ shift 2
+ ;;
+ -c|--nocss)
+ NOCSS="1"
+ (( retVal+=2 ))
+ shift 1
+ ;;
+ -h|--help)
+ usage
+ exit 0
+ ;;
+ -V|--version)
+ version
+ exit 0
+ ;;
+ -e|--exclusive)
EXCLUSIVE="${2%%=*}"
EXCLUSIVE_VAL="${2#*=}"
- let retVal+=2
- shift 2 ;;
+ (( retVal+=2 ))
+ shift 2
+ ;;
-q|--quiet)
- let QUIET+=1
- let retVal+=1
- shift 1 ;;
- --) let retVal++
- return $retVal ;;
- -*) usage
- exit 0 ;;
- *) [ -e $1 ] && return $retVal
+ (( QUIET+=1 ))
+ (( retVal+=1 ))
+ shift 1
+ ;;
+ --)
+ (( retVal++ ))
+ return $retVal
+ ;;
+ -*)
+ usage
+ exit 0
+ ;;
+ *)
+ [[ -e $1 ]] && return $retVal
echo "$1 doesn't exist."
usage
- exit 1 ;;
+ exit 1
+ ;;
esac
done
}

#-------------------------
+## Version for this script
+## @Stdout Version information
+#-------------------------
+function version()
+{
+ echo "bashdoc $VERSION - Generate HTML documentation from bash
scripts"
+ echo ''
+ echo 'Copyright (C) 2003 Paul Mahon'
+ echo 'Copyright (C) 2007 Arvid Norlander'
+ echo 'This is free software; see the source for copying conditions.
There is NO'
+ echo 'warranty; not even for MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.'
+ echo ''
+ echo 'Written by Paul Mahon and modified by Arvid Norlander'
+}
+
+#-------------------------
## Usage for this script
## @Stdout Usage information
#-------------------------
function usage()
{
cat <<- EOF
-Usage: $(basename $0) [-p project] [-o directory] [--] script [ script ...]
- '-p project' Name of the project
- '-o directory' Specifies the directory you want the
- resulting html to go into
- '-e tag' Only output if the block has this tag
- '-q' Quiet the output
- '--' No more arguments, only scripts
- 'script' The script you want documented
-
- Example: bash2doc.sh -p smgl -o docs/
/home/user/p4/sgl/devel/sorcery/var/lib/sorcery/modules/lib{misc,codex}
bash2doc.sh
+bashdoc generates HTML documentation from bash scripts.
+
+Usage: $(basename $0) [OPTIONS] [--] script [script ...]
+
+Options:
+ -p, --project project Name of the project
+ -o, --output directory Specifies the directory you want the resulting
html to go into
+ -c, --nocss Do not write default CSS file.
+ -e, --exclusive tag Only output if the block has this tag
+ -q, --quiet Quiet the output
+ -h, --help Display this help and exit
+ -V, --version Output version information and exit
+ -- No more arguments, only scripts
+ script The script you want documented
+
+Examples:
+ bashdoc.sh -p bashdoc -o docs/ bashdoc.sh Generate
documentation for this program.
+ bashdoc.sh -p appname -o docs/ -e Type=API someapp.sh Generate
documentation for someapp.sh,
+ exclude items that
do not include the tag
+ @Type API
EOF
}

@@ -99,7 +213,7 @@ EOF
## <br><pre>#---</pre></br>
## Alone on a line, and continues until the next
## <br><pre>#---</pre></br>
-## All comment lines inside should have ## at the start or they
+## All comment lines inside should have ## at the start or they
## will be ignored.
##
## @return 0 Possibly more blocks
@@ -107,33 +221,35 @@ EOF
## @return 2 Expected end of file, no more blocks
## @Stdin Reads a chunk
## @Stdout Block with starting '##' removed
-## @Globals paramDesc, retDesc, desc, block, split
+## @Globals paramDesc, retDesc, desc, block, split,
out_comment_block
#--------------------------
function get_comment_block()
{
local inComment commentBlock lastLine=""
commentBlock=""
while read LINE ; do
- let srcLine++
+ (( srcLine++ ))
if [[ ${LINE:0:4} == '#---' ]] ; then
if [[ $inComment ]] ; then
- echo "$commentBlock"
+ out_comment_block="$commentBlock"
+ # I'm not sure why this is needed but it
fixes incorrect line number
+ (( srcLine++ ))
return 0
else
inComment=yes
fi
elif [[ ${LINE:0:2} != '##' ]] && [[ $inComment ]] ; then
- [[ $QUIET -lt 1 ]] && echo "Line $srcLine of
$FILE isn't a doc comment! Ignoring." >&2
+ [[ $QUIET -lt 1 ]] && print_warn "Line
$srcLine of $FILE isn't a doc comment! Ignoring."
+ [[ $QUIET -lt 1 ]] && print_warn "Line in
question is: $LINE"
elif [[ $inComment ]] ; then
commentBlock="$commentBlock"$'\n'${LINE####}
fi
done
-
#If we make it out here, we hit the end of the file
if [[ $commentBlock ]] ; then
#If there is a comment block started, then it never ended
- [[ $QUIET -lt 2 ]] && echo "Unfinished comment block:"
- [[ $QUIET -lt 2 ]] && echo "$commentBlock"
+ [[ $QUIET -lt 2 ]] && print_error "Unfinished comment block:"
+ [[ $QUIET -lt 2 ]] && print_error "$commentBlock"
return 1
else
return 2
@@ -146,13 +262,13 @@ function get_comment_block()
## function name. Mostly uses <@function parse_block> and
## <@function output_parsed_block> to do the read work.
## @Stdin Reads line after comment block
-## @Globals paramDesc, retDesc, desc, block, split
+## @Globals paramDesc, retDesc, desc, block, split,
out_comment_block
#-----------------------
function parse_comments()
{

#We use a lot of $( echo ... ) in here to trim the blanks
-
+
local funcLine funcName
paramDesc=()
retDesc=()
@@ -160,14 +276,21 @@ function parse_comments()
local skipRead
local outBlock=""
local lastOutBlock=""
+ srcLine=0
+ # 1 = function
+ # 2 = variable
+ itemtype=0
while true ; do
paramNames=()
paramDesc=()
split=()
retDesc=()
desc=""
- block=$( get_comment_block )
- [ $? -gt 0 ] && break
+ itemtype=0
+ unset out_comment_block
+ get_comment_block
+ [[ $? -gt 0 ]] && break
+ block="$out_comment_block"

if [[ $skipRead ]] ; then
skipRead=""
@@ -175,103 +298,143 @@ function parse_comments()
funcLine=""
funcName=""
read funcLine
- fi
- if [[ ${funcLine%%[[:blank:]]*} == function ]] ; then
+ fi
+ # Is it a (global) variable?
+ # Check before function to catch arrays.
+ if [[ ${funcLine} =~ ^(declare -r
+)?([a-zA-Z_][a-zA-Z0-9_]*)=.+$ ]]; then
+ varName="${BASH_REMATCH[@]: -1}"
+ itemtype=2
+ # Is it a function?
+ elif [[ ${funcLine%%[[:blank:]]*} == function ]] || [[
${funcLine} =~ ^[^\ ]+\ *\(\)\ *\{?$ ]]; then
funcName=$( echo ${funcLine#function} )
funcName=$( echo ${funcName%%()*} )
+ itemtype=1
fi
- if [[ $funcName ]] || [[ $FIRST_BLOCK ]] ; then

+ if [[ $funcName ]] || [[ $varName ]] || [[ $FIRST_BLOCK ]] ;
then
# Only bother with this block if it is a function
block or
# the first script block
-
+
#This fills in paramDesc[*], tag_*, retDesc
parse_block
lastOutBlock="$outBlock"
outBlock=$(output_parsed_block)
- for i in ${!tag_*} ; do
- unset $i
- done
-
- if [[ $FIRST_BLOCK ]] && [[ ! $funcName ]] ; then
+
+ if [[ $FIRST_BLOCK ]] && [[ ! $funcName ]] && [[ !
$varName ]]; then
FIRST_BLOCK=""
fi
-
+
if [[ $EXCLUSIVE ]] ; then
- local i="tag_${EXCLUSIVE}"
- if [[ ${!i} != $EXCLUSIVE_VAL ]] ; then
- echo "$funcName block ignored, no
$EXCLUSIVE=$EXCLUSIVE_VAL tag." >&2
- for i in ${!tag_*} ; do
- unset $i
- done
- continue
+ # If this is first block, include it anyway.
+ if [[ $funcName ]] || [[ $varName ]]; then
+ local i="tag_${EXCLUSIVE}"
+ if [[ ${!i} != $EXCLUSIVE_VAL ]] ;
then
+ if [[ $itemtype = 2 ]]; then
+ funcName="$varName"
+ fi
+ print_debug "$funcName block
ignored, no $EXCLUSIVE=$EXCLUSIVE_VAL tag."
+ # Code duplication but hard
to avoid
+ for i in ${!tag_*} ; do
+ unset $i
+ done
+ continue
+ fi
fi
fi
-
- FUNC_LIST="$FUNC_LIST $funcName"
+
+ for i in ${!tag_*} ; do
+ unset $i
+ done
+
+ if [[ $funcName ]]; then
+ FUNC_LIST="$FUNC_LIST $funcName"
+ elif [[ $varName ]]; then
+ VAR_LIST="$VAR_LIST $varName"
+ fi
+ unset funcName varName
echo "$outBlock"
-
+
else
- [[ $QUIET -lt 2 ]] && echo "Ignoring non-first
non-function comment block" >&2
- [[ $QUIET -lt 1 ]] && echo "$block" >&2
+ [[ $QUIET -lt 2 ]] && print_warn "Ignoring non-first
non-function/variable comment block"
+ [[ $QUIET -lt 1 ]] && print_warn "$block"
fi
done
}

#---------------------
+## Create HTML from the non-special tags
+## @param var or func (is this for a variable or function)
+## @Stdout HTMLized tags
+#---------------------
+function output_parsed_tags() {
+ local i
+ for i in ${!tag_*} ; do
+ # Convert _ in tags to space. Looks better.
+ echo " <h3 class=\"othertag ${1}othertag
${i/tag_/tag-}\">$(sed 's/_/ /g' <<< "${i#tag_}")</h3>"
+ # This may be fun, allow special formatting by tag.
+ echo " <p class=\"othertag ${1}othertag ${i/tag_/tag-}\">"
+ echo " ${!i}"
+ echo " </p>"
+ unset $i
+ done
+}
+
+#---------------------
## Outputs the parsed information in a nice pretty format.
## @Stdout formated documentation
## @Globals paramDesc, retDesc, desc, block, split
-#---------------------
+#---------------------
function output_parsed_block()
{
- echo -e "<hr>"
- if [[ $funcName ]] ; then
+ echo "<hr />"
+ if [[ $itemtype -eq 1 ]] && [[ $funcName ]]; then
echo "<!-- Block for $funcName -->"
- echo "<dl>"
- echo " <dt><a name='$funcName'><h2>function
<strong>$funcName</strong>()</h2></a></dt>"
- echo " <dd><ul>"
- for(( i=0; i<"${#paramDesc[@]}"; i++ )) ; do
- echo " <li>\$$[i+1]: ${paramDesc[i]}</li>"
- done
- echo " </ul></dd>"
+ echo " <h2 id=\"$funcName\" class=\"function\">function
<strong>$funcName</strong>()</h2>"
+ echo " <h3>Parameters:</h3>"
+ echo " <ul class=\"paramerters\">"
+ if [[ ${#paramDesc[*]} -gt 0 ]] ; then
+ for(( i=0; i<"${#paramDesc[@]}"; i++ )) ; do
+ echo " <li
class=\"paramerters\">\$$[i+1]: ${paramDesc[i]}</li>"
+ done
+ else
+ echo "<li>None</li>"
+ fi
+ echo " </ul>"
if [[ ${#retDesc[*]} -gt 0 ]] ; then
- echo " <dt><h3>Returns:</h3></dt>"
+ echo " <h3>Returns:</h3>"
+ echo " <ul class=\"returns\">"
for(( i=0; i<"${#retDesc[@]}"; i++ )) ; do
- echo " <li>${retDesc[i]}</li>"
+ echo " <li
class=\"returns\">${retDesc[i]}</li>"
done
+ echo " </ul>"
fi
-
- for i in ${!tag_*} ; do
- echo " <dt><h3>${i#tag_}</h3></dt>"
- echo " <dd>${!i}</dd>"
- eval "unset $i"
- done
- [[ $desc ]] && echo "
<dt><h3>Description</h3></dt><dd>$desc</dd>"
- echo "</dl>"
+
+ output_parsed_tags func
+ [[ $desc ]] && echo "<h3>Description</h3><p
class=\"description funcdescription\">$desc</p>"
+ elif [[ $itemtype -eq 2 ]]; then
+ echo "<!-- Block for $varName -->"
+ echo " <h2 id=\"$varName\" class=\"variable\">variable
<strong>$varName</strong></h2>"
+ output_parsed_tags var
+ [[ $desc ]] && echo "<h3>Description</h3><p
class=\"description vardescription\">$desc</p>"
else
echo '<!-- Header for whole script -->'
- echo "<dl>"
- echo " <dt><h1><strong>$FILE</strong></h1></dt>"
- echo " <dd>$desc</dd>"
+ echo "<h1>$FILE</h1>"
+ echo " <p class=\"filedescription\">$desc</p>"
echo "$desc" >> $SCRIPT_DESC

for i in ${!tag_*} ; do
- echo " <dt><h3>${i#tag_}</h3></dt>"
- echo " <dd>${!i}</dd>"
+ echo " <h3 class=\"fileothertag
${i/tag_/tag-}\">${i#tag_}</h3>"
+ echo " <p class=\"fileothertag
${i/tag_/tag-}\">${!i}</p>"
unset $i
done
- echo "</dl>"
fi

}

#---------------
## Does the real work of the parsing. Tags start with @. Special
-## tags are @return and @param. Doc lines without a tag are
+## tags are @return and @param. Doc lines without a tag are
## considered description.
## @Globals paramDesc, retDesc, desc, block, split
-## @Test many line
-## @Test test tag
#---------------
function parse_block()
{
@@ -284,28 +447,32 @@ function parse_block()
if [[ ${LINE:0:1} == '@' ]] ; then
split_tag split $LINE
case ${split} in
- @param)
#paramNames[${#paramNames[*]}]=${split[1]}
+ @param)
+
#paramNames[${#paramNames[*]}]=${split[1]}
paramDesc=( "${paramDesc[@]}"
"${split[1]}" )
;;
- @return)
+ @return)
retDesc=( "${retDesc[@]}"
"${split[1]}" )
;;
- @*) tag=${split[0]#@}
+ @*)
+ tag=${split[0]#@}
local i="tag_${tag}"
- if [[ ${!i} ]] ; then
- eval
"tag_${tag}=\"\${tag_${tag}}"$'\n'"${split[1]}\""
+ if [[ ${!i} ]] ; then
+ local varname="tag_${tag}"
+ eval
"tag_${tag}=\"\${!varname}"$'\n'"\${split[1]}\""
else
- eval
"tag_${tag}=\"${split[1]}\""
+ eval
"tag_${tag}=\"\${split[1]}\""
fi
;;
- *) echo "We shouldn't get here... it was
a tag, but not a tag?" >&2
+ *)
+ print_error "We shouldn't get here...
it was a tag, but not a tag?"
;;
esac
else
desc="$desc"$'\n'"$LINE"
fi
done
- IFS="$backIFS"
+ IFS="$backIFS"
}

#----------------
@@ -321,7 +488,7 @@ function split_tag()
local tag=$( echo ${1} ) ; shift
# local key=$( echo ${1} ) ; shift
local value=$( echo $* )
- eval "$out=( \"$tag\" \"${value}\" )"
+ eval "$out=( \"\$tag\" \"\${value}\" )"
}

#--------------------
@@ -332,50 +499,134 @@ function split_tag()
function script_header()
{
cat <<- EOF > $OUT_FILE
- <html>
- $HEADER
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml"; lang="en" xml:lang="en">
<head>
+ $HEADERS
<title>$1 - $PROJECT</title>
</head>
<body>
- <p align=right>
- <a href="script_list.html">Script Index</a>
- </p>
+ <p class="right">
+ <a href="script_list.html">Script Index</a>
+ </p>
EOF
}

# Initialise project variables
OUT_DIR=$( dirname $0 )
+NOCSS=0
args "$@"
shift $?
[[ $OUT_DIR ]] || OUT_DIR="."

+# Create output directory in case it doesn't exist
+mkdir -p "$OUT_DIR" || {
+ print_error "Failed to create output directory."
+ exit 1
+}
+
+if [[ $NOCSS = 0 ]]; then
+ print_info "Writing CSS"
+ # Copy stylesheet to output directory.
+ cat <<- EOF > "${OUT_DIR}/style.css"
+ /* Based on Trac CSS */
+ body {
+ background: #fff;
+ color: #000;
+ margin: 10px;
+ padding: 0;
+ }
+ body, th, td {
+ font: normal 13px verdana,arial,'Bitstream Vera
Sans',helvetica,sans-serif;
+ }
+ h1, h2, h3, h4 {
+ font-family: arial,verdana,'Bitstream Vera
Sans',helvetica,sans-serif;
+ font-weight: bold;
+ letter-spacing: -0.018em;
+ }
+ h1 { font-size: 19px; margin: .15em 1em 0 0 }
+ h2 { font-size: 16px; font-weight: normal; }
+ h3 { font-size: 14px }
+ hr { border: none; border-top: 1px solid #ccb; margin: 2em 0 }
+ address { font-style: normal }
+ img { border: none }
+ tt { white-space: pre }
+ :link, :visited {
+ text-decoration: none;
+ color: #b00;
+ border-bottom: 1px dotted #bbb;
+ }
+ :link:hover, :visited:hover {
+ background-color: #eee;
+ color: #555;
+ }
+ h1 :link, h1 :visited ,h2 :link, h2 :visited, h3 :link, h3 :visited,
+ h4 :link, h4 :visited, h5 :link, h5 :visited, h6 :link, h6 :visited {
+ color: inherit;
+ }
+ /* Partly own stuff: */
+ .nav body {
+ margin: 0;
+ padding: 0;
+ background: inherit;
+ color: inherit;
+ }
+ .nav ul { font-size: 11px; list-style: none; margin: 0; padding: 0;
text-align: left }
+ .nav li {
+ display: block;
+ padding: 0;
+ margin: 0;
+ white-space: nowrap;
+ }
+ /* Own stuff */
+ .nav-header {
+ font-weight: bold;
+ }
+ .right { text-align: right }
+ .tag-Deprecated { color: #e00; }
+ EOF
+else
+ print_warn "Not writing a stylesheet. You will need to add your own
by hand afterwards."
+fi

-while [ $# -gt 0 ] ; do
+while [[ $# -gt 0 ]] ; do

- echo "Parsing $FILE" >&2
#Initialise vars for this src
FILE=$1
+ [[ ! -f $FILE ]] || [[ ! -r $FILE ]] && {
+ print_error "$FILE is not a file or is not readable,
skipping."
+ shift
+ continue
+ }
+ print_info "Parsing $FILE"
shift
OUT_FILE=${FILE#/}
#Remove leading /
OUT_FILE="$OUT_DIR/${OUT_FILE//\//.}.html"
FUNC_FILE="${OUT_FILE%.html}.funcs"
+ VAR_FILE="${OUT_FILE%.html}.vars"
SCRIPT_DESC="${OUT_FILE%.html}.desc"
+ # Store real name (reuse in script list)
+ REAL_NAME_FILE="${OUT_FILE%.html}.name"
+ echo -n "${FILE#/}" > "$REAL_NAME_FILE"
+
FUNC_LIST=""
+ VAR_LIST=""

#Start this src's html file
- script_header "$1"
+ script_header "$FILE"

# Parse and write out function list
{
- parse_comments < $FILE
+ parse_comments < $FILE
echo "$FUNC_LIST" > $FUNC_FILE
- } | sed -e 's!<@[[:blank:]]*function \([^,>]*\)[[:blank:]]*>!<a
href="#\1">\1</a>!g' \
- -e 's!<@[[:blank:]]*function
\([^,>]*\),[[:blank:]]*\([^>]*\)[[:blank:]]*>!<a href="\1#\2">\1</a>!g' >>
$OUT_FILE
+ echo "$VAR_LIST" > $VAR_FILE
+ # Convert references like <@function file,functioname> into links
+ } | sed -e 's!<@[[:blank:]]*function \([^,>]*\)[[:blank:]]*>!<a
href="#\1">\1</a>!g' \
+ -e 's!<@[[:blank:]]*function
\([^,>]*\),[[:blank:]]*\([^>]*\)[[:blank:]]*>!<a href="\1#\2">\1</a>!g' >>
$OUT_FILE
#Close off the html for this src
cat <<- EOF >> $OUT_FILE
</body>
- </html>
+ </html>
EOF

done #Go on to next src
@@ -383,76 +634,93 @@ done #Go on to next src
#Now for tying the scripts all together
pushd $OUT_DIR >/dev/null

+print_info "Writing function list"
# Start page that will have all the function calls
cat <<- EOF > function_list.html
- <html>
- $HEADER
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml"; lang="en" xml:lang="en">
<head>
+ $HEADERS
<title>Functions of $PROJECT</title>
</head>
- <body>
+ <body class="nav">
+ <ul class="nav">
EOF

+echo "<li class=\"nav nav-header\">Functions</li>" >> function_list.html
# Merge function lists of all sources, sort by function name
for i in *.funcs ; do
for f in $( cat $i ) ; do
- echo "$f <a href=\"${i%.funcs}.html#$f\"
target=main>$f</a><br>"
+ echo "$f <li class=\"nav nav-function\"><a
href=\"${i%.funcs}.html#$f\" target=\"main\">$f</a></li>"
+ done
+done | sort | cut -d' ' -f2- >> function_list.html
+
+echo "<li class=\"nav nav-header\">Variables</li>" >> function_list.html
+for i in *.vars ; do
+ for v in $( cat $i ) ; do
+ echo "$v <li class=\"nav nav-variable\"><a
href=\"${i%.vars}.html#$v\" target=\"main\">$v</a></li>"
done
done | sort | cut -d' ' -f2- >> function_list.html

# Close off the html for the global function list
cat <<- EOF >> function_list.html
-</body>
+ </ul>
+ </body>
</html>
EOF

+print_info "Writing script list"
# Start the list of scripts
TITLE="Scripts"
[[ $PROJECT ]] && TITLE="$PROJECT Script Documentation"
cat <<- EOF > script_list.html
- <html>
- $HEADER
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml"; lang="en" xml:lang="en">
<head>
+ $HEADERS
<title>Scripts of $PROJECT</title>
</head>
<body>
- <h1>$TITLE</h1>
- <hr>
- <dl>
+ <h1>$TITLE</h1>
+ <hr />
+ <dl>
EOF

# List all the sources + descriptions, sort by script dir/name
-for i in *.funcs ; do
- name=${i%.funcs}
- echo "${name}"
-done | sort | while read LINE ; do
- echo "<dt><a href=\"${LINE}.html\">$LINE</a></dt>"
+for i in *.name ; do
+ name=${i%.name}
+ echo "${name} $(cat "$i")"
+done | sort | while read LINE realname; do
+ echo "<dt><a href=\"${LINE}.html\">$realname</a></dt>"
echo "<dd>"
- cat ${LINE}.desc 2>/dev/null || { [[ $QUIET -lt 2 ]] && echo "$LINE
has no description." >&2; }
+ cat ${LINE}.desc 2>/dev/null || { [[ $QUIET -lt 2 ]] && print_warn
"$LINE has no description."; }
echo "</dd>"
done >> script_list.html

# Close off the html for the global script list
cat <<- EOF >> script_list.html
- </dl>
+ </dl>
</body>
- </html>
+</html>
EOF

+print_info "Writing index file"
# Create the index file for the whole shbang
cat <<- EOF > index.html
- <html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd";>
+<html xmlns="http://www.w3.org/1999/xhtml"; lang="en" xml:lang="en">
<head>
- $HEADER
+ $HEADERS
<title>BashDoc - $PROJECT</title>
</head>
- <frameset COLS="20%,*">
- <frame src=function_list.html name=function_list>
- <frame src=script_list.html name=main>
+ <frameset cols="25%,*">
+ <frame src="function_list.html" name="function_list" />
+ <frame src="script_list.html" name="main" />
</frameset>
- </html>
+</html>
EOF

-# Remove the temporary .desc files, leave the .func files, someone may want
them later.
+# Remove the temporary .desc and .name files, leave the .func and .vars
files, someone may want them later.
rm *.desc
+rm *.name
popd >/dev/null
diff --git a/generate-smgl-docs.sh b/generate-smgl-docs.sh
old mode 100644
new mode 100755
index 70c5a7e..a0933d8
--- a/generate-smgl-docs.sh
+++ b/generate-smgl-docs.sh
@@ -11,10 +11,13 @@ FLOW=$BIN/flow.sh
SRC2HTML=$BIN/src2html.sh
PROJECT=SourceMageDocs

-
QUIET=${QUIET:--q -q}

-SCRIPTS="/var/lib/sorcery/modules/lib*
/var/lib/sorcery/modules/url_handlers/url_* /usr/sbin/cast /usr/sbin/sorcery
/usr/sbin/dispel /usr/sbin/gaze /usr/sbin/invoke /usr/sbin/scribbler
/usr/sbin/scribe /usr/sbin/summon /usr/sbin/vcast /usr/sbin/xsorcery"
+SCRIPTS="/var/lib/sorcery/modules/lib*
/var/lib/sorcery/modules/url_handlers/url_* \
+/var/lib/sorcery/modules/build_api/{api2,api1,common}
/var/lib/sorcery/modules/dl_handlers/dl_* \
+/usr/sbin/cast /usr/sbin/sorcery /usr/sbin/dispel /usr/sbin/gaze
/usr/sbin/invoke \
+/usr/sbin/cleanse /usr/sbin/confmeld /usr/sbin/alter /usr/sbin/delve
/usr/sbin/cabal \
+/usr/sbin/scribbler /usr/sbin/scribe /usr/sbin/summon /usr/sbin/vcast
/usr/sbin/xsorcery"
#exclude non-sorcery files, like backups~ or numbered versions
for FILE in $SCRIPTS
do
@@ -45,7 +48,7 @@ else
echo "The bashdoc tools are not installed, please cast bashdoc!"
fi

-${SRC2HTMl} --funcs $DOCDIR $SCRIPTS
+${SRC2HTML} --funcs $DOCDIR $SCRIPTS
if which dot >/dev/null 2>&1 ; then
${FLOW} --funcs $DOCDIR --exclude debug --exclude message \
--exclude query $SCRIPTS



  • [SM-Commit] GIT changes to master bashdoc by Jaka Kranjc (7c0463a790fd9eed5671f83bb6bf958fe70a191d), Jaka Kranjc, 04/02/2008

Archive powered by MHonArc 2.6.24.

Top of Page