python使用sphinx构建文档

一直在使用MarkDown来简单记录相关操作文档，尝试使用.rst(reStructuredText)文件来记录一下

• 安装

pip install sphinx

安装中会自动下载安装相关依赖，耗时会多点。

• 测试安装

1. 创建一个文件夹docs，进入该文件夹，在cmd执行命令，创建一个新的文档目录用来测试

sphinx-quickstart

2. 会在当前目录下创建相关的文件清单

.
├── build
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── index.rst
    ├── ystatic
    └── ytemplates

4 directories, 4 files

3. 文件介绍

• Makefile：编译过代码的开发人员应该非常熟悉这个文件，如果不熟悉，那么可以将它看作是一个包含指令的文件，在使用 make 命令时，可以使用这些指令来构建文档输出。
• build：这是触发特定输出后用来存放所生成的文件的目录。
• source：这是存放.rst文件的目录。
• conf.py：这是一个 Python 文件，用于存放 Sphinx 的配置值，包括在终端执行 sphinx-quickstart 时选中的那些值。
• index.rst：文档项目的 root 目录。如果将文档划分为其他文件，该目录会连接这些文件。
• ystatic:：静态资源文件
• ytemplates：模板文件

3. 执行下面命令，在build文件夹下转换成html文档

sphinx-build -b html ./source ./build

执行构建命令，将source目录下的rst资源文件，转换为html文件到build目录下

上面演示了简单的生成步骤

---

进一步了解

index.rst 文件
该文件是入口，新增的文件要构建，需要在该文件里面配置。在 index.rst 文件中的主标题之后，有一个内容清单，其中包括 toctree 声明。toctree 是将所有文档汇集到文档中的中心元素。如果有其他文件存在，但没有将它们列在此指令下，那么在构建的时候，这些文件不会随文档一起生成。

加入我们下载有一个新增的文件example.rst，想要进行构建，我们需要将它列在index.rst的文件清单 toctree 中，不需要后缀名。示例如下：

.. toctree::
   :maxdepth: 2
   :caption: Contents:
   
   example  # 与上面保留一行空行才可生效

example.rst文件放在source文件下，构建目录如下：

.
├── build
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── example.rst
    ├── index.rst
    ├── ystatic
    └── ytemplates

4 directories, 5 files

此时执行以下命令，重新编译

E:\docs>make html
Running Sphinx v1.7.5
making output directory...
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded.

The HTML pages are in build\html.

这是最简单的新增一个文件在index.rst中，具体的排版细节待完善。。。

TODO conf.py配置文件说明