一直在使用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中，具体的排版细节待完善。。。
