程序文档工具rtfd、Wizard、DevDocs、Kookbook介绍

以下为你介绍的程序文档工具都可用在Linux系统上:rtfd(构建文档的命令工具)、Wizard(开源项目[API]文档管理工具)、DevDocs(API 文档浏览器)、Kookbook(cookbook 生成器)。

1、rtfd(构建文档的命令工具)

rtfd是一个基于sphinx来构建文档的命令工具,用来生成并阅读文档。

类似于 readthedocs.org 提供的服务,当然功能是比不上的,只是作为备用工具使用。

它源于我在readthedocs上遇到的致命问题以及一直想造这么个轮子的想法,在一个脚本的基础上,快速地加了其他代码,形成的一个命令行工具,所以它不是那么优雅,代码也不美观。

只是,当你不想用或不能用readthedocs时,可以用它构建你的文档。

特性:

使用简单,依靠命令行、API。

配置简单,rtfd配置依靠ini文件,构建文档时也支持直接写ini文件配置文档所需环境。

支持https(HTTP2、TLS1.3),支持自定义域名(包含HTTPS的支持)。

文档项目直接支持多语言(翻译)和多标签(版本),在页面右下角有按钮可以显示。

支持webhook触发、文档构建状态的徽章、文档单一版本等。

允许github公开仓库和私有仓库。

目前相对于readthedocs不足的特性是:

仅支持github。

不支持生成PDF、EPUB。

不支持添加翻译版本(目前翻译版本要求直接包含在文档中才行)。

不支持设置子项目、构建时环境变量等。

安装:

rtfd本身依赖Flask-PluginKit>=3.3.0、Click>=7.0、configparser模块,目前只支持Python2.7,您可以在virtualenv、或在全局环境中安装。

正式版本:

$ pip install -U rtfd

开发版本:

$ pip install -U git+https://github.com/staugur/rtfd.git@master

注解:

Flask-PluginKit在v3.0时重构,v3.3.1前不兼容旧版本,若有使用此模块请注意。

下载地址:https://gitee.com/staugur/rtfd

2、Wizard(开源项目[API]文档管理工具)

程序文档工具rtfd、Wizard、DevDocs、Kookbook介绍

Wizard 是基于Laravel开发框架开发的一款开源项目(API)文档管理工具。

目前支持三种类型的文档管理:

Markdown:也是Wizard最主要的文档类型,研发团队日常工作中交流所采用的最常用文档类型,在 Wizard 中,对 Editor.md 项目进行了功能扩展,增加了文档模板,Json 转表格,图片粘贴上传等功能。

Swagger:支持 OpenAPI 3.0 规范,嵌入了 Swagger 官方的编辑器,通过定制开发,使其融入到 Wizard 项目当中,支持文档模板,全屏编辑,文档自动同步功能。

Table:这种文档类型是类似于 Excel 电子表格,采用了 x-spreadsheet 项目,将该项目嵌入到了 Wizard 中,目前还不是很完善。

在Wizard中,正在编辑的文档会定时自动保存到本地的 Local Storage 中,避免错误关闭页面而造成编辑内容丢失。

目前主要包含以下功能:

Swagger,Markdown,Table 类型的文档管理

文档修改历史管理

文档修改差异对比

用户权限管理

项目分组管理

LDAP 统一身份认证

文档搜索,标签搜索

阅读模式

文档评论

消息通知

文档分享

统计功能

如果想快速体验一下Wizard的功能,有两种方式:

在线体验请访问 http://wizard.aicode.cc/,目前只提供部分功能的体验。

使用Docker来创建一个完整的Wizard服务

进入项目的根目录,执行 docker-compose up,就可以快速创建一个Wizard服务了,访问地址 http://localhost:8080。

起源:

为了鼓励大家在开发过程中写开发文档,最开始我们选择了 ShowDoc 项目来作为文档管理工具,当时团队规模也非常的小,大家都是直接用 Markdown 写一些简单的开发文档。后来随着团队的壮大,前后端分离,团队分工的细化,仅仅采用 Markdown 开始变得捉襟见肘,这时候,我们首先想到了使用开源界比较流行的 Swagger 来创建开发文档。但是 Swagger 文档多了,总得有个地方维护起来吧?

