windows环境下配置sphinx输出html文档

转载地址：windows环境下配置sphinx输出html文档

作者：zhany

序言

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`新建项目，根据提示分别输入项目信息和配置，操作流程如下图所示：

提示信息为：

1. 是否分离源文件目录 source 和生成文件目录 build，默认否；
2. 模板目录 templates 和静态文件目录 static 前缀，默认为_；
3. 项目名称；
4. 项目作者；
5. 项目版本，默认为空；
6. 项目语言，默认为 en；
7. 文档扩展名，默认为 .rst；
8. 首页文件名，默认为 index；
9. 开启的扩展，均默认为否：
10. 生成 Makefile，默认是；
11. 生成 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配置文档，参考修改配置信息，本地目录结构如下图所示：

④.生成文档

1. 首先修改由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

1. 使用make <type>命令生成特定的文档格式，在这里我们生成html文件

   执行make html

   

   此时，生成了build_zh_cn目录，里面包含了html文档，打开build_zh_cn/html/indext.html，可以在浏览器中review生成的html页面。

总结

在整个过程中我们使用sphinx在windows环境下将多个markdown、reStructuredText说明文档进行链接，构建成为可读性更强的html文档，其中关键的是配置文件的修改和自定义内容格式。使用sphinx可以使得生成的文档更具有可读性和美化，因此推荐参考官方应用案例和配置信息。