Sphinx使用说明

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 工具的，请参见如下指南，自行安装：

https://brew.sh/

 在你的 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

提示

1. 还可以在 /usr/lib/python2.7/site-packages/sphinx_autobuild/__init__.py 文件中的get_parser.parser.add_argument(),修改ip 和port。
   

 

文档编辑器

在 MacOS 下，你可以使用任何你所熟悉的文档编辑器，进行文档撰写，如：sublime，emacs，vim 等

在 Linux 下，推荐使用 vim