序言
Sphinx 是一个基于 Python 的文档生成项目。最早只是用来生成 Python 的项目文档，使用 reStructuredText 格式。但随着项目的逐渐完善，很多非 Python 的项目也采用 Sphinx 作为文档写作工具。
特点：
- 丰富的输出格式: 支持输出为 HTML（包括 Windows 帮助文档），LaTeX（可以打印PDF版本）, manual pages（man 文档）, 纯文本等若干种格式；
- 完备的交叉引用: 语义化的标签，并可以自动化链接函数、类、引文、术语等；
- 明晰的分层结构: 轻松定义文档树，并自动化链接同级/父级/下级文章；
- 美观的自动索引: 可自动生成美观的模块索引；
- 精确的语法高亮: 基于 Pygments 自动生成语法高亮；
- 开放的扩展: 支持代码块的自动测试，自动包含 Python 的模块自述文档
安装
可以通过源码编译安装或使用包管理器来安装Sphinx环境，在这里，我们通过PyPI使用pip命令安装Sphinx:
- 在Linux或MacOS上
$ pip install -U sphinx
- 在Windows上
C:\> pip install -U sphinx
安装完成后，在命令行输入sphinx-build --version可以看到Sphinx软件包的版本号
- 可以安装最新版本，测试最新的特性$ pip install -U --pre sphinx
创建项目
①. 新建项目
`cmd`命令行进入存放项目的根目录，使用命令`sphinx-quickstart`新建项目，根据提示分别输入项目信息和配置，操作流程如下图所示：
提示信息为：
- 是否分离源文件目录 source 和生成文件目录 build，默认否；
- 模板目录 templates 和静态文件目录 static 前缀，默认为_；
- 项目名称；
- 项目作者；
- 项目版本，默认为空；
- 项目语言，默认为 en；
- 文档扩展名，默认为 .rst；
- 首页文件名，默认为 index；
- 开启的扩展，均默认为否：
- 生成 Makefile，默认是；
- 生成 Windows 用命令行，默认是
项目新建后，查看生成的文件目录:
各文件或目录的功能为:
- Makefile：可以看作是一个包含指令的文件，在使用 make 命令时，可以使用这些指令来构建文档输出。
- build：生成的文件的输出目录。
- make.bat：Windows 用命令行。
- _static：静态文件目录，比如图片等。
- _templates：模板目录。
- conf.py：存放 Sphinx 的配置，包括在 sphinx-quickstart 时选中的那些值，可以自行定义其他的值。
- index.rst：文档项目起始文件。
②.执行命令make html
在项目根目录下执行命令make html，生成html资源文件：
此时查看项目目录:
可以看到在build/html文件夹下，生成了html资源文件，打开index.html，可以看到初始化的大致网页框架：
③.修改配置文件config.py，添加自己的内容
- 以上初始化项目之后，需要添加自己的内容和配置信息，输出自己的文档这里以输出mindspore的html格式介绍文档为例，由于主要内容为markdown格式文挡，需要安装recommonmark模块儿：pip install recommonmark 添加内容：
从Gitee仓库中下载markdown格式的说明文档,这里以api目录下的source_zh_cn为例
将source_zh_cn目录下载到本地，里面包含编写好的所有markdown文档，且已包含由config.py和index.rst配置文档，参考修改配置信息，本地目录结构如下图所示：
④.生成文档
- 首先修改由quickstart初始化生成的make.bat脚本文件,该文件内容为：
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command wa not found. Make sure you have Sphinx
echo.installed,then set the SPHINXBUILD environment viriable to point
echo.to the full path of the 'sphinx-build' executable.Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.if you don't have Sphinx installed,grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd
在这里将SOURCEDIR和BUILDDIR修改为:
set SOURCEDIR=source_zh_cn
set BUILDDIR=build_zh_cn
- 使用make
命令生成特定的文档格式，在这里我们生成html文件执行make html此时，生成了build_zh_cn目录，里面包含了html文档，打开build_zh_cn/html/indext.html，可以在浏览器中review生成的html页面。
总结
在整个过程中我们使用sphinx在windows环境下将多个markdown、reStructuredText说明文档进行链接，构建成为可读性更强的html文档，其中关键的是配置文件的修改和自定义内容格式。使用sphinx可以使得生成的文档更具有可读性和美化，因此推荐参考官方应用案例和配置信息。