程序文档工具prk、ssdb-docs、parm、犀鸟介绍

以下为你介绍的程序文档工具都可用在Linux系统上:prk(需求管理工具)、ssdb-docs(SSDB 文档项目)、parm(markdown 文档转换工具)、犀鸟(接口文档管理平台)。

1、prk(需求管理工具)

PeRKy 是个电脑软件,致力于软件需求管理和任何源代码管理(SCM[Source Control Manager]),类似一个存储层,基于一个简单的原则:每个需求一个文件。PeRKy 帮助开发者使用相同的工具保证文档和代码的同步,同时集成了分布式开发理念,因此可以在合并分支发展时限制遇到冲突的风险。

2、ssdb-docs(SSDB 文档项目)

这个项目是 SSDB 数据库的文档源码项目,文档采用 Markdown 格式编写,可以生成 HTML 网页。每个人都可以 fork,编辑,然后提交 pull request,给 SSDB 的文档做贡献。

3、parm(markdown 文档转换工具)

程序文档工具prk、ssdb-docs、parm、犀鸟介绍

注:上图为parm生成的一个效果图,它缺省使用了semantic-ui的css框架。

parm 是一款转换 markdown 文档为 html 的工具,它可以类似 sphinx 创建文档转換项目,可以将配置信息写在conf.py 中,支持目录页的生成,同时可以生成 disqus 的社会化评论。目前支持 bootstrap 和 semantic-ui  两种 css 框架。uliweb-doc 的文档就是使用 parm 生成。同时它还提供了将 rst 转为 markdown 语法的功能。

安装:

首先将par和parm安装:

pip install parm

然后写在:

/project/docs

初始化环境:

接下来,转到docs文件夹,如果是第一次运行,则应初始化parm项目环境,如下所示:

parm init

运行此命令时,它会询问您是否要初始化配置信息,如果您选择Y,则将输入交互式命令行,然后仅输入一些信息,以后可以在conf.py文件中进行更改。此命令将从parm模块复制一些静态文件和模板。

对于0.9版本,它还将复制一个演示页面,例如:index.md、introduction.md,因此您可以直接运行parm make并查看结果。

写作目录:

接下来,您可以开始转换文档。因为parm支持目录(TOC),所以您可以将主题内容写入index.md文件,对于0.9版本,它已经为您创建了index.md,因此您可以打开并编辑它。

内容就像:

## Introduction

{% toc max_depth=2 %}

file1.md

file2.md

...

{% endtoc %}

对于0.9版本,您不需要H1主题,因为项目信息已经写在conf.py中,您可以更改它们。

您应该将所有可以列出的文件放在toc标记中,并且您还可以设置max_depth argumant,这意味着每个markdown文件的标题级别,例如h1、h2。您也可以跳过max_depth,默认值为1。

您可以在index.md中放置多个toc部分,并为每个主题指定H2主题。

建立:

您可以运行:

parm make

开始转换,转换完成后,结果将输出为html默认值,您也可以使用-d参数更改它,就像:

parm make -d output_directory

并将结果输出到output_directory。

将reStructuredText转换为Markdown:

parm还支持将reStructuredText格式转换为Markdown格式,只需输入您的doc目录,然后执行以下命令:

parm rst2md <output_directory>

但您知道,reStructuredText格式比markdown丰富,因此我在par项目中为Markdown格式扩展了一些新样式。但是par仍然支持某些样式,因此您需要手动更改它们。

而且,如果要将reStructuredText转换为Markdown,则应首先安​​装docutils。

下载地址:https://gitee.com/limodou/parm

4、犀鸟(接口文档管理平台)

什么是犀鸟?

犀鸟是一个在线文档系统,致力于快速解决团队内部接口文档的编写和沉淀。

往往开发的时候的接口文档不是存在WORD里就是存在于我们的内部IM的聊天记录中,犀鸟的存在就是为了解决这些接口的维护。

力求用最简单的方式部署您的文档系统,拥有最方便的文档管理。

一些想法借鉴了iodocs。

犀鸟如何部署?

犀鸟采用bootstrap+angularjs+php开发。

获取源文件,部署到您支持php的webserver的可访问目录即可。

注明

以上就是程序文档工具prk、ssdb-docs、parm、犀鸟的介绍内容,这些程序文档工具都能使用在Linux操作系统中。

栏目相关文章