自动索引和文档创建工具:Sphinx

项目地址:http://www.pocoo.org/projects/sphinx/

功能分类:内容管理/新闻类   技术分类:杂项其他

更新时间:2011-05-14 16:24:29

用户关注:6001 次

用户评价:5 次 我来点评↓

sphinx logo

什么是sphinx?

sphinx不是那个全文检索引擎! 是一个写文档的工具: sphinx

它有什么特性?

  • python文档所使用的系统
  • 输出HTML, LaTeX, manual pages, 纯文本..
  • 层级结构, 内链
  • 自动索引
  • 语法高亮
  • 扩展: graphivz, docstrings, 等等..

让我们开始尝试一下

创建一个项目

新建一个目录, 然后执行下面的命令:

sphinx-quickstart

只要回答一些问题就好了. 全部默认, 除了一个: 文档和生成的文件不要放在一个目录下, 方便整理

会在你指定的目录下面生成一些文件. 我们来看看这些文件吧.

目录

$ find
.
./Makefile               # 工具帮我们生成的makefile
./build                  # 生成文档后放置的目录
./source                 # 文档源码的位置
./source/index.rst       # 文档的入口
./source/conf.py         # 项目的一些设置, 上面quickstart设置的部分内容可以在里面修改
./source/_static         # 静态文档存放目录
./source/_templates      # 模板存放目录

开写哈

我们开启index.rst, 主要结构是这里, 我们可以在上面加东西扩展文档:

Contents:

.. toctree::
   :maxdepth: 2

# 我们在这里加内容
intro
tutorial

然后我们就可以继续写intro.rst, tutorial.rst等文档了. 这些文档的格式都采用restructuredtext方式.

文档对象

如果你要写一个python函数的定义, 这样写:

.. py:function:: enumerate(sequence[, start=0])

Return an iterator that yields tuples of an index and an item of the
*sequence*. (And so on.)

这里是连接 :py:func:`enumerate`

对应的文档介绍在这里: http://sphinx.pocoo.org/tutorial.html#documenting-objects

自动导入代码中的文档

sphinx一个非常好的功能, 就是可以自动嵌入代码中的文档, 如果你有一个模块io.open

.. autofunction:: io.open

.. automodule:: io
   :members:

sphinx必须先知道你的模块位置, 要在 conf.py 里面把目录加到 sys.path 里面去.

conf.py里面必须加sphinx.ext.autodoc的模块.

生成我们需要的格式

最后我们需要把文档生成我们想要的格式, 方法如下:

sphinx-build

$ sphinx-build -b html sourcedir builddir

make

$ make html

以上介绍资料来源:http://server.linjunhalida.com/blog/article/sphinx%E4%BB%8B%E7%BB%8D/

Pocoo 团队作品,可能是 python 相关的最好文档生成工具了了。

项目实例:

我是作者,想要修改项目内容?把修改内容发到联系邮箱(看最底部)

用户评价 (5)

     

称呼(*)

网站

邮箱

填写右边的单词 simple

Copyright© Python4cn(news, jobs) simple-is-better.com, 技术驱动:powered by web.py 空间主机:Webfaction

版权申明:文章转载已注明出处,如有疑问请来信咨询。本站为 python 语言推广公益网站,与 python 官方没有任何关系。

联系/投搞/留言: en.simple.is.better@gmail.com 向本站捐赠