Sphinx 0.2

Release 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（应用对象）:

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

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

    • 添加对其他模板引擎（除了Jinja）的支持,通过添加一个称为 “模板桥接” 的抽象.该类处理模板的渲染,并可以使用新的配置值 “template_bridge” 进行更改.

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

  • Markup:

    • 新的指令 currentmodule .它可以用来指示后续文档内容的模块名称,而不会创建索引条目.

    • 允许在toctree中为文档提供不同的标题.

    • 允许在 cmdoption 指令中提供多个选项.

    • 修复未给出明确类名时类成员的显示问题.

  • 模板 (HTML 输出):

    • index.html renamed to defindex.html, see above.

    • 有一个新的配置值 html_title ,它控制整个 Sphinx 文档集的 “标题”. 现在它会在所有地方替代 “项目名称 vX.Y 文档”.

    • 所有模板中有关 “文档 “的引用已被删除,因此现在使用默认模板使用 Sphinx 进行非文档文件变得更加容易.

    • 模板现在具有XHTML文档类型,以便与Docutils的HTML输出保持一致.

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

    • 您现在可以通过使用 html_logo 配置值快速在侧边栏中包含一个logo.

    • 侧边栏中有新的块,您可以轻松地将内容插入到侧边栏中.

  • LaTeX输出:

    • The sphinx.sty package was cleaned of unused stuff.

    • 您可以在标题页中包含一个徽标,使用 latex_logo 配置值.

    • 您可以为逐字环境定义链接颜色、边框和背景颜色.

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

修复的错误

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

  • sphinx.htmlwriter: 不要使用 os.path 来连接图像 HREFs.

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

  • sphinx.latexwriter: 实现选项列表.此外,还对 sphinx.sty 进行了其他一些更改,以增强兼容性并移除旧的未使用内容.感谢 Gael Varoquaux 的贡献!

  • sphinx.roles:修复引用具有显式目标的术语表条目.

  • sphinx.environment: 在解析子树时不要忽略目录条目.

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

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

  • sphinx.util: 在查找文档时跟随符号链接.