Sphinx 1.0

发布 1.0.8 (2011年9月23日)

  • #627: 修复 autosummary 生成中 AttributeError 的追溯。

  • 修复当缩写中包含换行符时 abbr 角色。

  • #727: 修复带有自定义对象类型的搜索结果链接。

  • #648: 修复有关未定义引用的警告中报告的行号。

  • #696, #666: 修复 C++ 数组定义和不是类型名的模板参数。

  • #633: 允许 LaTeX 输出中章节标题中包含脚注。

  • #616: 允许通过 intersphinx 链接关键字。

  • #613: 允许生产列表 token 名称中包含 Unicode 字符。

  • #720: 为 text 和 man 的 graphviz 节点添加虚拟访问器。

  • #704: 修复图像文件重复的 bug。

  • #677: 修复 C++ 域中多个签名的解析。

  • #637: 在查找源文件时忽略 Emacs 锁文件。

  • #544: 允许 autodoc 中可导入模块使用 .pyw 扩展名。

  • #700: 在 quickstart 生成的 Makefiles 中使用 $(MAKE)。

  • #734: 使浏览器中侧边栏搜索框宽度一致。

  • #644: 修复 HTML 输出中居中图形的间距。

  • #767: 在将 SphinxError 消息打印到 sys.stderr 时安全编码。

  • #611: 修复 LaTeX 输出中无章节但有链接目标的文档错误。

  • 正确地将内置方法描述符视为 autodoc 中的方法。

  • #706: 停止猴子补丁 Python 的 textwrap 模块。

  • #657: viewcode 现在可以正确处理非 ASCII 编码的源文件。

  • #669: 遵守 py:module 指令中的 noindex 标志选项。

  • #675: 修复当 literalinclude 包含不存在的行时的 IndexError。

  • #676: 遵守自定义函数/方法参数分隔符字符串。

  • #682: 修复与 jQuery >= 1.5 的 JS 不兼容性。

  • #693: 修复写入 HTMLHelp .hhk 文件时进行的双重编码。

  • #647: 不要在解析的字面块中应用 SmartyPants。

  • C++ 域现在支持数组定义。

发布 1.0.7 (2011年1月15日)

  • #347: 修复 autosummary 中静态方法指令的错误生成。

  • #599: 导入 PIL 为 from PIL import Image。

  • #558: 修复 LaTeX 输出中带有标题的 longtables。

  • 使 LaTeX 输出中的 token 引用再次作为超链接工作。

  • #572: 默认显示找不到引用标签时的警告。

  • #536: 在吹毛求疵模式下抱怨缺少引用目标时包含行号。

  • #590: 修复 LaTeX 输出中 graphviz 图的内联显示。

  • #589: 在 setup 命令中使用 app.build() 进行构建。

  • 修复继承图异常中的一个 bug，该 bug 导致如果其中一个基类是内置的，则会跳过基类。

  • 修复 C++ 域对象的通用索引链接。

  • #332: 使 LaTeX 输出中的训诫边界可见。

  • #573: 修复删除文件后重建时发生的 KeyError。

  • 修复删除带有通配符 toctree 的文件时的追溯。

  • 如果 autodoc 对象无法导入，则在下次构建时始终重新读取包含指令的文档。

  • 如果 autodoc 对象无法导入，则显示导入错误的完整追溯。

  • 修复未注意到下载文件和图像被删除的 bug。

  • #571: 为 C 域实现 ~ 交叉引用前缀。

  • 修复 #556 修复后 LaTeX 输出的回归。

  • #568: 修复描述符上类属性文档的查找，以便注释文档现在可以工作。

  • 修复 only 指令前面有目标时发生的追溯。

  • 修复重复的 C++ 域对象引起的追溯。

  • 修复 JavaScript 域链接到名称中包含 $ 的对象。

发布 1.0.6 (2011年1月4日)

  • #581: 修复 Python 域中空交叉引用目标的追溯。

  • #283: 修复 Chrome 浏览器上字面块显示问题。

  • #383, #148: 支持在通用索引和词汇表中对有限范围的重音字符进行排序。

  • #570: 尝试使用区域设置的首选编码解码 -D 和 -A 命令行参数。

  • #528: 查找 JS 翻译文件时遵守 locale_dirs。

  • #574: 为 LaTeX 构建器中日语文档的更好支持添加特殊代码。

  • #77 的回归: 如果 :param: 标记只给出一个参数，现在再次抑制项目列表。

  • #556: 修复某些情况下 LaTeX 输出中缺少段落换行的问题。

  • #567: 即使对于没有文档字符串的对象也发出 autodoc-process-docstring 事件，以便它可以添加内容。

  • #565: 在 LaTeX 构建器中，不仅字面块需要不同的表格处理，还有许多其他列表式块元素。

  • #515: 修复 viewcode 扩展中 Python 对象没有有效签名时的追溯。

  • 修复由于 Docutils 版本不同而导致 autodoc 包含的文档字符串生成的警告的行号报告异常。

  • 对 C++ 域的几处修复。