项目中的文档仅仅用Swagger也是不够的,它只适应于API文档的管理,还有很多其它文档,比如设计构想,流程图,架构文档,技术方案,数据库变更等各种文档需要一起维护起来。因此,我决定利用业余时间开发一款 集成 Markdown 和 Swagger 文档的管理工具,也就是 Wizard 项目了。

起初打算用 Go 语言来开发,但是没过几天发现使用 Golang 来做 Web 项目开发效率太低(快速开发效率,并非指性能),很多常用的功能都需要自己去实现,遂放弃使用 Golang,转而使用 PHP 的 Laravel 框架来开发。所以虽然项目创建的时间为 2017年7月27日,但是实际上真正开始的时间应该算是 2017年7月31日。

程序文档工具rtfd、Wizard、DevDocs、Kookbook介绍

起初Wizard项目的想法比较简单,只是用来将 Markdown 文档和 Swagger 文档放在一起,提供一个简单的管理界面就足够了,但是随着在团队中展开使用后,发现在企业中作为一款文档管理工具来说,只提供简单的文档管理功能是不够的,比如说权限控制,文档修改历史,文档搜索,文档分类等功能需求不断的被提出来,因此也促成了 Wizard 项目的功能越来越完善。

用户权限管理参考了 Gitlab 的权限管理方式,在用户的身份上只区分了管理员和普通用户,通过创建用户组来对用户的权限进行细致的管理,同时每个项目都支持单独的为用户赋予读写权限。

项目分组 在 Wizard 中,文档是以项目为单位进行组织的,刚开始的时候发现这样是OK的,后来项目越来越多,项目分组功能应运而生,以目录的形式来组织项目结构。

文档修改历史 每次对文档的修改,Wizard 都会记录一个快照,避免错误的修改了文档而造成损失,可以通过文档历史快速的恢复文档,对文档的修改,新增,删除等关键操作都会记录审计日志,以最近活动的形式展示出来。

文档差异对比 在团队协助中,经常会出现很多人修改同一份文档,为了避免冲突,文档修改后,其它人在提交旧的历史版本时,系统会提示用户文档内容发生了变更,用户可以通过文档比对功能找出文档中有哪些内容发生了修改。

阅读模式 当使用投影仪展示文档来过技术方案的时候,为了减少不必要的干扰,使用阅读模式,只展示文档内容部分,提供更好的展示体验。

文档搜索 通过搜索功能快速查找需要的文档,目前支持通过文档标题来搜素文档,后续会增加全文检索功能。

LDAP支持 很多公司都会使用 LDAP 来统一的管理公司员工的账号,员工的在公司内部的所有系统中都是用同一套帐号来登录各种系统比如 Jira,Wiki,Gitlab 等,Wizard 也提供了对 LDAP 的支持,只需要简单的几个配置,就可以快速的接入公司的统一帐号体系。

文档附件,文档分享,统计,文档排序,模板管理,文档评论。

关于代码:

项目采用了 Laravel 开发框架开发,目前框架的版本已经升级到最新的 5.8(最开始为5.4,一路升级过来)。为了提高开发效率,保持架构的简洁,在开发过程中,一直避免引入过多的外部组件,尽可能的利用 Laravel 提供的各种组件,比如 Authentication,Authorization,Events,Mail,Notifications 等,非常适合Laravel新手利用该项目来学习Laravel开发框架。

安装:

目前支持两种安装方式,如果你熟悉Docker,可以直接使用Docker容器的方式来运行该项目,这也是最简单的方式了。如果你没有使用Docker或者不知道什么是Docker,那么请直接参考手动安装部分。

通过 Docker 安装:

我们需要创建一个Dockerfile,在Dockerfile中添加环境配置,比如我采用了宿主机上安装的MySQL服务器,就有了下面的这段Dockerfile配置

FROM mylxsw/wizard:latest

# 数据库连接配置

# 这里可以根据需要添加其它的Env配置,可用选项参考项目的.env.example文件

ENV DB_CONNECTION=mysql

ENV DB_HOST=host.docker.internal

ENV DB_PORT=3306

ENV DB_DATABASE=wizard_2

ENV DB_USERNAME=wizard

ENV DB_PASSWORD=wizard

ENV WIZARD_NEED_ACTIVATE=false

# 文件上传存储目录

VOLUME /webroot/storage/app/public

