python sphinx_python使用sphinx构建文档

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

安装

pip install sphinx

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

测试安装

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

sphinx-quickstart

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

.

├── build

├── make.bat

├── Makefile

└── source

├── conf.py

├── index.rst

├── ystatic

└── ytemplates

4 directories, 4 files

文件介绍

Makefile：编译过代码的开发人员应该非常熟悉这个文件，如果不熟悉，那么可以将它看作是一个包含指令的文件，在使用 make 命令时，可以使用这些指令来构建文档输出。

build：这是触发特定输出后用来存放所生成的文件的目录。

source：这是存放.rst文件的目录。

conf.py：这是一个 Python 文件，用于存放 Sphinx 的配置值，包括在终端执行 sphinx-quickstart 时选中的那些值。

index.rst：文档项目的 root 目录。如果将文档划分为其他文件，该目录会连接这些文件。

ystatic:：静态资源文件

ytemplates：模板文件

执行下面命令，在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配置文件说明