发布 1.0.5 (2010年11月12日)

  • #557: 为 Docutils 0.7 添加对齐图像和图形所需的 CSS 样式。

  • 在 LaTeX 输出生成的 Makefile 中，不要在 clean 时删除 pdf 文件；它们可能是必需的图像。

  • #535: 修复为行块生成的 LaTeX 输出。

  • #544: 允许 .pyw 作为源文件扩展名。

发布 1.0.4 (2010年9月17日)

  • #524: 在 Windows 上以二进制模式打开 intersphinx 清单，因为版本 2 包含 zlib 压缩数据。

  • #513: 允许为 JavaScript 文件提供非本地 URI，例如在 JSMath 扩展中。

  • #512: 修复当 intersphinx_mapping 为空时的追溯。

发布 1.0.3 (2010年8月23日)

  • #495: 修复来自 Docutils 目录的链接的内部与外部链接区别。

  • #494: 修复当与 collapse=True 一起使用时，toctree() 模板可调用项的 maxdepth 选项。

  • #507: 修复解析包含字符串字面量中方括号的 Python 参数列表时崩溃。

  • #501: 修复构建没有标题的图形的 LaTeX 文档时的回归。

  • #510: 修复不可序列化的类的继承图。

  • #497: 为侧边栏折叠按钮引入单独的背景颜色，使其更容易看到。

  • #502, #503, #496: 修复几个内置主题中的小型布局 bug。

发布 1.0.2 (2010年8月14日)

  • #490: 修复对通过 add_object_type() API 函数添加的类型对象的交叉引用。

  • 修复不同指令类型的文档字段类型的处理。

  • 允许断开长签名，用反斜杠转义的换行符继续。

  • 修复 C 域引用的不必要样式（由于与 Pygments 样式命名空间冲突）。

  • 允许通过显式锚点引用 PEP 和 RFC。

  • #471: 修复 LaTeX 对图形的引用。

  • #482: 进行非精确搜索时，只匹配给定类型的对象。

  • #481: 将非精确搜索应用于 Python 引用目标，对模块也使用 .name。

  • #484: 修复信息字段列表中参数重复时崩溃。

  • #487: 修复将默认角色设置为 oldcmarkup 扩展提供的角色。

  • #488: 修复安装 json-py 时崩溃，json-py 提供了一个 json 模块但与 simplejson 不兼容。

  • #480: 修复 intersphinx 中目标命名的处理。

  • #486: 修复所有交叉引用角色中 ! 的删除。

发布 1.0.1 (2010年7月27日)

  • #470: 修复 reST 域对象生成的目标名称；它们不在同一个命名空间。

  • #266: 添加孟加拉语。

  • #473: 修复解析 JavaScript 对象名称的 bug。

  • #474: 修复使用 SingleHTMLBuilder 构建时没有 toctree 的情况。

  • 修复 intersphinx 链接到带有显式目标的对象时的显示名称。

  • 修复使用 JSON 构建器进行构建。

  • 修复 LaTeX 对象描述中的超链接。

发布 1.0 (2010年7月23日)

不兼容的变更

  • 已添加对域的支持。域是指令和角色的集合，它们都描述属于一起的对象，例如编程语言的元素。提供了几个内置域

    • Python

    • C

    • C++

    • JavaScript

    • reStructuredText

  • 用于定义和链接 C 指令的旧标记现已弃用。将来版本中，如果不激活 oldcmarkup 扩展，它将不再起作用；在 Sphinx 1.0 中，它默认激活。

  • 移除对旧依赖版本的支持；现在要求是

    • Docutils >= 0.5

    • Jinja2 >= 2.2

  • 已移除弃用元素

    • exclude_dirs 配置值

    • sphinx.builder 模块

