断断续续的完善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一摸一样了。