RUN php artisan config:cache

执行构建

docker build -t my-wizard .

数据库初始化

docker run -it --rm --name my-wizard my-wizard php artisan migrate:install

docker run -it --rm --name my-wizard my-wizard php artisan migrate

运行

docker run -d --name my-wizard -p 8080:80  my-wizard

然后就可以通过 http://localhost:8080 访问 Wizard 了。

手动安装:

手动安装方式需要先安装配置好PHP环境,建议采用 PHP-FPM/Nginx 的方式来运行,具体配置参考环境依赖部分。

环境依赖:

以下组件的安装配置这里就不做详细展开,可以自行寻找安装方法。

PHP 7.2 + (需要启用 LDAP 扩展)

composer.phar

MySQL 5.6 +

Nginx

Git

下载代码:

推荐使用 git 来下载项目代码到服务器,我们假定将该项目放在服务器的 /data/webroot 目录

cd /data/webroot

git clone https://github.com/mylxsw/wizard.git

cd wizard

下载代码之后,使用 composer 安装项目依赖

composer install --prefer-dist --ignore-platform-reqs

composer 会在在项目目录中创建 vender 目录,其中包含了项目所依赖的所有第三方代码库。

你也可以直接到项目的 release 页面直接下载包含依赖的软件包。

配置:

复制一份配置文件

cp .env.example .env

修改 .env 中的配置信息,比如 MySQL 连接信息,文件存储目录,项目网址等。

接下来创建数据库,提前在MySQL中创建好项目的数据库,然后在项目目录执行下面的命令

php artisan migrate:install

php artisan migrate

接下来配置文件上传目录

php artisan storage:link

执行该命令后会在 public 目录下创建 storage/app/public 目录的符号链接。

在Nginx中配置项目的访问地址

server {

listen  80;

server_name wizard.example.com;

root /data/webroot/wizard/public;

index   index.php;

location / {

index index.php index.html index.htm;

try_files $uri $uri/ /index.php?$query_string;

}

location ~ .*\.(gif|jpg|png|bmp|swf|js|css)$ {

try_files $uri  =302;

}

location ~ .*\.php$ {

# php-fpm 监听地址,这里用了socket方式

fastcgi_pass  unix:/usr/local/php/var/run/php-cgi.sock;

fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

fastcgi_index index.php;

include fastcgi_params;

}

}

升级:

项目升级过程非常简单,只需要使用git拉取最新代码(git pull),然后执行下面的命令完成数据库迁移和依赖更新就OK了。

composer install --prefer-dist --ignore-platform-reqs

php artisan migrate

初始化:

安装完成后,Wizard项目就可以通过浏览器访问了,接下来需要访问注册页面创建初始用户

http://项目地址/register

在系统中注册的第一个用户为默认管理员角色。

开发计划:

开发框架升级Laravel 5.8

新版本更新

自动检测是否有新版本

无损更新版本

markdown编辑器增加json转换为markdown表格的功能

增加空间管理,类似于命名空间,不同部门在自己的空间中管理项目,文档等

项目功能

项目新增

项目配置

项目权限分配

项目删除

支持对项目进行分组,首页分组展示

关注项目优先展示

文档历史管理,文档恢复

操作日志记录

国际化支持

markdown编辑器增加图片上传支持

文档差异比较,文档历史版本差异比较

基于git的文档差异分析

文档多人编辑避免内容冲突覆盖

个人文档置顶(个人关注的文档,在首页增加展示区域,方便快速进入)

全局文档置顶(重要的常用文档,由管理员设置在首页特定区域展示,方便快速进入)

全文检索(文档,项目,评论,标签)

搜索功能优化,大部分用户都认为首页项目栏目顶部的搜索是用来搜索文档的,因此搜索不到

图片拖拽上传

复制自动上传

文档管理

文档编辑

新增文档

支持Swagger格式文档

支持markdown文档

支持表格类型的文档

文档删除

跨项目移动文档(移动时级联选择项目-目录)

文档点赞

文档菜单支持折叠

权限组,分组权限,管理员权限

项目按照分组分配读写权限

项目按照用户分配读写权限

文档模板管理

另存为模板

编辑器选择模板

模板列表

模板更新

模板删除

文档排序,支持在文档配置中国年修改文档排序

