小介绍下Sphinx

打算写这个的原因是昨天看到了有人翻译的Tornado http://my.oschina.net/f1eming/blog/131382, 吐槽下作者翻译的不错,但是怎么看排版都不美观, 后来作者提到到他自己的blog上看,作者是用Markdown编写的, 个人感觉作为发布blog尚可, 但是是翻译的一本书总感觉有点不专业.

当然了此Sphinx非彼Sphinx, 它由Pocoo Team这个团队所做的一个文档工具,如果去Pocoo Team官网看的话发现他们做的东西都挺厉害的.

第一次知道Sphinx时是在看<Python科学计算>这本书后面作者讲到用Sphinx生成他想要的好多样式时,当时只是知道了下,并没有太多的了解. 后来才知道Sphinx的用户群很多, 如Python自带的文档就是这货生成的, OpenCV中的文档也是这货写的, Tornado的Document也是这货生成的. 如果要看更多的话可以看下http://sphinx-doc.org/examples.html这里, 很多项目都是它作为文档支持的, 甚至出书.

具体安装过程我就不介绍了, 基本Python安装方法, 下载下来python setup.py install即可, 如果遇到依赖包, 一并下载下来再安装, 偷懒就直接是用 pip, easy_install. 什么都帮你解决了.

Sphinx的文档是用reStructedText所写的,主要是由docutils这个作为底层驱动渲染的, 对比markdown, reStructedText好像是复杂些.当然了, 如果直接看github中的文档, 它这两个都支持在线渲染.

Sphinx使用方法,先创建一个文件夹,然后切换到其中虽然 sphinx-quickstart命令,就会有很多问题了,基本上无特殊要求默认即可,不过有几个地方还是要注意的.

 

起码知道项目是啥, 是谁写的,当然这些也可以在后面再次改写的. 然后一路下去就可以了.

最后会生成一小堆东西

快速测试下在刚才的命令行中输入make html(当然还有很多选项,不过有些要再安装依赖的东西)

在_build/html/index.html中就可以查看效果了(一个Python文档出来了).

下面是改下conf.py文件总是看这个样式看多了也实在不咋地

#1.

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None

#去掉注释, 改成
language = u'zh'

#2. 

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
html_theme = 'default'

#改成
html_theme = 'haiku'

修改cong.py后再次编译下:

效果不错.

下面就实际写文档了.

如introduce to tornado的第一章.就直接在根目录下创建文件'introduce.rst', 并且在index.rst中加入introduce

然后就可以在introduce.rst文件中添加文字了.

如下:

介绍上面后下面的====是确定标题的, 与之相关的还有单下边====和------

中间部分是扩展阅读, 可以这样来:

build一下:

很专业吧, 而且看index

继续添加完:

效果如下:

中间的代码段,和超链接格式如下

渲染的效果很不错的.

后面不写了, 发现网上有人翻译了官方文档 http://zh-sphinx-doc.readthedocs.org/en/latest/. 当然这个文档本身就是用这个写的.