Sphinx 1.0¶

版本 1.0.8 (2011年9月23日)¶

#627: 修复在自动摘要生成中引发的AttributeError的回溯错误.
修复 abbr 角色,当缩写中包含换行符时.
#727:修复自定义对象类型搜索结果的链接.
#648: 修复有关未定义引用的警告中报告的行号.
#696, #666: 修复不是类型名称的C++数组定义和模板参数.
#633: 允许在LaTeX输出的章节标题中使用脚注.
#616: 允许通过intersphinx链接关键字.
#613: 允许在生产列表令牌名称中使用Unicode字符.
#720: 为graphviz节点添加虚拟访客,用于文本和手册.
#704: 修复图片文件重复的bug.
#677: 修复C++域中多个签名的解析.
#637: 在查找源文件时忽略 Emacs 锁定文件.
#544: 允许在autodoc中使用.pyw扩展名的可导入模块.
#700: 在quickstart生成的Makefile中使用 $(MAKE) .
#734: 确保侧边栏搜索框在浏览器中的宽度一致.
#644: 修复HTML输出中居中图形的间距.
#767:在将 SphinxError 消息打印到 sys.stderr 时安全地编码它们.
#611:修复带有链接目标但没有章节的文档的 LaTeX 输出错误.
正确地将内置方法描述符视为 autodoc 中的方法.
#706: 停止猴子补丁 Python 的 textwrap 模块.
#657: viewcode 现在可以正确处理具有非 ASCII 编码的源文件.
#669: 在 py:module 指令中尊重 noindex 标志选项.
#675: 修复在使用 literalinclude 包含不存在的行时出现的 IndexErrors.
#676: 尊重自定义函数/方法参数分隔符字符串.
#682: 修复与 jQuery >= 1.5 的 JS 不兼容问题.
#693: 修复在写入 HTMLHelp .hhk 文件时发生的双重编码问题.
#647: 不要在解析文本块中应用SmartyPants.
C++领域现在支持数组定义.

Release 1.0.7（2011年1月15日）¶

#347: 修复在自动摘要中静态方法指令生成错误.
#599: 导入PIL为 from PIL import Image .
#558: 修复LaTeX输出中带标题的长表.
在LaTeX输出中,使令牌引用再次作为超链接工作.
#572: 默认显示警告,当找不到引用标签时.
#536: 在严格模式下,当抱怨缺失引用目标时包含行号.
#590: 修复LaTeX输出中graphviz图表的内联显示.
#589: 在设置命令中使用 app.build() 构建.
修复了一个继承图异常的错误,如果基类之一是内置类,则会导致跳过基类.
修复C++域对象的一般索引链接.
#332: 使 LaTeX 输出中的警告边界可见.
#573:修复在删除文件后重建时出现的 KeyErrors.
修复在删除带有通配符的toctrees文件时出现的追踪记录错误.
如果一个自动文档对象无法被导入,下一次构建时始终重新读取包含该指令的文档.
如果无法导入autodoc对象,则显示导入错误的完整回溯信息.
修复一个错误,以前删除下载文件和图像时没有被注意到.
#571: 为C域实现 ~ 交叉引用前缀.
修复与 #556 的修复相关的 LaTeX 输出回归.
#568: 修复描述符上类属性文档的查找,使评论文档现在工作.
修复在目标前置的 only 指令中出现的回溯错误.
修复出现重复C++域对象时的回溯错误.
修复带有 $ 名称的对象的JavaScript域链接.

Release 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 中,清理时请不要删除 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: 修复多个内置主题中的小布局错误.

版本 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 模块,但与simplejson不兼容.
#480: 修复在intersphinx中目标命名的处理.
#486: 修复所有交叉引用角色的 ! 移除问题.

发布 1.0.1 （2010年7月27日）¶

#470: 修复生成的目标名称对于 reST 域对象;它们不在同一个命名空间.
#266: 添加孟加拉语.
#473: 修复解析JavaScript对象名称的错误.
#474: 修复在没有 toctree 时使用 SingleHTMLBuilder 的构建问题.
修复与显式目标通过 intersphinx 链接的对象的显示名称.
修复使用JSON构建器时的构建问题.
修复 LaTeX 中对象描述的超链接.

Release 1.0 (2010年7月23日)¶

不兼容的更改¶

已添加对域的支持.域是一组指令和角色的集合,这些指令和角色描述了属于同一类别的对象,例如编程语言的元素.提供了一些内置的域:
- Python
- C
- C++
- JavaScript
- reStructuredText
定义和链接C指令的旧标记现已被弃用.在未来的版本中,如果不激活 oldcmarkup 扩展,它将无法再使用;在Sphinx 1.0中,该扩展默认被激活.
移除了对旧依赖版本的支持;现在的需求是:
- Docutils >= 0.5
- Jinja2 >= 2.2
移除了已弃用的元素:
- exclude_dirs config value
- sphinx.builder module

新增功能¶

一般:
- 新增了一个”挑剔”模式,该模式会对所有缺失的引用发出警告.可以通过 sphinx-build -n 命令行开关或 nitpicky 配置值来激活.
- 在快速启动的 Makefile 中添加了 latexpdf 目标.
Markup:
- The menuselection and guilabel roles now support ampersand accelerators.
- 现在识别新的更紧凑的文档字段语法: :param type name: description .
- 为 literalinclude 指令添加了 tab-width 选项.
- 为 toctree 指令添加了 titlesonly 选项.
- 添加了 literalinclude 指令的 prepend 和 append 选项.
- #284: 所有文档信息元数据现在都放入文档元数据中,不仅仅是作者信息.
- The ref role can now also reference tables by caption.
- The include directive now supports absolute paths, which are interpreted as relative to the source directory.
- 在Python领域,如果未找到直接匹配,引用如``:func:`.name``将查找带有任何前缀的匹配名称.
配置:
- 添加了 rst_prolog 配置值.
- 添加了 html_secnumber_suffix 配置值以控制章节编号格式.
- 添加了 html_compact_lists 配置值,以控制 Docutils 的紧凑列表功能.
- The html_sidebars config value can now contain patterns as keys, and the values can be lists that explicitly select which sidebar templates should be rendered. That means that the builtin sidebar contents can be included only selectively.
- html_static_path can now contain single file entries.
- 新的通用配置值 exclude_patterns 使得旧的 unused_docs 、 exclude_trees 和 exclude_dirnames 变得过时.
- 添加了 html_output_encoding 配置值.
- 添加了 latex_docclass 配置值,并且使得 “twoside” 文档类选项可被 “oneside” 覆盖.
- 添加了 trim_doctest_flags 配置值,默认为真.
- 新增了 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-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:
- 添加了:event:html-collect-pages .
- 添加了 needs_sphinx 配置值和 require_sphinx() 应用程序 API 方法.
- #200: 添加了:meth:!add_stylesheet 应用 API 方法.
扩展:
- 添加了 viewcode 扩展.
- 添加了 extlinks 扩展.
- 添加了对 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.
修复的漏洞:
- #445:修复使用 dirhtml 构建的HTML时搜索功能的结果页面链接.
- #444: 在模板中,正确地重新转义经过”striptags” Jinja过滤器处理的值.