论文部分内容阅读
摘要：软件开发者一项重要的工作就是文档的编写，但这是一项枯燥泛味的工作，大多数软件开发者只专心于代码的编写，后期的文档不善于编写，造成团队开发的一些困扰。如果在程序代码开发阶段中就能实现文档的编写，无疑是一举两得的事情。本文探讨了如何使用国产优秀的开源软件ShowDoc自动通过程序代码注释进行文档的自动生成，为前后端开发者提供了编写文档的捷径，共同发展提高。
关键词：ShowDoc，程序文档
作为软件开发者，文档的编写整理是一项十分重要的工作。开发人员都很希望别人能写技术文档，而自己却很不希望要写文档。因为写文档需要花大量的时间去处理格式排版，想着新建的word文档放在哪个目录等各种非技术细节。word文档零零散散地放在团队不同人那里，需要文档的人要花费大量时间进行沟通，通过QQ、邮箱接收对方的文档。这种沟通方式当然可以，只是效率不高。
ShowDoc就是一个非常适合软件开发团队的在线文档分享工具，它可以加快团队之间沟通的效率，并且有着精巧的设计，可以通过程序编写过程中十分便利地顺手写的程序注释，自动形成规范的文档，贴近于开发人员的使用习惯，是非常优秀的开源工具。
下面本人就自己在软件开发工作中的ShowDoc使用经验，及使用心得分享给大家：
一、自行构建API文档本地服务器。
本人使用CentOS 7.8 64位系统，在本地利用虚拟化平台布署，因为ShowDoc使用Docker技术，Docker需要container-selinux包，需要手工安装，在https：//pkgs.org/download下载后，拖入linux后手工安装：
cd /opt
yum localinstall -y container-selinux-2.119.2-1.911c772.el7_8.noarch.rpm
下面下载ShowDoc，由其自动安装Docker容器：
wget https：//www.showdoc.com.cn/script/showdoc
chmod +x showdoc
./showdoc
由于要下载安装Docker相关环境，经过漫长时间后，ShowDoc即布署完成。在内网即可直接访问，假定ShowDoc安装的IP是10.0.0.100：
http：//10.0.0.100/web/#/
设置Docker自动启动ShowDoc：
systemctl enable docker
docker update --restart=always showdoc
二、使用ShowDoc手工、自動编写、添加文档
使用ShowDoc默认密码登录后，在页面上新建文档，即可进入某个项目的详细文档编辑页面，类似于Markdown的编辑页面，手工编辑一些说明、全局错误码、修改记录等全局性的API文档，可以非常方便地便于后端、前端的开发人员翻阅。
手工编写不是开发人员的常规选择，更直接、便利的方式是通过代码中常规注释来自动生成文档，贴近于后端开发人员的开发习惯，是值得推荐的方式：
wget https：//www.showdoc.cc/script/showdoc_api.sh
chmod a+x showdoc_api.sh
wget https：//www.showdoc.cc/script/api_demo.test
api_demo.test是一个示例性的文档，从中可以拿到完整的注释参考。编辑showdoc_api.sh，根据自己项目的具体配置，修改api key和url，即可使showdoc_api与项目专属文档形成关联。在程序编写时，可以在代码起始处、或每个关键函数起始处添加如下注释：
‘’’
/**
* showdoc
* @catalog 测试文档/用户相关
* @title 用户注册
* @description 用户注册的接口
* @method post
* @url https：//www.showdoc.com.cn/home/user/login
* @param username 必选 string 用户名
* @param password 必选 string 密码
* @param name 可选 string 用户昵称
* @return {"error_code"：0，"data"：{"uid"："1"，"username"："12154545"，"name"："吴系挂
"，"groupid"：2，"reg_time"："1436864169"，"last_login_time"："0"}}
* @return_param groupid int 用户组id
* @return_param name string 用户昵称
* @remark 这里是备注信息
* @number 99
*/
‘’’
需要说明的是本人使用python编程，因而在前后都增加了’’’。我们也可以看到，注释同样适用于java、javascript的代码注释。其中@catalog用于生成文档的树型结构，@number用于文档生成的顺序，其它注释都是开发人员十分熟悉的，在此不做赘述。
我们可以与git配合，做成日志的自动更新，定时启动showdoc_api.sh，即可自动生成规整的API文档，这极大便利于程序文档的编写，团队开发人员只要形成了约定，在每段关键的API调用函数前，使用一些必要的注释，即可生成规范的文档，供后端和前端开发人员共享使用，大大提高了开发效率，方便了团队开发的规范形成。
本人对于ShowDoc的使用已有一段时间，真切地感到它为软件开发工作提供了极大的帮助，也希望更多的软件开发人员所知晓，不管是python、java、javascript、c、c++、go的开发人员，都能利这款优良的国产开源软件从中获益非浅。
关键词：ShowDoc，程序文档
作为软件开发者，文档的编写整理是一项十分重要的工作。开发人员都很希望别人能写技术文档，而自己却很不希望要写文档。因为写文档需要花大量的时间去处理格式排版，想着新建的word文档放在哪个目录等各种非技术细节。word文档零零散散地放在团队不同人那里，需要文档的人要花费大量时间进行沟通，通过QQ、邮箱接收对方的文档。这种沟通方式当然可以，只是效率不高。
ShowDoc就是一个非常适合软件开发团队的在线文档分享工具，它可以加快团队之间沟通的效率，并且有着精巧的设计，可以通过程序编写过程中十分便利地顺手写的程序注释，自动形成规范的文档，贴近于开发人员的使用习惯，是非常优秀的开源工具。
下面本人就自己在软件开发工作中的ShowDoc使用经验，及使用心得分享给大家：
一、自行构建API文档本地服务器。
本人使用CentOS 7.8 64位系统，在本地利用虚拟化平台布署，因为ShowDoc使用Docker技术，Docker需要container-selinux包，需要手工安装，在https：//pkgs.org/download下载后，拖入linux后手工安装：
cd /opt
yum localinstall -y container-selinux-2.119.2-1.911c772.el7_8.noarch.rpm
下面下载ShowDoc，由其自动安装Docker容器：
wget https：//www.showdoc.com.cn/script/showdoc
chmod +x showdoc
./showdoc
由于要下载安装Docker相关环境，经过漫长时间后，ShowDoc即布署完成。在内网即可直接访问，假定ShowDoc安装的IP是10.0.0.100：
http：//10.0.0.100/web/#/
设置Docker自动启动ShowDoc：
systemctl enable docker
docker update --restart=always showdoc
二、使用ShowDoc手工、自動编写、添加文档
使用ShowDoc默认密码登录后，在页面上新建文档，即可进入某个项目的详细文档编辑页面，类似于Markdown的编辑页面，手工编辑一些说明、全局错误码、修改记录等全局性的API文档，可以非常方便地便于后端、前端的开发人员翻阅。
手工编写不是开发人员的常规选择，更直接、便利的方式是通过代码中常规注释来自动生成文档，贴近于后端开发人员的开发习惯，是值得推荐的方式：
wget https：//www.showdoc.cc/script/showdoc_api.sh
chmod a+x showdoc_api.sh
wget https：//www.showdoc.cc/script/api_demo.test
api_demo.test是一个示例性的文档，从中可以拿到完整的注释参考。编辑showdoc_api.sh，根据自己项目的具体配置，修改api key和url，即可使showdoc_api与项目专属文档形成关联。在程序编写时，可以在代码起始处、或每个关键函数起始处添加如下注释：
‘’’
/**
* showdoc
* @catalog 测试文档/用户相关
* @title 用户注册
* @description 用户注册的接口
* @method post
* @url https：//www.showdoc.com.cn/home/user/login
* @param username 必选 string 用户名
* @param password 必选 string 密码
* @param name 可选 string 用户昵称
* @return {"error_code"：0，"data"：{"uid"："1"，"username"："12154545"，"name"："吴系挂
"，"groupid"：2，"reg_time"："1436864169"，"last_login_time"："0"}}
* @return_param groupid int 用户组id
* @return_param name string 用户昵称
* @remark 这里是备注信息
* @number 99
*/
‘’’
需要说明的是本人使用python编程，因而在前后都增加了’’’。我们也可以看到，注释同样适用于java、javascript的代码注释。其中@catalog用于生成文档的树型结构，@number用于文档生成的顺序，其它注释都是开发人员十分熟悉的，在此不做赘述。
我们可以与git配合，做成日志的自动更新，定时启动showdoc_api.sh，即可自动生成规整的API文档，这极大便利于程序文档的编写，团队开发人员只要形成了约定，在每段关键的API调用函数前，使用一些必要的注释，即可生成规范的文档，供后端和前端开发人员共享使用，大大提高了开发效率，方便了团队开发的规范形成。
本人对于ShowDoc的使用已有一段时间，真切地感到它为软件开发工作提供了极大的帮助，也希望更多的软件开发人员所知晓，不管是python、java、javascript、c、c++、go的开发人员，都能利这款优良的国产开源软件从中获益非浅。