Sphinx 0.6

发布 0.6.7 (2010年6月5日)

  • #440: 移除 literalinclude 指令中对 Python >= 2.5 API 的使用。

  • 修复一个导致 LaTeX 构建器中无法生成某些引用的错误。

  • #428: 为标准 Docutils 类添加一些缺失的 CSS 样式。

  • #432: 修复在翻译的语言环境中构建 LaTeX 时出现的 UnicodeErrors。

发布 0.6.6 (2010年5月25日)

  • 在 text 编写器中处理原始节点。

  • 修复 qthelp 构建器生成的 Qt 帮助项目中的一个问题，该问题会导致 Qt Assistant 中不显示任何内容。

  • #393: 修复使用 pngmath 扩展时，数学公式中使用 Unicode 字符的问题。

  • #404: 使 \and 在 latex_documents 设置的 author 字段中正常工作。

  • #409: 使 highlight_language 配置值在 LaTeX 构建器中正常工作。

  • #418: 允许在 Unix 系统上将翻译 JavaScript 文件重新定位到系统目录。

  • #414: 修复使用 literalinclude 指令包含的文件中 Windows 换行符的处理问题。

  • #377: 修复 linkcheck 构建器中的崩溃。

  • #387: 修复 dirhtml 输出中搜索结果的显示问题。

  • #376: 在 autodoc 中，修复包含反斜杠的参数默认值的显示问题。

  • #370: 修复 LaTeX 输出中复杂列表项标签的处理问题。

  • #374: 使 doctest 扩展的 doctest_path 配置值真正生效。

  • 修复为 toctree() 模板函数创建全局 TOC 时处理多个 toctree 的问题。

  • 修复为 toctree() 模板函数创建全局 TOC 时处理隐藏 toctree 的问题。

  • 修复文本编写器中嵌套列表的处理问题。

  • #362: 在 autodoc 中，在访问函数对象上的 __self__ 之前检查其是否存在。

  • #353: 在搜索功能中提取搜索词时，去除前导和尾随空格。

发布 0.6.5 (2010年3月1日)

  • 在 autodoc 中，修复使用文档注释明确文档化的某些模块成员被遗漏的问题。

  • #345: 修复默认主题的 stickysidebar 选项导致侧边栏滚动条被裁剪的问题。

  • #341: 在 quickstart Makefile 中始终生成 UNIX 换行符。

  • #338: 修复在 Windows 下使用 -C 运行的问题。

  • 在 autodoc 中，允许在内置机制失败时自定义对象的签名。

  • #331: 修复 LaTeX 中带有起始值的枚举列表的输出问题。

  • 使 literalinclude 指令的 start-after 和 end-before 选项在不一起使用时正常工作。

  • #321: 修复 LaTeX 构建器中链接生成的问题。

发布 0.6.4 (2010年1月12日)

  • 改进配置中非 Unicode 字符串的处理。

  • #316: 捕获调用 graphviz 时因参数不理解而产生的 OSErrors。

  • 恢复与 Pygments >= 1.2 的兼容性。

  • #295: 修复 LaTeX 输出中 hyperref 目标的转义问题。

  • #302: 修复 :doc: 角色为 LaTeX 输出生成的链接。

  • #286: 在读取整个文档后收集 todo 节点；这允许在 todo 项中放置替换引用。

  • #294: 在 LaTeX 构建中不要忽略显式的 today 配置值。

  • 继承图的 alt 文本现在更清晰了。

  • 生成链接标题时忽略章节标题中的图片。

  • #310: 支持 doctest 扩展的 testoutput 块中的异常消息。

  • #293: HTML 输出中的行块样式正确。

  • #285: 再次使 locale_dirs 配置值生效。

  • #303: 通过 -A 在命令行上给出的 html_context 值不应覆盖 conf.py 中给出的其他值。

  • 修复阻止 dirhtml 构建器增量重建的错误。

  • #299: 修复某些字面块中引号的混乱。

  • #292: 修复 dirhtml 构建器搜索索引的路径。

  • 修复 Jython 兼容性问题：使对 parser 模块的依赖可选。

  • #238: 在 autodoc 中，捕获模块导入时发生的所有错误，而不仅仅是 ImportError。

  • 修复 autodoc 中非数据但非方法描述符的处理。

  • 复制文件时间时，忽略 os.utime() 引发的 OSErrors。

