⽤sphinx-doc优雅的写⽂档
Sphinx 是⼀个⼯具，它使得创建⼀个智能⽽美丽的⽂档变得简单。作者Georg Brandl，基于BSD许可证。
起初为写 Python ⽂档⽽诞⽣的 Sphinx，⽀持为各种语⾔⽣成软件开发⽂档。
它有着以下突出特性：
输出格式：HTML（包括Windows的HTML帮助⽂件）、LaTex（可以打印为PDF）、epub（流⾏的电⼦书格式）、Texinfo、manual pages（man⼿册）、plain Text（纯⽂本）
⼴泛的交叉引⽤：语义标记，函数、类等的⾃动连接等
分层架构：⽬录树的简单定义，有⾃动链接的⽗⼦兄弟节点等
⾃动索引
代码⾼亮
丰富的拓展
Sphinx 使⽤作为编写语⾔，也可以使⽤ 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.
Plea enter values for the following ttings (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 u a directory "_build" within the root path, or you parate
"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 veral places in the built documentation.
> Project name: test_sphinx # 项⽬名称
indicate是什么意思
> Author name(s): yqmcu # 作者
> Project relea []: 0.1 # 版本号
If the documents are to be written in a language other than English,
you can lect a language here by its language code. Sphinx will then
cefirotranslate text that it generates into that language.
For a list of supported codes, e
/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 t 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 inrt 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
2013考研政治真题
> 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 browr by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content bad 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 `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. U the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
clothes可数吗
⾄此，⼀个⽂档项⽬就建⽴好了，⽂件结构如下：
如图，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 2316:06:152018.
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: 2
:caption: Contents:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`arch`
上海新东方英语培训其中，toctree（table of contents）代表⽂档的⽬录页，toctree 是sphinx 指令，主要功能是将多个⽂件链接到⼀个单⼀页⾯中组成层级结构。（说⼈话：⽣成⽂档⽬录）。
toctree命令初始化是空的，像下⾯这样：
.. toctree::
:maxdepth: 2
maxdepth 代表⽬录显⽰的最⼤层级。
我们在此模拟的官⽹的⽂档⽰例，在source ⽂件夹中，新建⼀个叫做usage的⽂件夹，再在usage ⽂件夹中新建两个⽂件，分别命名为installation.rst、quickstart.rst。
上⾯的 toctree 指令内容改成如下这样。
.. toctree::
:maxdepth: 2
usage/installation
usage/quickstart
英国大学排行榜小学一年级英语上册视频如此，toctree 指令使⽤⽂档名称（省略后缀名）作为⽬录的中的链接地址。使⽤ /（正斜杠）作为路径分隔符。总之，⽬录的结构就是按照⽂件夹中⽂件的编排来进⾏布置。需要在⽬录中链接什么⽂件，就将该⽂件之于source路径的相对路径填写在toctree之后就可以。⽽maxdepth是代表⽬录中链接的⽂件的⽂章层级，⽐如上述代码中，链接installation.rst⽂件中的⼀级标题和⼆级标题的内容，在⽬录页⾯，也就是当前的index.rst页⾯中显⽰。
需要注意的是：
形如 usage/installation 作为 toctree指令的内容（content）需要跟在可选项（options）的后⾯，空⼀⾏，才能发挥作⽤
maxdepth 作为 toctree指令的可选项（options），:maxdepth: 和 2 之间需要空⼀格，才能⽣效
