自动生成bash脚本文档 bashdoc功能

断断续续的完善QA bash 函数库，已经整整一年多。没有想到这个小东西，最后会变成今天这样一个小型的框架。
它给我带来了很多的帮助，每次更新，都有一些新的领悟。
再不断的使用中，实实在在的体会到了有使用平台的愉悦。

最近很多人反映这个小框架的使用问题，没有文档，直接去看代码，很累，而且没有头绪。
之前不想写文档，是因为自己认为，一个好的帮助文档，应该是类似rdoc，javadoc之类的模式，可以跟随代码自动更新。而不是人为的去维护。我是不想把自己的时间，耗费在写帮助文档上，而且辛苦写出来的东西，还很少有人看。

不过随着代码，功能以及使用的增多，文档问题的重要性在不断的增大。
如果没有文档机制，以后的发展也会受限。

为了让新人更好的学习和了解这个小框架，决定周末加班下，解决自动生成帮助文档的问题。


从网上搜索了下，发现没有bashdoc之类的工具，之前有人写过一个，还半途而废了。
因为时间，精力有限，我也不可能再去开发一个。这个工作量是很大的。
思考了下，决定采用借用别的框架去试试。

doxygen是个不错的工具，支持的语言较多，但是好像是不支持bash的。而且配置比较繁琐。直接pass了。
想了想其他的语言，与bash比较类似的，就是python与ruby了。

最近在学习ruby，所以正好，就锻炼下自己的ruby吧。
我的设想是把bash脚本，转换到ruby脚本，最后调用rubydoc去完成文档生成。

bash的语法

xx（）
{
}

ruby的语法

def xx
end

使用awk，就可以很容易转换过去。而且bash与ruby的注释是一致的，注释基本上不需要修改了。
不过鉴于函数库的注释特性，我加入了一些额外的扩展。

最后很容易就实现了bash脚本生成文档。

:<<seven_doc_help
class:QA
user:yansheng.huangys
generate bash documention with rdoc ,  i like it very much
seven_doc ~/QA
seven_doc ~/QA/$USER
seven_doc ~/QA/script. ~/QA/$USER

if you write your bash script. like our style, reference to qahelp
then you would be able to generate doc by seven_doc
if you put your files in QA directory, you would be able to get help by man
seven_doc_help
=========================

========source code=========
seven_doc is a function
seven_doc ()
{
    rm -rf /tmp/QA_src_doc_$USER;
    mkdir /tmp/QA_src_doc_$USER;
    for f in `find "$@" -name "*.sh" -type f`;
    do
        for cat in QA cmd performance other;
        do
            grep "class:$cat" $f >&/dev/null && {
                echo "module `echo ${f##*/}|tr '[a-z]' '[A-Z]'`";
                echo "class `echo $cat|tr '[a-z'] '[A-Z]'`"
            };
            awk -F"\t" 'BEGIN{key="#"}{if($1~/:<<.*_help/) {print "=begin rdoc";key="*";} else if($1~/[^:]*_help$/) {print "=end";key="#";} else if($1~/^.*\(\)/) {print "def "$0
;key="#";} else if($1=="}") {print "end#def";} else {print key" "$0} }' $f | awk 'BEGIN{RS="end#def";ORS=RS;}{show=1;if("'$cat'"=="other") {if($0~/class:/) show=0} else {if($0~/
class:'$cat'/) {} else show=0};if(show==1) {print $0} }';
            echo;
            grep "class:$cat" $f >&/dev/null && {
                echo "end#class `echo $cat|tr '[a-z'] '[A-Z]'`";
                echo;
                echo "end#module `echo ${f##*/}|tr '[a-z]' '[A-Z]'`"
            };
        done >/tmp/QA_src_doc_$USER/doc_${f##*/}.rb;
    done;
    rdoc /tmp/QA_src_doc_$USER --op /tmp/QA_src_doc_$USER/doc -S
}


使用这个功能的前期，是你的脚本要按照如下的形式去编写


:<<qahelp_help
class:QA
#你的注释
qahelp_help
qahelp()
{

#你的代码内容

}


或者如下的形式


#你的注释
qahelp()
{

#你的代码内容

}





最后的文档，就和rdoc一摸一样了。