发布 0.6.3 (2009年9月3日)

  • 在 autodoc 中正确添加 C 模块文件名作为依赖项。

  • #253: 忽略没有内容的 graphviz 指令，而不是引发未处理的异常。

  • #241: 修复包含 todolist 指令的文档构建 LaTeX 输出时发生的崩溃。

  • #252: 使 quickstart 生成的 Makefile 中更容易更改构建目录。

  • #220: 修复 CSS 以便 displaymath 真正居中。

  • #222: 允许翻译“Footnotes”标题。

  • #225: 在生成的 HTML 中内联标签后不添加空格。

  • #227: 使 literalinclude 在文档路径名包含非 ASCII 字符时正常工作。

  • #229: 修复成员在 getattr() 上引发错误时的 autodoc 失败问题。

  • #205: 复制文件时，不复制完整的 stat 信息，只复制修改时间。

  • #232: 支持 Qt 帮助构建器中的非 ASCII 元数据。

  • 为 LaTeX 正确格式化定义列表中嵌套的无序列表。

  • 现在允许在 only 指令中包含章节标题。

  • #201: 使 centered 指令在 LaTeX 输出中正常工作。

  • #206: 拒绝在 sphinx-quickstart 中覆盖现有的主文档。

  • #208: 在 HTML 帮助构建器中，使用由 language 配置选项确定的 MS 认可的语言环境设置。

  • #210: 修复 pngmath 扩展中显示的数学公式的 HTML 标签嵌套问题。

  • #213: 修复 LaTeX 输出中图像居中问题。

  • #211: 修复与 Docutils 0.5 的兼容性。

发布 0.6.2 (2009年6月16日)

  • #130: 修复 doctest 扩展中模糊的 IndexError。

  • #167: 使词汇表排序不区分大小写。

  • #196: 如果扩展模块没有 setup() 函数，则添加警告。

  • #158: 允许模板名称中包含“..”，并允许使用绝对模板路径；Jinja 2 默认禁用这两者。

  • 在突出显示 Python 代码时，在尝试将其解析为 Python 之前，忽略额外的缩进。

  • #191: 在 LaTeX 的 URI 中不转义波浪号。

  • 搜索索引不考虑源注释的内容。

  • 将默认编码设置为 utf-8-sig 以正确处理带有 UTF-8 BOM 的文件。

  • #178: 将 add_function_parentheses 配置值应用于 C 函数，如承诺的那样。

  • #173: 遵守 Docutils title 指令。

  • #172: obj 角色现在链接到模块，如承诺的那样。

  • #19: 表格现在可以有一个“longtable”类，以便在 LaTeX 输出中正确地分页。

  • 在尝试 sphinx/locale 之前，在系统默认路径中查找 Sphinx 消息目录。

  • 修复通过“classname.methodname”搜索方法的问题。

  • #155: 修复 Python 2.4 兼容性：在那里异常是旧式类。

  • #150: 修复 Internet Explorer 6 和 7 版本上“sphinxdoc”主题的显示问题。

  • #146: 当用户有活动的 .docutils 配置时，不要生成 LaTeX 失败。

  • #29: 在 LaTeX 选项列表中不生成可见的“-{-}”。

  • 修复放入替换中的交叉引用角色。

  • 不要将图像“alt”文本放入目录条目中。

  • 在 LaTeX 编写器中，如果章节级别过多，不要引发异常，只需将所有级别都使用“subparagraph”级别。

  • #145: 修复 autodoc 中自动成员拒绝从其父级 getattr() 的问题。

  • 如果在命令行上给出了要构建的特定文件名，请检查它们是否在源目录中。

  • 修复没有 __name__ 的对象的 autodoc 崩溃。

  • 修复没有 urllib2.HTTPSHandler 的安装的 intersphinx 问题。

  • #134: 修复使用 todo 扩展的 todolist 指令时，pending_xref 遗留节点的问题。

发布 0.6.1 (2009年3月26日)

  • #135: 修复 LaTeX 输出和 graphviz 扩展的问题。

  • #132: 在发行版中包含 autosummary“module”模板。

发布 0.6 (2009年3月24日)

