手把手教你Sphinx（一）

手把手教你Sphinx（一）

1. 什么是Sphinx？

所谓Sphinx，其实就是一个能将reStructuredText（类似于Markdown）语法的文本文件转换为HTML、PDF、epub等格式的强大工具。

要知道，Python的官方文档就是利用这款工具书写而成的，并且被广泛用于各式各样的说明文档。

2. Sphinx的安装

由于Sphinx运行于python之上，因此可以在命令行使用pip进行安装：

$ pip install sphinx

3. 创建项目

为了验证安装的成功与否，可以运行下面的命令

sphinx-quickstart 文档名

为了演示方便，下面除了Project name、Author name(s)、Project version这必填的3项外，直接跳过其他项（啥都不填，直接按回车）。

Welcome to the Sphinx 1.6.3 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: sphinx-test

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]:

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 [_]:

The project name will occur in several places in the built documentation.
> Project name: SphinxTest
> Author name(s): hymanlu

Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
just set both to the same value.
> Project version []: 1.0.0
> Project release [1.0.0]:

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

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]:

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]:

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/n) [n]:

Please indicate if you want to use one of the following Sphinx extensions:
> autodoc: automatically insert docstrings from modules (y/n) [n]:
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]:
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]:
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:

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]:

Creating file sphinx-test\conf.py.
Creating file sphinx-test\index.rst.
Creating file sphinx-test\Makefile.
Creating file sphinx-test\make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file sphinx-test\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

4. 文档转换

在项目创建完之后，我们就可以将原始的reStructuredText文档转换成HTML网页代码：

cd sphinx-test/
make html

对于windows平台的用户可以执行下面的命令：

./make.bat html

转换生成的HTML文件保存在_build/html/index.html 目录下

同样地，我们可以通过make epub或者./make.bat epub来转换得到epub文件