Table of Contents

Sphinx是一个Python文档构建工具, 使用的标记语言是reStructuredText.

安装:

pip install Sphinx

当前版本: Sphinx 1.3.1

初始化文档项目

使用自带的 sphinx-quickstart 命令快速构建文档项目, 相当于傻瓜式的安装指引, 把一些主要的配置根据个人定义写入conf.py.

其中:

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]:

这一步是选择文档的结构, 默认no是把源文件直接放在根目录下, 生成文件放在根目录下的_build目录:

$  tree
.
├── Makefile
├── _build
├── _static
├── _templates
├── conf.py
└── index.rst

yes是把源文件和生成文件分两个目录存放:

$  tree
.
├── Makefile
├── build
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst
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 [_]:

TODO 这块应该有作用, 考虑下应用场景.

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]: zh_CN

国际化的配置, 这里我选择了zh_CN 简体中文

Sphinx的 Overview Tutorial, 国内有翻译的中文版 或者 中文版2

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 set this to another filename.
> Name of your master document (without suffix) [index]:

索引文件, 默认是 ./index

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]:

Sphinx提供了Unix/Linux下的Makefile和Windows下的make.bat, 用于封装了一些常用的命令


主题

官方提供了一些内置主题可以选择.

直接修改conf.pyhtml_theme的选项.

部分主题有一些可定制的选项, 参考文档即可.


文档:

  1. Overview Tutorial 官方 | 中文1 | 中文2
  2. 文档与笔记利器 reStructuredText 和 Sphinx
  3. A ReStructuredText Primer
  4. Quick reStructuredText
  5. Markdown和reStructuredText语法比较
  6. Markdown And RestructuredText