什么是 Docat ?
Docat
是一个用于托管文档的平台,它支持简单、版本化和高级功能。能够与常见的文档生成工具(如MkDocs
和Sphinx
)无缝集成。无论是技术手册、API
文档还是用户指南,Docat
都能提供一个直观的查看和导航体验。
安装
在群晖上以 Docker 方式安装。因为镜像发布在 ghcr.io
,所以采用命令行方式安装
需要用
SSH
客户端登录到群晖后再执行
# 下载镜像
docker pull ghcr.io/docat-org/docat:latest
docker hub
上的 randombenj/docat
从 tags
看,很可能是官方的同步发布
docker cli 安装
如果你熟悉命令行,可能用 docker cli
更快捷
# 新建文件夹 docat 和 子目录
mkdir -p /volume1/docker/docat/doc
# 进入 docat 目录
cd /volume1/docker/docat
# 运行容器
docker run -d \
--restart unless-stopped \
--name docat \
-p 5066:80\
-v $(pwd)/:/var/docat/ \
ghcr.io/docat-org/docat:latest
也可以用 docker-compose
安装,将下面的内容保存为 docker-compose.yml
文件
version: "3"
services:
docat:
image: ghcr.io/docat-org/docat:latest
container_name: docat
restart: unless-stopped
ports:
- "5066:80"
volumes:
- ./:/var/docat/
然后执行下面的命令
# 新建文件夹 docat 和 子目录
mkdir -p /volume1/docker/docat/doc
# 进入 docat 目录
cd /volume1/docker/docat
# 将 docker-compose.yml 放入当前目录
# 一键启动
docker-compose up -d
运行
在浏览器中输入 http://群晖IP:5066
就能看到主界面,这是一个使用说明
因为没有静态 html
文档或使用 mkdocs
、sphinx
等生成的文档 ,老苏随便准备了几个文件
其中还要有一个 index.html
文件,用于串联几个文件
否则上传完成时会显示
而且进入项目后,会报错
压缩文件最好不要有目录,否则也会报错
点左下角的上传按钮
填写项目名称,文档的版本,选择文档压缩包,点 upload
上传
回到首页
老苏自己写的 index.html
实在是有点丑陋
但是不影响使用
像 doc
和 md
文件点击后会下载,所以看起来适合网页文件和 pdf
文件的管理
当然如果不写 index.html
也是可以的
直接在浏览器中输入文档的地址 http://192.168.0.197:5066/doc/融合通信%20api%20文档/v5.0/QTalk平台Restful服务接口文档.pdf
,不过这有点难为人了
所以
docat
还是最适合静态HTML
文档或使用mkdocs
、sphinx
等工具生成的文档的托管
除了在网页上直接上传之外,首选通过命令行应用程序 docatl
将文档推送到 docat
服务器
# tag the version VERSION of project PROJECT as latest
docatl tag --host http://localhost:8000 PROJECT VERSION latest
除此之外,还能用标准 UNIX
命令行工具 curl
实现一样的功能
# tag the version VERSION of project PROJECT as latest
curl -X PUT http://localhost:8000/api/PROJECT/VERSION/tags/latest
参考文档
GitHub - docat-org/docat: Host your docs. Simple. Versioned. Fancy.
地址:https://github.com/docat-org/docat
docat-org/docatl: docatl, the docat cli 🙀
地址:https://github.com/docat-org/docatl