写文档 ================== 小白听到同学的抱怨后，自己尝试着从用户的眼光再看了看自己写的代码。小白发现，同学的抱怨也挺有道理的。随着通讯录功能的增加，软件也越来越难用了。 “恩！的确需要一个软件文档。” 回顾需求 -------------------- 小白的程序基本成型了，但是缺少一个“说明书”，所以，小白要为自己的程序写个“说明书”——文档 编辑文档的工具，不能是慢的要死的word,又不能从头写网页…… 于是乎，行者给出两个利器：ReST、sphinx ReST ---------------------- 结构化文本reStructuredText？上网搜一搜，搜到一篇“简明教程” http://blog.csdn.net/jiyucn/article/details/2157189 摘录一段:: 我们已经知道了，所见即所得偏重的是外观设计，而不是代码。看起来不错，不过这种模式也有一些缺点。 比如我想强调某事，我可能就会有点犹豫……我是应该用粗体呢？还是应该用红色的字体？还有什么其它更好的方法么？ 小白：所想即所得？很好玩阿？但是太抽象了，能不能说的简单一些呢？ 好吧，做一个比较更加形象： RST代码:: title ========================= content :: code 相同效果的HTML代码 ::

title

content

code 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 就可以看到项目文档了 .. image :: ../_static/snap/sphinx.png 再发 ----------------------------- 隔壁室友研究了一会儿，终于承认：会用了 小白身边出现了一圈光环…… 升级到Lv2！又向hacker靠近一步！