Sphinx-doc编写文档

sphinx-doc是一种基于python的文档编写工具。python的官方帮助文档就是使用它编写的。sphinx-doc是reStructuredText，即使用带有简单语法的文本文件来编写文件，然后通过编译，可以生成html,epub,man,pdf等多种格式。

---

plain text VS. WYSIWYG

使用文本文件编写，再使用工具编译生成文档(tex,docbook,sphinx都可算这个阵营)，和所见即所得(微软的word,mac的page等)的编写方式相比有啥优缺点呢？

优点

• 开源跨平台，文本文件任何平台都可以打开，编译工具也可以在任何平台运行
• 能产生多种格式的文档，甚至可以简单地转为博客的markdown语法
• 能够生成html等格式，便于发布交流，如发到网上，大家都可以看到了
• 由于是文本，方便版本控制，也可以加注释，多人编写、合并文档更方便
• WYSIWYG的编写，如果加载图片多了，会导致越来越卡，而plain text只是include一个文件，编译后才会加载
• 基于网页的技术可以方便地调整文档格式，编写时可以更加注重内容
• 插件较多，如特别适合各种代码的插入、语法高亮等

缺点

• 没有WYSIWYG直观，只能编译后才能生成实际的文档，才能看到效果
• 国内用word写文档的人比较多

sphinx-doc的安装

sphinx依赖于python，所以要先安装python环境，并安装pip工具，安装方法见 [ python入门系列(2) – python环境搭建 ]

使用pip安装sphinx:

pip install sphinx

---

创建工程

使用sphinx-quickstart创建工程

安装完sphinx后，会在python的Scripts目录下(C:\Python27\Scripts)产生sphinx-quickstart。确保该目录已经添加到系统环境变量中，然后启动cmd。进入要创建sphinx文档的目录，如 D:\Learn\python， 然后执行下面过程，创建编写Python学习文档的工程，其实设置工程名、作者名、版本号，其他默认就行。我们这里把source和build两个目录分开，因为这样比较方便。

D:\Learn\python>sphinx-quickstart
Welcome to the Sphinx 1.3.1 quickstart utility.

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

Enter the root path for documentation.
> Root path for the documentation [.]:

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

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: Python
> Author name(s): Vincent Yu

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-languag