Sphinx 0.5

发布版本 0.5.2（2009年3月24日）

  • 在LaTeX输出中正确处理 | .

  • #71: 如果源文件中发生解码错误,打印警告并用 “?” 替换字符.

  • 修复HTML搜索中的一个问题,如果索引加载时间过长.

  • 在解析时不要输出系统消息,因为即使 keep_warnings 为假,它们仍会保留在文档树中.

  • #82: 确定docutils注释的依赖项的正确路径.这修复了有关依赖文件的源总是被报告为已更改的行为.

  • 识别不在章节顶层而是在块项目（如表格）内的 toctree 指令.

  • 使用新的RFC基础URL,因为rfc.org似乎无法访问.

  • 修复了在未定义待办事项时,todolist指令导致崩溃的问题.

  • 如果 LaTeX 或 dvipng 在第一次未找到,请不要反复调用它们,遇到这种情况时请使用仅文本的 latex 作为替代.

  • 修复LaTeX输出中的脚注问题.

  • 在LaTeX输出中防止双连字符变成en-dash.

  • 以通用换行模式打开literalinclude文件,以允许任意换行约定.

  • 实际上使 -Q 选项有效.

  • #86: 修复toctrees中的显式文档标题.

  • #81: 以安全的方式写入环境和搜索索引,防止在转储过程中发生异常.

  • #80: 修复当使用setlocale()设置区域时的UnicodeErrors.

发布 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 扩展块不包含任何代码,则发出警告.

  • 修正对含有标记（特别是交叉引用角色）的 :param: 和 :type: 文档字段的处理.

  • #65: 修复pngmath扩展生成的PNG文件的深度信息存储.

  • 修复在类上下文之外使用 automethod 时导致的 autodoc 崩溃.

  • #68: 修复指定高度图像的LaTeX输出.

  • #60: 修复在子目录的源文件中包含图像时生成的图像路径错误.

  • 当 html_copy_source 关闭时,修复 JavaScript 搜索.

  • 修复在使用选项 autoclass_content = "both" 文档化类时 autodoc 的缩进问题.

  • 在空索引条目时不要崩溃,仅发出警告.

  • 修复了搜索JavaScript代码中的一个拼写错误,该错误导致某些设置下搜索功能无法使用.

发布 0.5（2008年11月23日）– 生日版!

新增加的功能

  • Markup features:

    • 引用现在是全局的:在任何文件中定义的所有引用都可以从任何文件中引用.引用会被收集到 LaTeX 输出的参考书目中.

    • 脚注在LaTeX生成器中现在得到了正确处理:它们出现在文本中脚注引用的位置,而不是章节末尾.感谢Andrew McNamara提供的初始补丁.

    • “系统消息”警告现在会自动从构建的文档中移除,仅写入stderr.如果您想要旧的行为,请将新的配置值 keep_warnings 设置为 True .

    • 词汇条目现在会自动添加到索引中.

    • 图像及其标题现在可以像章节标题一样引用,使用 :ref: 角色而不需要明确的链接文本.

    • 添加了 cmember 角色以保持一致性.

    • 现在按字母或罗马数字枚举的列表与标准reST中的处理方式一致.

    • The seealso directive can now also be given arguments, as a short form.

    • 您现在可以使用新的 program 指令来记录多个程序及其选项.

  • HTML 输出和模板:

    • 不兼容更改:”root” 关系链接（关系栏左上角）现在默认指向 master_doc ,不再指向名为 “index” 的文档.虽然旧的行为在某些情况下是有用的,但有些出乎意料.可以在模板中覆盖 “rootrellink” 块来定制其指向的位置.

    • JavaScript 搜索现在在搜索完整文本之前会先搜索对象.

    • 目录树条目现在具有CSS类,可以根据其深度对它们进行样式化.

    • 突出代码块现在具有 CSS 类,可以根据其语言对其进行样式设置.

    • 现在支持通过 Docutils meta 指令的 HTML <meta> 标签.

    • SerializingHTMLBuilder was added as new abstract builder that can be subclassed to serialize build HTML in a specific format. The PickleHTMLBuilder is a concrete subclass of it that uses pickle as serialization implementation.

    • JSONHTMLBuilder was added as another SerializingHTMLBuilder subclass that dumps the generated HTML into JSON files for further processing.

    • 布局模板中的 rellinks 块现在被称为 linktags ,以避免与 relbar 链接的混淆.

    • HTML构建器现在有两个额外的属性,可以用来禁用在标题和定义链接后的锚链接创建.

    • 仅在文档中有某些模块时生成模块索引.

  • 新增加和修改的配置值:

    • 在生成的文本中增加了对国际化的支持,使用了 language 和 locale_dirs 配置值.非常感谢语言贡献者:

      • Horst Gutmann – 德国人

      • Pavel Kosina – 捷克

      • David Larlet – 法国人

      • Michał Kandulski – 波兰语

      • Yasushi Masuda – 日本人

      • Guillem Borrell – 西班牙人

      • Luc Saffre 和 Peter Bertels – 荷兰

      • 弗雷德·林 – 繁体中文

      • 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 ,允许调整函数签名的 introspection.

    • sphinx.ext.autodoc 现在有了一个新的事件 autodoc-skip-member ,该事件允许调整在生成的内容中包含哪些成员.

    • 在自动文档化模块成员时,尊重 __all__ .

    • The automodule directive now supports the synopsis, deprecated and platform options.

  • 扩展 API:

    • Sphinx.add_node() now takes optional visitor methods for the HTML, LaTeX and text translators; this prevents having to manually patch the classes.

    • 添加了 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 构建目录中.

    • 在快速启动中,如果选择的根路径已经包含一个Sphinx项目,则报告错误并中止.

修复的错误

  • #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未最后包含所导致的.

  • 不要忽视没有任何参数的函数的返回注解.

  • 不要丢弃代码块的标签.