新增功能

  • 不兼容的变更

    • 模板现在需要 Jinja2 库，它是旧 Jinja1 引擎的增强版本。由于语法和语义大致相同，自定义模板中应该很少需要修复。

    • “document” div 标签已从 layout.html 模板的“document”块移出，因为结束标签已经在外面。如果您覆盖此块，您也需要移除您的“document” div 标签。

    • autodoc_skip_member 事件现在也可以决定是否跳过名称以下划线开头的成员。以前，这些成员总是自动跳过。因此，如果您处理此事件，请在事件处理程序中添加类似以下内容以恢复旧行为

      if name.startswith('_'):
    return True

  • 主题支持，请参阅文档中的新部分。

  • 标记

    • 由于需求旺盛，添加了 :doc: 角色，它直接链接到另一个文档，无需创建 :ref: 可以链接到的标签。

    • #4: 添加了 :download: 角色，用于标记非文档文件以包含到 HTML 输出中并链接到它。

    • 添加了一个 only 指令，可以根据启用的“标签”有选择地包含文本。标签可以在命令行上给出。此外，当前的构建器输出格式（例如“html”或“latex”）始终是一个已定义的标签。

    • #10: 添加了 HTML 章节编号，通过向 toctree 指令提供 :numbered: 标志来启用。

    • #114: 添加了 abbr 角色来标记缩写和首字母缩写。

    • literalinclude 指令现在支持更多选项，以仅包含文件的一部分。

    • toctree 指令现在支持 :hidden: 标志，这将阻止在指令位置生成链接 – 这允许您定义文档结构，但自己放置链接。

    • #123: glossary 指令现在支持 :sorted: 标志，按字母顺序对词汇表条目进行排序。

    • 图像、字面包含文件和下载文件的路径现在可以是绝对路径（如 /images/foo.png）。它们被视为相对于顶部源目录。

    • #52: 现在有一个 hlist 指令，通过将项目分发到多个列来创建紧凑列表。

    • #77: 如果带有信息字段列表的描述环境只包含一个 :param: 条目，则不生成无序列表。

    • #6: 不为顶级 TOC 树项生成冗余的 <ul>，这会导致 TOC 条目在视觉上分离。

    • #23: 添加了 classmethod 指令以及 method 和 staticmethod。

    • 缩放图像现在会链接到未缩放版本。

    • HTML 现在支持 SVG 图像（通过 <object> 和 <embed> 标签）。

    • 向模板添加了一个可调用的 toctree，以及在 toctree 中包含外部链接的功能。“collapse”关键字参数指示是否仅显示当前页面的子项。（默认为 True。）

  • 配置

    • 新的配置值 rst_epilog 可以包含追加到每个读取的源文件的 reST。这是全局替换的正确位置。

    • 新的 html_add_permalinks 配置值可用于关闭为每个标题和定义环境生成的“段落符号”永久链接。

    • 新的 html_show_sourcelink 配置值可用于关闭侧边栏中到 reST 源的链接。

    • htmlhelp_basename 的默认值现在是项目标题，清理后作为文件名。

    • 新的 modindex_common_prefix 配置值可用于忽略某些包名称以进行模块索引排序。

    • 新的 trim_footnote_reference_space 配置值与同名的 Docutils 配置值相同，并删除了脚注引用前识别引用所需的空格。

    • 新的 latex_additional_files 配置值可用于将文件（Sphinx 不会自动复制的文件，例如，如果在 latex_elements 中添加的自定义 LaTeX 中引用它们）复制到构建目录。

  • 构建器

    • HTML 构建器现在在其输出目录中存储一个名为 .buildinfo 的小文件。它存储配置值的哈希，可用于确定是否需要完全重建（例如，更改 html_theme 后）。

    • 由 Antonio Valentino 创建的 Qt 帮助集合新构建器。

    • 新的 DirectoryHTMLBuilder（简称 dirhtml）为每个页面创建一个单独的目录，并将页面放置在该目录中名为 index.html 的文件中。因此，页面 URL 和链接不需要包含 .html。

    • 新的 html_link_suffix 配置值可用于选择 HTML 文件之间生成的链接的后缀。

    • #96: LaTeX 构建器现在支持使用 figwidth 选项和右/左对齐时，文本环绕的图。

  • 新翻译

    • 意大利语由 Sandro Dentella 翻译。

    • 乌克兰语由 Petro Sasnyk 翻译。

    • 芬兰语由 Jukka Inkeri 翻译。

    • 俄语由 Alexander Smishlajev 翻译。

  • 扩展和 API

    • 新的 graphviz 扩展用于嵌入 graphviz 图。

    • 新的 inheritance_diagram 扩展用于嵌入……继承图！

    • 新的 autosummary 扩展，用于生成模块摘要和模块的自动文档。

    • Autodoc 现在有一个可重用的 Python API，可用于创建自定义类型的对象以进行自动文档（例如 Zope 接口）。另请参见 Sphinx.add_autodocumenter()。

    • Autodoc 现在处理已文档化的属性。

    • Autodoc 现在处理内部类及其方法。

    • 如果明确用 autofunction 标记，Autodoc 现在可以将类文档化为函数。

    • Autodoc 现在可以通过 exclude-members 选项从文档中排除单个成员。

    • Autodoc 现在可以按字母顺序（如以前）或按成员类型对成员进行排序；可通过配置值 autodoc_member_order 或每个指令的 member-order 选项进行配置。

    • 函数 Sphinx.add_directive() 现在也支持 Docutils 0.5 风格的指令类。如果它们继承自 sphinx.util.compat.Directive，它们也适用于 Docutils 0.4。

    • 现在有一个 Sphinx.add_lexer() 方法可以轻松使用自定义 Pygments 词法分析器。

    • 现在有 Sphinx.add_generic_role() 来镜像 Docutils 自己的函数。

  • 其他更改

    • 单个字典键的配置覆盖现在可以在命令行上给出。

    • 现在有一个 doctest_global_setup 配置值，可用于为文档中的所有 doctest 提供设置代码。

    • HTML 中的源链接现在使用 rel="nofollow" 生成。

    • Quickstart 现在可以生成 Windows make.bat 文件。

    • #62: 现在 sphinx-build 有一个 -w 选项，除了标准错误输出外，还可以将警告写入文件。

    • 现在 sphinx-build 有一个 -W 选项，可以将警告转换为错误。