一直在使用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配置文件说明