新增功能

  • 通用

    • 添加了“吹毛求疵”模式，它会对所有缺失的引用发出警告。它通过 sphinx-build -n 命令行开关或 nitpicky 配置值激活。

    • 在 quickstart Makefile 中添加了 latexpdf 目标。

  • 标记

    • menuselection 和 guilabel 角色现在支持 ampersand 加速器。

    • 现在识别新的更紧凑的文档字段语法: :param type name: description。

    • 为 literalinclude 指令添加了 tab-width 选项。

    • 为 toctree 指令添加了 titlesonly 选项。

    • 为 literalinclude 指令添加了 prepend 和 append 选项。

    • #284: 所有 docinfo 元数据现在都放入文档元数据中，而不仅仅是作者。

    • ref 角色现在也可以按标题引用表格。

    • include 指令现在支持绝对路径，这些路径被解释为相对于源目录。

    • 在 Python 域中，像 :func:`.name` 这样的引用，如果没有直接匹配，现在会查找任何前缀的匹配名称。

  • 配置

    • 添加了 rst_prolog 配置值。

    • 添加了 html_secnumber_suffix 配置值来控制章节编号格式。

    • 添加了 html_compact_lists 配置值来控制 Docutils 的紧凑列表功能。

    • html_sidebars 配置值现在可以包含模式作为键，并且值可以是明确选择应渲染哪些侧边栏模板的列表。这意味着内置侧边栏内容可以有选择地包含。

    • html_static_path 现在可以包含单个文件条目。

    • 新的通用配置值 exclude_patterns 使旧的 unused_docs、exclude_trees 和 exclude_dirnames 过时。

    • 添加了 html_output_encoding 配置值。

    • 添加了 latex_docclass 配置值，并使“twoside”文档类选项可以被“oneside”覆盖。

    • 添加了 trim_doctest_flags 配置值，默认为 true。

    • 添加了 html_show_copyright 配置值。

    • 添加了 latex_show_pagerefs` 和 latex_show_urls 配置值。

    • html_file_suffix` 的行为略有改变：空字符串现在表示“无后缀”而不是“默认后缀”，使用 None 表示“默认后缀”。

  • 新构建器

    • 添加了 Epub 格式的构建器。

    • 添加了手册页的构建器。

    • 添加了单文件 HTML 构建器。

  • HTML 输出

    • 内联角色现在会获得一个以其名称命名的 CSS 类，允许样式自定义其外观。特定域的角色会获得两个类，domain 和 domain-rolename。

    • 引用现在会获得 internal 类，如果它们是整个项目内部的，而不是当前页面内部的。

    • 外部引用可以使用默认主题的新 externalrefs 主题选项进行不同的样式设置。

    • 在默认主题中，侧边栏现在可以使用新的 collapsiblesidebar 主题选项进行实验性折叠。

    • #129: 在 HTML 输出中，Toctree 现在被包装在带有类 toctree-wrapper 的 div 标签中。

    • 模板中的 toctree 可调用项现在有一个 maxdepth 关键字参数来控制生成树的深度。

    • 模板中的 toctree 可调用项现在接受 titles_only 关键字参数。

    • 在布局模板中添加了 htmltitle 块。

    • 在 JavaScript 搜索中，允许搜索包含模块名称的对象名称，例如 sys.argv。

    • 添加了新主题 haiku，灵感来自 Haiku OS 用户指南。

    • 添加了新主题 nature。

    • 添加了新主题 agogo，由 Andi Albrecht 创建。

    • 添加了新主题 scrolls，由 Armin Ronacher 创建。

    • #193: 为默认主题添加了 visitedlinkcolor 主题选项。

    • #322: 通过异步加载搜索索引，提高了搜索页面的响应速度。

  • 扩展 API

    • 添加了 html-collect-pages。

    • 添加了 needs_sphinx 配置值和 require_sphinx() 应用程序 API 方法。

    • #200: 添加了 add_stylesheet() 应用程序 API 方法。

  • 扩展

    • 添加了 viewcode 扩展。

    • 添加了 extlinks 扩展。

    • 添加了对 autodoc 中成员源顺序的支持，使用 autodoc_member_order = 'bysource'。

    • 添加了 autodoc_default_flags 配置值，可用于选择所有 autodoc 指令的默认标志。

    • 添加了 intersphinx 引用其他项目中命名标签的方式，并指定要链接到的项目。

    • #280: Autodoc 现在可以记录在 __init__ 方法中分配的实例属性。

    • 对 autosummary 扩展进行了许多改进和修复，感谢 Pauli Virtanen。

    • #309: graphviz 扩展现在可以输出 SVG 而不是 PNG 图像，由 graphviz_output_format 配置值控制。

    • 为 graphviz 扩展指令添加了 alt 选项。

    • 为 autodoc.between() 添加了 exclude 参数。

  • 翻译

    • 添加了克罗地亚语翻译，感谢 Bojan Mihelač。

    • 添加了土耳其语翻译，感谢 Firat Ozgul。

    • 添加了加泰罗尼亚语翻译，感谢 Pau Fernández。

    • 添加了简体中文翻译。

    • 添加了丹麦语翻译，感谢 Hjorth Larsen。

    • 添加了立陶宛语翻译，感谢 Dalius Dobravolskas。

  • 修复的 Bug

    • #445: 修复使用 dirhtml 构建器构建的 HTML 搜索功能中结果页面的链接。

    • #444: 在模板中，正确地重新转义经过“striptags”Jinja 过滤器处理的值。