Sphinx 文档简介
Sphinx 是一个结构化的文档工具,易于版本管理,文档格式统一,并且最终将文档发布。有关 Sphinx 文档撰写语法,以及 Sphinx 各种环境的安装与配置,请直接参见官方文档,如下:
http://www.sphinx-doc.org/en/master/contents.html
Sphinx 文档开发与测试
Sphinx 文档开发可以在任意环境进行,包括:MacOS,Linux,甚至 Windows(非原生,不推荐)。如果你使用的个人电脑是 Windows,那么建议开启一台 CentOS 7 的虚拟机,进行开发。可以生成html、htmlhelp/chm、qthelp、devhelp、latex、man 等格式的文档。
MacOS 开发指南
首先,你的 MAC 应该已经安装了 brew 工具,如果没有安装 brew 工具的,请参见如下指南,自行安装:
在你的 MacOS 上,安装 pip,关于 pip 应该如何安装,请自行请教 google。通过 pip 安装 sphinx,如下:
pip
install
sphinx
pip
install
sphinx-autobuild
|
克隆需要开发的项目,以私有仓库下的 uos-director 模板文档为例
git clone http:
//gitlab
.xxx.com
/docs/uos-director
.git
|
接下来就可以编译并浏览文档
sphinx-autobuild
source
/ _build/
#你可以自行指定监听地址和端口号
sphinx-autobuild
source
/ _build/ -H 0.0.0.0 -p 8080
|
Linux 开发指南
以 CentOS 7 为例
# 安装 pip
yum
install
python-pip -y
# 安装 sphinx
pip
install
sphinx
pip
install
sphinx-autobuild
|
克隆需要开发的项目,以 私有仓库uos-director 模板文档为例
git clone http:
//gitlab
.xxx.com
/docs/uos-director
.git
|
接下来就可以编译并浏览文档了
sphinx-autobuild
source
/ _build/
#你可以自行指定监听地址和端口号
sphinx-autobuild
source
/ _build/ -H 0.0.0.0 -p 8080
|
提示
- 还可以在 /usr/lib/python2.7/site-packages/sphinx_autobuild/__init__.py 文件中的get_parser.parser.add_argument(),修改ip 和port。
文档编辑器
在 MacOS 下,你可以使用任何你所熟悉的文档编辑器,进行文档撰写,如:sublime,emacs,vim 等
在 Linux 下,推荐使用 vim