用sphinx-doc优雅的写文档

Sphinx 是一个工具，它使得创建一个智能而美丽的文档变得简单。作者Georg Brandl，基于BSD许可证。

起初为写 Python 文档而诞生的 Sphinx，支持为各种语言生成软件开发文档。

它有着以下突出特性：

• 输出格式：HTML（包括Windows的HTML帮助文件）、LaTex（可以打印为PDF）、epub（流行的电子书格式）、Texinfo、manual pages（man手册）、plain Text（纯文本）
• 广泛的交叉引用：语义标记，函数、类等的自动连接等
• 分层架构：目录树的简单定义，有自动链接的父子兄弟节点等
• 自动索引
• 代码高亮
• 丰富的拓展

Sphinx 使用 reStructuredText 作为编写语言，也可以使用 Markdown + 拓展库的方式进行文档的编写。

1. 起步

1.1 安装

Sphinx 用Python编写，支持 Python 3.5+，可以使用 pip 进行安装。

命令行中执行以下指令安装

$ pip install -U sphinx # windows系统 cmd调出方式 （Win徽标键 + R）

$ pip3 install -U sphinx # Linux系统 

1.2 初体验

安装好 Sphinx 以后，你可以创建自己的第一个 Sphinx 项目了。为了简化启动过程，Sphinx 提供了一个 sphinx-quickstart 工具，用于产生文档源目录。

命令行中执行 sphinx-quickstart ，依照提示进行相应的选择，其他设置选择默认，后期再改动。

E:\working>sphinx-quickstart
Welcome to the Sphinx 1.8.0 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y # 源路径和输出路径分开

Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:

The project name will occur in several places in the built documentation.
> Project name: test_sphinx # 项目名称
> Author name(s): yqmcu     # 作者
> Project release []: 0.1   # 版本号

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]: zh_CN # 中文 语言列表看上面的网址

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]: # 源文件后缀名 因为用的是 reStructureText 所以默认选择 .rst

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]: # 主页面 index.rst 编译后为 index.html
Indicate which of the following Sphinx extensions should be enabled:
> autodoc: automatically insert docstrings from modules (y/n) [n]:
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y # 此处选择了 todo 命令拓展，其他的包 根据需求选配 | yes or no
> coverage: checks for documentation coverage (y/n) [n]:
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]:
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]: # 创建Makefile 编译用的配置
> Create Windows command file? (y/n) [y]: # 创建编译用的脚本可执行程序

Creating file .\source\conf.py.
Creating file .\source\index.rst.
Creating file .\Makefile.
Creating file .\make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file .\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

至此，一个文档项目就建立好了，文件结构如下：

如图，source 和 build 路径是分开的。

由此可见，sphinx-quickstart 执行后，设置了一系列有用的配置值并在 source 文件夹中创建了一个 conf.py 配置文件。

注意：官网上提示要选择 autodoc 扩展，不知道是做什么用的，暂时不选。

1.3 定义文档结构

之后，我们打开 source 文件夹，默认的有一个名为 index.rst 的主文件。它是我们文档的欢迎页，也就是首页。

内容如下：

.. test_sphinx documentation master file, created by
   sphinx-quickstart on Tue Oct  :: .
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to test_sphinx's documentation!
=======================================

.. toctree::
   :maxdepth:
   :caption: Contents:

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

其中，toctree（table of contents） 代表文档的目录页，toctree 是sphinx 指令，主要功能是将多个文件链接到一个单一页面中组成层级结构。（说人话：生成文档目录）。

toctree 命令初始化是空的，像下面这样：

.. toctree::
    :maxdepth: 

maxdepth 代表目录显示的最大层级。

我们在此模拟 sphinx-doc 的官网的文档示例，在 source 文件夹中，新建一个叫做 usage 的文件夹，再在 usage 文件夹中新建两个文件，分别命名为 installation.rst、quickstart.rst。

上面的 toctree 指令内容改成如下这样。

.. toctree::
    :maxdepth: 

    usage/installation
    usage/quickstart

如此，toctree 指令使用 文档名称（省略后缀名）作为目录的中的链接地址。使用 /（正斜杠）作为路径分隔符。总之，目录的结构就是按照文件夹中文件的编排来进行布置。需要在目录中链接什么文件，就将该文件之于source路径的相对路径填写在toctree之后就可以。而maxdepth是代表目录中链接的文件的文章层级，比如上述代码中，链接installation.rst文件中的一级标题和二级标题的内容，在目录页面，也就是当前的index.rst页面中显示。

需要注意的是：

• 形如 usage/installation 作为 toctree指令的 内容（content）需要跟在可选项（options）的后面，空一行，才能发挥作用
• maxdepth 作为 toctree指令的 可选项（options），:maxdepth: 和 2 之间需要空一格，才能生效