Sphinx 0.5¶

0.5.2 版本 (2009年3月24日)¶

正确地转义 LaTeX 输出中的 |。
#71: 如果源文件中发生解码错误，则打印警告并将字符替换为“?”。
修复 HTML 搜索中如果索引加载时间过长的问题。
在解析时不要输出系统消息，因为即使 keep_warnings 为 false，它们也会保留在 doctree 中。
#82: 确定 docutils 注意到的依赖项的正确路径。这修复了带有依赖文件的源总是报告为已更改的行为。
识别不在节顶层，而是在块项目（例如表格）内的 toctree 指令。
使用新的 RFC 基本 URL，因为 rfc.org 似乎已关闭。
修复 todolist 指令在未定义任何待办事项时崩溃的问题。
如果 LaTeX 或 dvipng 一次未找到，则不要反复调用它们，在这种情况下，使用纯文本 LaTeX 作为替代。
修复 LaTeX 输出中脚注的问题。
防止 LaTeX 输出中字面代码中的双连字符变为长破折号。
以通用换行模式打开 literalinclude 文件，以允许任意换行约定。
实际上使 -Q 选项起作用。
#86: 修复 toctree 中的显式文档标题。
#81: 以安全的方式编写环境和搜索索引，防止在转储期间发生的异常。
#80: 修复使用 setlocale() 设置区域设置时发生的 UnicodeError。

0.5.1 版本 (2008年12月15日)¶

#67: 即使在安静模式下运行，也要在 doctest 扩展中输出有关失败的 doctest 的警告。
#72: 在 pngmath 中，可以在 Windows 上为 LaTeX 和 dvipng 提供完整路径。为此，pngmath_latex 和 pngmath_dvipng 选项不再拆分为命令和附加参数；使用 pngmath_latex_args 和 pngmath_dvipng_args 来提供附加参数。
不要在带有非 ASCII 字符的失败 doctest 上崩溃。
不要在写入包含无法编码字符的状态消息和警告时崩溃。
如果 doctest 扩展块不包含任何代码，则发出警告。
修复处理 :param: 和 :type: 文档字段中包含标记（尤其是交叉引用角色）的问题。
#65: 修复 pngmath 扩展生成的 PNG 的深度信息存储。
修复在类上下文之外使用 automethod 时 autodoc 崩溃的问题。
#68: 修复 LaTeX 编写器输出指定高度的图像。
#60: 修复在子目录中包含图像时生成的错误图像路径。
修复 html_copy_source 关闭时的 JavaScript 搜索。
修复 autodoc 中在文档类中设置选项 autoclass_content = "both" 时的缩进问题。
不要在空索引条目上崩溃，只发出警告。
修复搜索 JavaScript 代码中的拼写错误，导致在某些设置中搜索功能无法使用。

0.5 版本 (2008年11月23日) – 生日特别版！¶

新增功能¶

标记功能
- 引用现在是全局的：任何文件中定义的所有引用都可以在任何文件中引用。引用在 LaTeX 输出的参考书目中收集。
- 脚注现在在 LaTeX 构建器中得到正确处理：它们出现在文本中脚注引用的位置，而不是在节的末尾。感谢 Andrew McNamara 的初始补丁。
- “系统消息”警告现在会自动从生成的文档中删除，只写入 stderr。如果您想要旧行为，请将新的配置值 keep_warnings 设置为 True。
- 词汇表条目现在会自动添加到索引中。
- 带有标题的图现在可以像节标题一样引用，使用 :ref: 角色，无需显式链接文本。
- 添加了 cmember 角色以保持一致性。
- 按字母或罗马数字枚举的列表现在像标准 reST 中一样处理。
- seealso 指令现在也可以作为简短形式提供参数。
- 您现在可以使用新的 program 指令文档多个程序及其选项。
HTML 输出和模板
- 不兼容的更改： “root” 关系链接（relbar 左上角）现在默认指向 master_doc，不再指向名为“index”的文档。旧行为虽然在某些情况下有用，但有些出乎意料。覆盖模板中的“rootrellink”块以自定义其指向的位置。
- JavaScript 搜索现在在全文搜索之前搜索对象。
- TOC 树条目现在具有 CSS 类，可以根据其深度进行样式设置。
- 高亮显示的代码块现在具有 CSS 类，可以根据其语言进行样式设置。
- 现在支持通过 Docutils meta 指令生成的 HTML <meta> 标签。
- SerializingHTMLBuilder 作为新的抽象构建器添加，可以子类化以特定格式序列化构建的 HTML。PickleHTMLBuilder 是它的一个具体子类，它使用 pickle 作为序列化实现。
- JSONHTMLBuilder 作为另一个 SerializingHTMLBuilder 子类添加，它将生成的 HTML 转储到 JSON 文件中以供进一步处理。
- 布局模板中的 rellinks 块现在更名为 linktags，以避免与 relbar 链接混淆。
- HTML 构建器现在有两个额外的属性，可用于禁用标题和定义链接后的锚链接创建。
- 只有当文档中存在一些模块时才生成模块索引。
新增和更改的配置值
- 通过 language 和 locale_dirs 配置值，增加了对生成文本国际化的支持。非常感谢语言贡献者：
  - Horst Gutmann – 德语
  - Pavel Kosina – 捷克语
  - David Larlet – 法语
  - Michał Kandulski – 波兰语
  - Yasushi Masuda – 日语
  - Guillem Borrell – 西班牙语
  - Luc Saffre 和 Peter Bertels – 荷兰语
  - Fred Lin – 繁体中文
  - Roger Demetrescu – 巴西葡萄牙语
  - Rok Garbas – 斯洛文尼亚语
