写文档¶
小白听到同学的抱怨后，自己尝试着从用户的眼光再看了看自己写的代码。小白发现，同学的抱怨也挺有道理的。随着通讯录功能的增加，软件也越来越难用了。 “恩！的确需要一个软件文档。”
回顾需求¶
小白的程序基本成型了，但是缺少一个“说明书”，所以，小白要为自己的程序写个“说明书”——文档
编辑文档的工具，不能是慢的要死的word,又不能从头写网页……
于是乎，行者给出两个利器：ReST、sphinx
ReST¶
结构化文本reStructuredText？上网搜一搜，搜到一篇“简明教程”
http://blog.csdn.net/jiyucn/article/details/2157189
摘录一段:
我们已经知道了，所见即所得偏重的是外观设计，而不是代码。看起来不错，不过这种模式也有一些缺点。 比如我想强调某事，我可能就会有点犹豫……我是应该用粗体呢？还是应该用红色的字体？还有什么其它更好的方法么？
小白：所想即所得？很好玩阿？但是太抽象了，能不能说的简单一些呢？
好吧，做一个比较更加形象：
RST代码:
title
=========================
content
::
code
相同效果的HTML代码
<html>
<body>
<h1>title</h1>
<p>content</p>
<code>code</code>
</body>
</html
明显是Rst简便多了吧。
那就用他了！
安装方法:
easy_install docutils
如果没有安装easy_install，就先搜索安装吧
小白先写一段
title
=============
content
保存为text.txt
再在命令行运行
rst2html.py text.txt > text.html
哈哈，编译成功。可以打开text.html看看效果。
结构大全¶
标题
=======================
章
------------------------
节
~~~~~~~~~~~~~~~~~~~~~
- 列表1
- 列表2
计数列表：
1. one
2. two
说明列表：
标题
这是说明
标题2
这还是说明
:: 代码块/文本块（依靠缩进分划）
这是代码：：
>> 1+1
2
>> import os
代码结束
*斜体* **黑体** ..`超级连接`:http://www.woodpecker.org.cn
于是小白一个个写了api文档
可是白板界面也太难看了！
行者曰：用“斯芬克斯”吧
sphinx大怪兽¶
听说这个玩意儿可以生成很漂亮的文档？试试看,
搜索“python sphinx”找到http://hi.baidu.com/cyclone/blog/item/26949052956e7e010cf3e3da.html
安装¶
sudo easy_install Sphinx
配置¶
进入命令行，进入文档目录:
sphinx-quickstart
然后一条一条填下来，基本上就默认就可以了:
$sphinx-quickstart
> Root path for the documentation [.]:
> Separate source and build directories (y/N) [n]: y
> Name prefix for templates and static dir [_]:
> Project name: test
> Author name(s): su
> Project version: 1
> Project release [1]:
> Source file suffix [.rst]:
> Name of your master document (without suffix) [index]:
> Do you want to use the epub builder (y/N) [n]:
> 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]:
> pngmath: include math, rendered as PNG images (y/N) [n]:
> jsmath: include math, rendered in the browser by JSMath (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]:
> Create Makefile? (Y/n) [y]:
> Create Windows command file? (Y/n) [y]:
一路回车按下来……
然后把自己写的index.rst拷贝到source文件夹中
运行:
make html
输出一大堆后，打开build/html/index.html
就可以看到项目文档了
