Welcome
Sphinx 是一个工具,她能够轻易地创建智慧和优雅的文档,她是出自 Georg Brandl 之手,在 BSD 许可证下授权。
她最初是为了新版的 python 文档, 因此在 python 项目的文档具有完美的特性,但是同样支持 c/c++,目前正在计划增加对其他的语言的支持。 理所当然,本页面也是使用 Sphinx 创造自 reStructuredText 格式源!Sphinx 具有如下的特点:
- 输出格式: 超文本标记语言 (包括Windows HTML帮助),LaTeX (可打印的 PDF 版本),手册页,纯文本
- 丰富的交叉引用: 语义标记以及针对函数,类,引用,词汇表(术语)和相似的信息块的自动链接
- 层次结构: 简单的文本树定义,就能自动地链接到同层(兄弟姐妹)、上一层(父母)以及下一层(子女)的文本位置
- 自动生成目录: 通用索引以及语言模块的目录
- 代码高亮: 代码自动高亮,通过使用 Pygments
- 扩展功能: 自动测试的代码片段,包括从Python模块(API文档)的文档字符串
Sphinx 使用 reStructuredText 作为她的标记语言,她的优点大部分是来自于 reStructuredText 以及 reStructuredText 的解析和转换工具(套件) Docutils 的强大以及简单明了。
文档
初尝 Sphinx 目录 |
搜索页 通用索引 |
你也能下载 PDF 格式的 Sphinx 文档:一种PDF 版本 是由 LaTeX Sphinx 生成,另一种PDF 版本 是由 rst2pdf 生成。
实例
用 Sphinx 生成文档的项目能够在 Projects using Sphinx上找到。
想要查看 Sphinx 源文件长得什么样的话,可以在除本欢迎页外的任何页面上使用“显示网页源代码”。
你也许对这份十分不错 教程感兴趣,它是由 matplotlib 的开发者编写,是使用了 Sphinx 创建地自定义的文档。
已经有日语翻译的版本,多谢日本的 Sphinx 用户组的工作。
一本日语关于 Sphinx 的书籍已经由 O'Reilly 出版了: Sphinxをはじめよう / Learning Sphinx.
托管
需要一个地方托管你的 Sphinx 文档吗? readthedocs.org 已经托管了大量的 Sphinx 文档,并且与版本控制很好地结合。它也具有一个强大的内置的搜索,这个搜索超过了 Sphinx 的基于 JavaScript 离线的搜索的可能。