- 新的配置值 highlight_language 设置了高亮显示的全局默认值。当选择 'python3' 时，控制台输出块被识别为 'python'。
- 将 Pygments 的词法分析器猜测公开为高亮显示“语言” guess。
- 新的配置值 latex_elements 允许覆盖 Sphinx 默认放入生成的 .tex 文件中的所有 LaTeX 片段。
- 添加了 exclude_dirnames 配置值，可用于从源文件搜索中排除例如 CVS 目录。
- 添加了 source_encoding 配置值以选择输入编码。
扩展
- 新的扩展 sphinx.ext.jsmath 和 sphinx.ext.pngmath 为 HTML 和 LaTeX 构建器提供数学支持。
- 新的扩展 sphinx.ext.intersphinx 半自动地创建指向其他项目中 Python 对象的 Sphinx 文档的链接。
- 新的扩展 sphinx.ext.todo 允许插入“待办事项”指令，其在输出中的可见性可以切换。它还添加了一个指令来编译所有待办事项的列表。
- sphinx.ext.autodoc 有一个新事件 autodoc-process-signature，允许调整函数签名自省。
- sphinx.ext.autodoc 有一个新事件 autodoc-skip-member，允许调整包含在生成内容中的成员。
- 在自动文档模块成员时尊重 __all__。
- automodule 指令现在支持 synopsis、deprecated 和 platform 选项。
扩展 API
- Sphinx.add_node() 现在接受 HTML、LaTeX 和文本翻译器的可选访问者方法；这避免了手动修补类。
- 添加了 Sphinx.add_javascript()，它将脚本添加到默认 HTML 模板中加载。
- 添加了新事件： source-read、env-updated、env-purge-doc、missing-reference、build-finished。
其他更改
- 添加了命令行开关 -Q：它将抑制警告。
- 添加了命令行开关 -A：它可用于向 HTML 模板提供额外的值。
- 添加了命令行开关 -C：如果给定，则不需要配置文件 conf.py。
- 添加了 distutils 命令 build_sphinx：安装 Sphinx 后，您可以为具有 Sphinx 文档的项目调用 python setup.py build_sphinx，这将构建文档并将其放置在标准的 distutils 构建目录中。
- 在 quickstart 中，如果选择的根路径已经包含一个 Sphinx 项目，则抱怨并中止。

修复的 Bug¶

#51: 转义放置在 HTML 模板中的配置值。
#44: 修复 HTML 帮助索引生成中的小问题。
修复表格中行块的 LaTeX 输出。
#38: 修复使用像素图像宽度/高度时出现的“非法单位”错误。
支持 LaTeX 输出中的表格标题。
#39: 解决了 Jinja 中的一个错误，该错误导致 HTML 输出中发出“<generator ...>”。
修复 LaTeX 输出中未生成模块链接的问题。
修复处理不同目录中图像的问题。
#29: 支持文本编写器中的选项列表。确保引入长选项名称的破折号不会缩写为长破折号。
支持 HTML 输出中图像的“scale”选项。
#25: 正确转义 HTML 帮助属性值中的引号。
修复某些带有 :noindex: 的描述环境的 LaTeX 构建。
#24: 不要在角色名称的不常见大小写（如 :Class:）上崩溃。
仅在彩色终端上输出 ANSI 颜色。
更新到最新的 fncychap.sty，以修复章节标题开头带有非 ASCII 字符的问题。
修复 LaTeX 输出中索引生成的问题，这是由于 hyperref 未最后包含导致的。
不要忽略没有任何参数的函数的返回注释。
不要丢弃代码块的标签。