Sphinx 0.2

版本 0.2 (2008年4月27日)

不兼容的变更

  • Jinja，默认 HTML 模板使用的模板引擎，现在不再随 Sphinx 一起发布。如果它没有自动为您安装（它现在在 setup.py 中被列为依赖项），请从 PyPI 手动安装。如果您正在使用 SVN 检出的 Sphinx，这也将是必需的；在这种情况下，请同时删除可能从旧版本遗留的 sphinx/jinja 目录。

  • 对 index.html 模板的笨拙处理已被移除。html_index 配置值已不存在，应改用 html_additional_pages。如果您需要，旧的 index.html 模板仍然存在，名为 defindex.html，您可以通过更改模板并使用 Jinja 继承来移植您的 html_index 模板

    {% extends "defindex.html" %}
{% block tables %}
... old html_index template content ...
{% endblock %}

    并将 'index': 您的模板名称 放入 html_additional_pages 中。

  • 在布局模板中，删除了冗余的 block；您应该改用 Jinja 的标准 {{ super() }} 机制，如（新编写的）模板文档中所述。

新增功能

  • 扩展 API (Application 对象)

    • 支持一个新方法 add_crossref_type。它的工作方式类似于 add_description_unit，但指令只会创建一个目标而不会产生输出。

    • 支持一个新方法 add_transform。它接受一个标准的 Docutils Transform 子类，该子类随后由 Sphinx 的阅读器在解析 reST 文档树时应用。

    • 通过添加一个名为“模板桥接”的抽象，支持除 Jinja 之外的其他模板引擎。该类处理模板的渲染，并可以使用新的配置值“template_bridge”进行更改。

    • 配置文件本身可以是一个扩展（如果它提供了一个 setup() 函数）。

  • 标记

    • 新的指令 currentmodule。它可用于指示后续文档内容的模块名称，而无需创建索引条目。

    • 允许在 toctree 中为文档指定不同的标题。

    • 允许在 cmdoption 指令中指定多个选项。

    • 修复了未明确给定类名时类成员的显示问题。

  • 模板 (HTML 输出)

    • index.html 已重命名为 defindex.html，详见上文。

    • 有一个新的配置值 html_title，它控制 Sphinx 文档集的整体“标题”。现在它在所有地方都取代了“项目名称 vX.Y 文档”。

    • 模板中所有对“文档”的引用都已被移除，因此现在使用 Sphinx 及其默认模板更容易处理非文档类文件。

    • 模板现在具有 XHTML doctype，以与 Docutils 的 HTML 输出保持一致。

    • 您现在可以使用 html_use_opensearch 配置值创建 OpenSearch 描述文件。

    • 您现在可以使用 html_logo 配置值快速在侧边栏中包含一个标志。

    • 侧边栏中新增了一些块，以便您可以轻松地将内容插入侧边栏。

  • LaTeX 输出

    • sphinx.sty 包已清除未使用的内容。

    • 您可以使用 latex_logo 配置值在标题页中包含一个标志。

    • 您可以定义链接颜色以及逐字环境的边框和背景颜色。

感谢 Jacob Kaplan-Moss、Talin、Jeroen Ruigrok van der Werven 和 Sebastian Wiesner 提供的建议。

修复的 Bug

  • sphinx.ext.autodoc: 不检查显式给定成员的 __module__。在类构造函数参数列表中删除“self”。

  • sphinx.htmlwriter: 不使用 os.path 来拼接图像 HREFs。

  • sphinx.htmlwriter: 不对 HTML 属性值使用 SmartyPants。

  • sphinx.latexwriter: 实现了选项列表。此外，sphinx.sty 也进行了一些其他更改，以增强兼容性并删除旧的未使用的内容。感谢 Gael Varoquaux！

  • sphinx.roles: 修复了带有显式目标的术语表引用问题。

  • sphinx.environment: 解决子树时不要吞噬 TOC 条目。

  • sphinx.quickstart: 创建一个合理的默认 latex_documents 设置。

  • sphinx.builder, sphinx.environment: 优雅地处理一些用户错误情况。

  • sphinx.util: 搜索文档时跟随符号链接。