文档排序优化:以拖动的方式进行排序

文档快速在项目内部变更目录

项目排序

文档标签

文档评论

实现最基本的评论功能

实现评论回复,带层级的评论

实现评论支持@某人

评论点赞,类似Github issue评论后的emoji

实现评论支持@用户组下所有用户

消息通知功能

支持@某人后收到消息

支持消息列表

新的消息提示

消息全部已读,部分已读

新消息邮件提醒

消息接收配置(站内信,邮件,接收类型)

关注项目

关注项目,取消关注

已关注项目列表

关注项目变更后接收消息通知

支持导出文件

导出pdf

导出markdown、swagger

导出word

文档批量导出

实现API接口管理,自动根据接口数据判断接口是否需要修改,手动触发文档同步

对接postman,实现自动生成接口文档,接口测试

实现页面中之间互相引用

项目列表分页展示,增加按照项目标题搜索

文档增加标题搜索

文档保存后弹框提示选择:继续编辑还是创建新文档

文档分享

分享链接

分享后的文档页面,单页面模式

分享链接管理

分享链接有效期设置

分享链接删除

文档附件

附件上传

附件展示

附件删除

附件重传(历史附件)

文档,评论内引用附件

用户管理

用户姓名自动转拼音,用于引用该用户时快速提示和搜素

用户部门管理,用于不同部门使用不同空间

用户登录,注册,找回密码

基本信息修改

修改密码

管理员分配

用户分组管理

管理员管理分组

分组基础数据结构支持

用户管理页面,增加为用户分配用户组的功能,简化新员工入职时,权限分配的工作量

LDAP支持

统计信息查看

用户数量统计

文档数量统计

评论数量统计

用户活跃度统计

文档更新统计

下载地址:https://gitee.com/orionis/wizard

3、DevDocs(API 文档浏览器)

DevDocs 集合了多个开发者文档到一个简洁的 Web 界面中,提供即时搜索、离线浏览和移动设备支持,提供黑暗模式,键盘快捷键等等特性。同时提供各种编辑工具的插件。

DevDocs由两部分组成:一个用于生成文档和元数据的Ruby刮板,以及一个由小型Sinatra应用提供支持的JavaScript应用。

DevDocs需要Ruby 2.6.x,libcurl和ExecJS(在OS X和Windows中包含,在Linux上为Node.js包含)支持的JavaScript运行时。

使用方法:

git clone https://github.com/freeCodeCamp/devdocs.git && cd devdocs

gem install bundler

bundle install

bundle exec thor docs:download --default

bundle exec rackup

另外,DevDocs可以作为Docker容器启动:

首先,建立image:

git clone https://github.com/freeCodeCamp/devdocs.git && cd devdocs

docker build -t thibaut/devdocs .

最后,启动一个DevDocs容器(访问http://localhost:9292):

docker run --name devdocs -d -p 9292:9292 thibaut/devdocs

主要命令:

# Server

rackup              # Start the server (ctrl+c to stop)

rackup --help       # List server options

# Docs

thor docs:list      # List available documentations

thor docs:download  # Download one or more documentations

thor docs:manifest  # Create the manifest file used by the app

thor docs:generate  # Generate/scrape a documentation

thor docs:page      # Generate/scrape a documentation page

thor docs:package   # Package a documentation for use with docs:download

thor docs:clean     # Delete documentation packages

# Console

thor console        # Start a REPL

thor console:docs   # Start a REPL in the "Docs" module

Note: tests can be run quickly from within the console using the "test" command. Run "help test"

for usage instructions.

# Tests

thor test:all       # Run all tests

thor test:docs      # Run "Docs" tests

thor test:app       # Run "App" tests

# Assets

thor assets:compile # Compile assets (not required in development mode)

thor assets:clean   # Clean old assets

下载地址:https://gitee.com/mirrors/DevDocs

4、Kookbook(cookbook 生成器)

KookBook 是一个 cookbook 生成器。通过 KookBook 快速生成 cookbook 的层级目录。cookbook 可以通过 git 或者 nextcloud 等服务进行同步。

下载地址:https://gitee.com/mirrors/Kookbook

注明

以上就是程序文档工具rtfd、Wizard、DevDocs、Kookbook的介绍内容,这些程序文档工具都能使用在Linux操作系统中。

栏目相关文章