1Release 3.5.2 (released Mar 06, 2021) 2===================================== 3 4Bugs fixed 5---------- 6 7* #8943: i18n: Crashed by broken translation messages in ES, EL and HR 8* #8936: LaTeX: A custom LaTeX builder fails with unknown node error 9* #8952: Exceptions raised in a Directive cause parallel builds to hang 10 11Release 3.5.1 (released Feb 16, 2021) 12===================================== 13 14Bugs fixed 15---------- 16 17* #8883: autodoc: AttributeError is raised on assigning __annotations__ on 18 read-only class 19* #8884: html: minified js stemmers not included in the distributed package 20* #8885: html: AttributeError is raised if CSS/JS files are installed via 21 :confval:`html_context` 22* #8880: viewcode: ExtensionError is raised on incremental build after 23 unparsable python module found 24 25Release 3.5.0 (released Feb 14, 2021) 26===================================== 27 28Dependencies 29------------ 30 31* LaTeX: ``multicol`` (it is anyhow a required part of the official latex2e 32 base distribution) 33 34Incompatible changes 35-------------------- 36 37* Update Underscore.js to 1.12.0 38* #6550: html: The config variable ``html_add_permalinks`` is replaced by 39 :confval:`html_permalinks` and :confval:`html_permalinks_icon` 40 41Deprecated 42---------- 43 44* pending_xref node for viewcode extension 45* ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.anchors_ignore`` 46* ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.auth`` 47* ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.broken`` 48* ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.good`` 49* ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.redirected`` 50* ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.rqueue`` 51* ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.to_ignore`` 52* ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.workers`` 53* ``sphinx.builders.linkcheck.CheckExternalLinksBuilder.wqueue`` 54* ``sphinx.builders.linkcheck.node_line_or_0()`` 55* ``sphinx.ext.autodoc.AttributeDocumenter.isinstanceattribute()`` 56* ``sphinx.ext.autodoc.directive.DocumenterBridge.reporter`` 57* ``sphinx.ext.autodoc.importer.get_module_members()`` 58* ``sphinx.ext.autosummary.generate._simple_info()`` 59* ``sphinx.ext.autosummary.generate._simple_warn()`` 60* ``sphinx.writers.html.HTMLTranslator.permalink_text`` 61* ``sphinx.writers.html5.HTML5Translator.permalink_text`` 62 63Features added 64-------------- 65 66* #8022: autodoc: autodata and autoattribute directives does not show right-hand 67 value of the variable if docstring contains ``:meta hide-value:`` in 68 info-field-list 69* #8514: autodoc: Default values of overloaded functions are taken from actual 70 implementation if they're ellipsis 71* #8775: autodoc: Support type union operator (PEP-604) in Python 3.10 or above 72* #8297: autodoc: Allow to extend :confval:`autodoc_default_options` via 73 directive options 74* #8619: html: kbd role generates customizable HTML tags for compound keys 75* #8634: html: Allow to change the order of JS/CSS via ``priority`` parameter 76 for :meth:`Sphinx.add_js_file()` and :meth:`Sphinx.add_css_file()` 77* #6241: html: Allow to add JS/CSS files to the specific page when an extension 78 calls ``app.add_js_file()`` or ``app.add_css_file()`` on 79 :event:`html-page-context` event 80* #6550: html: Allow to use HTML permalink texts via 81 :confval:`html_permalinks_icon` 82* #1638: html: Add permalink icons to glossary terms 83* #8868: html search: performance issue with massive lists 84* #8867: html search: Update JavaScript stemmer code to the latest version of 85 Snowball (v2.1.0) 86* #8852: i18n: Allow to translate heading syntax in MyST-Parser 87* #8649: imgconverter: Skip availability check if builder supports the image 88 type 89* #8573: napoleon: Allow to change the style of custom sections using 90 :confval:`napoleon_custom_styles` 91* #8004: napoleon: Type definitions in Google style docstrings are rendered as 92 references when :confval:`napoleon_preprocess_types` enabled 93* #6241: mathjax: Include mathjax.js only on the document using equations 94* #8775: py domain: Support type union operator (PEP-604) 95* #8651: std domain: cross-reference for a rubric having inline item is broken 96* #7642: std domain: Optimize case-insensitive match of term 97* #8681: viewcode: Support incremental build 98* #8132: Add :confval:`project_copyright` as an alias of :confval:`copyright` 99* #207: Now :confval:`highlight_language` supports multiple languages 100* #2030: :rst:dir:`code-block` and :rst:dir:`literalinclude` supports automatic 101 dedent via no-argument ``:dedent:`` option 102* C++, also hyperlink operator overloads in expressions and alias declarations. 103* #8247: Allow production lists to refer to tokens from other production groups 104* #8813: Show what extension (or module) caused it on errors on event handler 105* #8213: C++: add ``maxdepth`` option to :rst:dir:`cpp:alias` to insert nested 106 declarations. 107* C, add ``noroot`` option to :rst:dir:`c:alias` to render only nested 108 declarations. 109* C++, add ``noroot`` option to :rst:dir:`cpp:alias` to render only nested 110 declarations. 111 112Bugs fixed 113---------- 114 115* #8727: apidoc: namespace module file is not generated if no submodules there 116* #741: autodoc: inherited-members doesn't work for instance attributes on super 117 class 118* #8592: autodoc: ``:meta public:`` does not effect to variables 119* #8594: autodoc: empty __all__ attribute is ignored 120* #8315: autodoc: Failed to resolve struct.Struct type annotation 121* #8652: autodoc: All variable comments in the module are ignored if the module 122 contains invalid type comments 123* #8693: autodoc: Default values for overloaded functions are rendered as string 124* #8134: autodoc: crashes when mocked decorator takes arguments 125* #8800: autodoc: Uninitialized attributes in superclass are recognized as 126 undocumented 127* #8655: autodoc: Failed to generate document if target module contains an 128 object that raises an exception on ``hasattr()`` 129* #8306: autosummary: mocked modules are documented as empty page when using 130 :recursive: option 131* #8232: graphviz: Image node is not rendered if graph file is in subdirectory 132* #8618: html: kbd role produces incorrect HTML when compound-key separators (-, 133 + or ^) are used as keystrokes 134* #8629: html: A type warning for html_use_opensearch is shown twice 135* #8714: html: kbd role with "Caps Lock" rendered incorrectly 136* #8123: html search: fix searching for terms containing + (Requires a custom 137 search language that does not split on +) 138* #8665: html theme: Could not override globaltoc_maxdepth in theme.conf 139* #8446: html: consecutive spaces are displayed as single space 140* #8745: i18n: crashes with KeyError when translation message adds a new auto 141 footnote reference 142* #4304: linkcheck: Fix race condition that could lead to checking the 143 availability of the same URL twice 144* #8791: linkcheck: The docname for each hyperlink is not displayed 145* #7118: sphinx-quickstart: questionare got Mojibake if libreadline unavailable 146* #8094: texinfo: image files on the different directory with document are not 147 copied 148* #8782: todo: Cross references in todolist get broken 149* #8720: viewcode: module pages are generated for epub on incremental build 150* #8704: viewcode: anchors are generated in incremental build after singlehtml 151* #8756: viewcode: highlighted code is generated even if not referenced 152* #8671: :confval:`highlight_options` is not working 153* #8341: C, fix intersphinx lookup types for names in declarations. 154* C, C++: in general fix intersphinx and role lookup types. 155* #8683: :confval:`html_last_updated_fmt` does not support UTC offset (%z) 156* #8683: :confval:`html_last_updated_fmt` generates wrong time zone for %Z 157* #1112: ``download`` role creates duplicated copies when relative path is 158 specified 159* #2616 (fifth item): LaTeX: footnotes from captions are not clickable, 160 and for manually numbered footnotes only first one with same number is 161 an hyperlink 162* #7576: LaTeX with French babel and memoir crash: "Illegal parameter number 163 in definition of ``\FNH@prefntext``" 164* #8055: LaTeX (docs): A potential display bug with the LaTeX generation step 165 in Sphinx (how to generate one-column index) 166* #8072: LaTeX: Directive :rst:dir:`hlist` not implemented in LaTeX 167* #8214: LaTeX: The :rst:role:`index` role and the glossary generate duplicate 168 entries in the LaTeX index (if both used for same term) 169* #8735: LaTeX: wrong internal links in pdf to captioned code-blocks when 170 :confval:`numfig` is not True 171* #8442: LaTeX: some indexed terms are ignored when using xelatex engine 172 (or pdflatex and :confval:`latex_use_xindy` set to True) with memoir class 173* #8750: LaTeX: URLs as footnotes fail to show in PDF if originating from 174 inside function type signatures 175* #8780: LaTeX: long words in narrow columns may not be hyphenated 176* #8788: LaTeX: ``\titleformat`` last argument in sphinx.sty should be 177 bracketed, not braced (and is anyhow not needed) 178* #8849: LaTex: code-block printed out of margin (see the opt-in LaTeX syntax 179 boolean :ref:`verbatimforcewraps <latexsphinxsetupforcewraps>` for use via 180 the :ref:`'sphinxsetup' <latexsphinxsetup>` key of ``latex_elements``) 181* #8183: LaTeX: Remove substitution_reference nodes from doctree only on LaTeX 182 builds 183* #8865: LaTeX: Restructure the index nodes inside title nodes only on LaTeX 184 builds 185* #8796: LaTeX: potentially critical low level TeX coding mistake has gone 186 unnoticed so far 187* C, :rst:dir:`c:alias` skip symbols without explicit declarations 188 instead of crashing. 189* C, :rst:dir:`c:alias` give a warning when the root symbol is not declared. 190* C, ``expr`` role should start symbol lookup in the current scope. 191 192Release 3.4.3 (released Jan 08, 2021) 193===================================== 194 195Bugs fixed 196---------- 197 198* #8655: autodoc: Failed to generate document if target module contains an 199 object that raises an exception on ``hasattr()`` 200 201Release 3.4.2 (released Jan 04, 2021) 202===================================== 203 204Bugs fixed 205---------- 206 207* #8164: autodoc: Classes that inherit mocked class are not documented 208* #8602: autodoc: The ``autodoc-process-docstring`` event is emitted to the 209 non-datadescriptors unexpectedly 210* #8616: autodoc: AttributeError is raised on non-class object is passed to 211 autoclass directive 212 213Release 3.4.1 (released Dec 25, 2020) 214===================================== 215 216Bugs fixed 217---------- 218 219* #8559: autodoc: AttributeError is raised when using forward-reference type 220 annotations 221* #8568: autodoc: TypeError is raised on checking slots attribute 222* #8567: autodoc: Instance attributes are incorrectly added to Parent class 223* #8566: autodoc: The ``autodoc-process-docstring`` event is emitted to the 224 alias classes unexpectedly 225* #8583: autodoc: Unnecessary object comparision via ``__eq__`` method 226* #8565: linkcheck: Fix PriorityQueue crash when link tuples are not 227 comparable 228 229Release 3.4.0 (released Dec 20, 2020) 230===================================== 231 232Incompatible changes 233-------------------- 234 235* #8105: autodoc: the signature of class constructor will be shown for decorated 236 classes, not a signature of decorator 237 238Deprecated 239---------- 240 241* The ``follow_wrapped`` argument of ``sphinx.util.inspect.signature()`` 242* The ``no_docstring`` argument of 243 ``sphinx.ext.autodoc.Documenter.add_content()`` 244* ``sphinx.ext.autodoc.Documenter.get_object_members()`` 245* ``sphinx.ext.autodoc.DataDeclarationDocumenter`` 246* ``sphinx.ext.autodoc.GenericAliasDocumenter`` 247* ``sphinx.ext.autodoc.InstanceAttributeDocumenter`` 248* ``sphinx.ext.autodoc.SlotsAttributeDocumenter`` 249* ``sphinx.ext.autodoc.TypeVarDocumenter`` 250* ``sphinx.ext.autodoc.importer._getannotations()`` 251* ``sphinx.ext.autodoc.importer._getmro()`` 252* ``sphinx.pycode.ModuleAnalyzer.parse()`` 253* ``sphinx.util.osutil.movefile()`` 254* ``sphinx.util.requests.is_ssl_error()`` 255 256Features added 257-------------- 258 259* #8119: autodoc: Allow to determine whether a member not included in 260 ``__all__`` attribute of the module should be documented or not via 261 :event:`autodoc-skip-member` event 262* #8219: autodoc: Parameters for generic class are not shown when super class is 263 a generic class and show-inheritance option is given (in Python 3.7 or above) 264* autodoc: Add ``Documenter.config`` as a shortcut to access the config object 265* autodoc: Add Optional[t] to annotation of function and method if a default 266 value equal to None is set. 267* #8209: autodoc: Add ``:no-value:`` option to :rst:dir:`autoattribute` and 268 :rst:dir:`autodata` directive to suppress the default value of the variable 269* #8460: autodoc: Support custom types defined by typing.NewType 270* #8285: napoleon: Add :confval:`napoleon_attr_annotations` to merge type hints 271 on source code automatically if any type is specified in docstring 272* #8236: napoleon: Support numpydoc's "Receives" section 273* #6914: Add a new event :event:`warn-missing-reference` to custom warning 274 messages when failed to resolve a cross-reference 275* #6914: Emit a detailed warning when failed to resolve a ``:ref:`` reference 276* #6629: linkcheck: The builder now handles rate limits. See 277 :confval:`linkcheck_retry_on_rate_limit` for details. 278 279Bugs fixed 280---------- 281 282* #7613: autodoc: autodoc does not respect __signature__ of the class 283* #4606: autodoc: the location of the warning is incorrect for inherited method 284* #8105: autodoc: the signature of class constructor is incorrect if the class 285 is decorated 286* #8434: autodoc: :confval:`autodoc_type_aliases` does not effect to variables 287 and attributes 288* #8443: autodoc: autodata directive can't create document for PEP-526 based 289 type annotated variables 290* #8443: autodoc: autoattribute directive can't create document for PEP-526 291 based uninitalized variables 292* #8480: autodoc: autoattribute could not create document for __slots__ 293 attributes 294* #8503: autodoc: autoattribute could not create document for a GenericAlias as 295 class attributes correctly 296* #8534: autodoc: autoattribute could not create document for a commented 297 attribute in alias class 298* #8452: autodoc: autodoc_type_aliases doesn't work when autodoc_typehints is 299 set to "description" 300* #8541: autodoc: autodoc_type_aliases doesn't work for the type annotation to 301 instance attributes 302* #8460: autodoc: autodata and autoattribute directives do not display type 303 information of TypeVars 304* #8493: autodoc: references to builtins not working in class aliases 305* #8522: autodoc: ``__bool__`` method could be called 306* #8067: autodoc: A typehint for the instance variable having type_comment on 307 super class is not displayed 308* #8545: autodoc: a __slots__ attribute is not documented even having docstring 309* #741: autodoc: inherited-members doesn't work for instance attributes on super 310 class 311* #8477: autosummary: non utf-8 reST files are generated when template contains 312 multibyte characters 313* #8501: autosummary: summary extraction splits text after "el at." unexpectedly 314* #8524: html: Wrong url_root has been generated on a document named "index" 315* #8419: html search: Do not load ``language_data.js`` in non-search pages 316* #8549: i18n: ``-D gettext_compact=0`` is no longer working 317* #8454: graphviz: The layout option for graph and digraph directives don't work 318* #8131: linkcheck: Use GET when HEAD requests cause Too Many Redirects, to 319 accommodate infinite redirect loops on HEAD 320* #8437: Makefile: ``make clean`` with empty BUILDDIR is dangerous 321* #8365: py domain: ``:type:`` and ``:rtype:`` gives false ambiguous class 322 lookup warnings 323* #8352: std domain: Failed to parse an option that starts with bracket 324* #8519: LaTeX: Prevent page brake in the middle of a seealso 325* #8520: C, fix copying of AliasNode. 326 327Release 3.3.1 (released Nov 12, 2020) 328===================================== 329 330Bugs fixed 331---------- 332 333* #8372: autodoc: autoclass directive became slower than Sphinx-3.2 334* #7727: autosummary: raise PycodeError when documenting python package 335 without __init__.py 336* #8350: autosummary: autosummary_mock_imports causes slow down builds 337* #8364: C, properly initialize attributes in empty symbols. 338* #8399: i18n: Put system locale path after the paths specified by configuration 339 340Release 3.3.0 (released Nov 02, 2020) 341===================================== 342 343Deprecated 344---------- 345 346* ``sphinx.builders.latex.LaTeXBuilder.usepackages`` 347* ``sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref`` 348* ``sphinx.ext.autodoc.SingledispatchFunctionDocumenter`` 349* ``sphinx.ext.autodoc.SingledispatchMethodDocumenter`` 350 351Features added 352-------------- 353 354* #8100: html: Show a better error message for failures on copying 355 html_static_files 356* #8141: C: added a ``maxdepth`` option to :rst:dir:`c:alias` to insert 357 nested declarations. 358* #8081: LaTeX: Allow to add LaTeX package via ``app.add_latex_package()`` until 359 just before writing .tex file 360* #7996: manpage: Add :confval:`man_make_section_directory` to make a section 361 directory on build man page 362* #8289: epub: Allow to suppress "duplicated ToC entry found" warnings from epub 363 builder using :confval:`suppress_warnings`. 364* #8298: sphinx-quickstart: Add :option:`sphinx-quickstart --no-sep` option 365* #8304: sphinx.testing: Register public markers in sphinx.testing.fixtures 366* #8051: napoleon: use the obj role for all See Also items 367* #8050: napoleon: Apply :confval:`napoleon_preprocess_types` to every field 368* C and C++, show line numbers for previous declarations when duplicates are 369 detected. 370* #8183: Remove substitution_reference nodes from doctree only on LaTeX builds 371 372Bugs fixed 373---------- 374 375* #8085: i18n: Add support for having single text domain 376* #6640: i18n: Failed to override system message translation 377* #8143: autodoc: AttributeError is raised when False value is passed to 378 autodoc_default_options 379* #8103: autodoc: functools.cached_property is not considered as a property 380* #8190: autodoc: parsing error is raised if some extension replaces docstring 381 by string not ending with blank lines 382* #8142: autodoc: Wrong constructor signature for the class derived from 383 typing.Generic 384* #8157: autodoc: TypeError is raised when annotation has invalid __args__ 385* #7964: autodoc: Tuple in default value is wrongly rendered 386* #8200: autodoc: type aliases break type formatting of autoattribute 387* #7786: autodoc: can't detect overloaded methods defined in other file 388* #8294: autodoc: single-string __slots__ is not handled correctly 389* #7785: autodoc: autodoc_typehints='none' does not effect to overloaded functions 390* #8192: napoleon: description is disappeared when it contains inline literals 391* #8142: napoleon: Potential of regex denial of service in google style docs 392* #8169: LaTeX: pxjahyper loaded even when latex_engine is not platex 393* #8215: LaTeX: 'oneside' classoption causes build warning 394* #8175: intersphinx: Potential of regex denial of service by broken inventory 395* #8277: sphinx-build: missing and redundant spacing (and etc) for console 396 output on building 397* #7973: imgconverter: Check availability of imagemagick many times 398* #8255: py domain: number in default argument value is changed from hexadecimal 399 to decimal 400* #8316: html: Prevent arrow keys changing page when button elements are focused 401* #8343: html search: Fix unnecessary load of images when parsing the document 402* #8254: html theme: Line numbers misalign with code lines 403* #8093: The highlight warning has wrong location in some builders (LaTeX, 404 singlehtml and so on) 405* #8215: Eliminate Fancyhdr build warnings for oneside documents 406* #8239: Failed to refer a token in productionlist if it is indented 407* #8268: linkcheck: Report HTTP errors when ``linkcheck_anchors`` is ``True`` 408* #8245: linkcheck: take source directory into account for local files 409* #8321: linkcheck: ``tel:`` schema hyperlinks are detected as errors 410* #8323: linkcheck: An exit status is incorrect when links having unsupported 411 schema found 412* #8188: C, add missing items to internal object types dictionary, 413 e.g., preventing intersphinx from resolving them. 414* C, fix anon objects in intersphinx. 415* #8270, C++, properly reject functions as duplicate declarations if a 416 non-function declaration of the same name already exists. 417* C, fix references to function parameters. 418 Link to the function instead of a non-existing anchor. 419* #6914: figure numbers are unexpectedly assigned to uncaptioned items 420* #8320: make "inline" line numbers un-selectable 421 422Testing 423-------- 424 425* #8257: Support parallel build in sphinx.testing 426 427Release 3.2.1 (released Aug 14, 2020) 428===================================== 429 430Features added 431-------------- 432 433* #8095: napoleon: Add :confval:`napoleon_preprocess_types` to enable the type 434 preprocessor for numpy style docstrings 435* #8114: C and C++, parse function attributes after parameters and qualifiers. 436 437Bugs fixed 438---------- 439 440* #8074: napoleon: Crashes during processing C-ext module 441* #8088: napoleon: "Inline literal start-string without end-string" warning in 442 Numpy style Parameters section 443* #8084: autodoc: KeyError is raised on documenting an attribute of the broken 444 class 445* #8091: autodoc: AttributeError is raised on documenting an attribute on Python 446 3.5.2 447* #8099: autodoc: NameError is raised when target code uses ``TYPE_CHECKING`` 448* C++, fix parsing of template template paramters, broken by the fix of #7944 449 450Release 3.2.0 (released Aug 08, 2020) 451===================================== 452 453Deprecated 454---------- 455 456* ``sphinx.ext.autodoc.members_set_option()`` 457* ``sphinx.ext.autodoc.merge_special_members_option()`` 458* ``sphinx.writers.texinfo.TexinfoWriter.desc`` 459* C, parsing of pre-v3 style type directives and roles, along with the options 460 :confval:`c_allow_pre_v3` and :confval:`c_warn_on_allowed_pre_v3`. 461 462Features added 463-------------- 464 465* #2076: autodoc: Allow overriding of exclude-members in skip-member function 466* #8034: autodoc: ``:private-member:`` can take an explicit list of member names 467 to be documented 468* #2024: autosummary: Add :confval:`autosummary_filename_map` to avoid conflict 469 of filenames between two object with different case 470* #8011: autosummary: Support instance attributes as a target of autosummary 471 directive 472* #7849: html: Add :confval:`html_codeblock_linenos_style` to change the style 473 of line numbers for code-blocks 474* #7853: C and C++, support parameterized GNU style attributes. 475* #7888: napoleon: Add aliases Warn and Raise. 476* #7690: napoleon: parse type strings and make them hyperlinks as possible. The 477 conversion rule can be updated via :confval:`napoleon_type_aliases` 478* #8049: napoleon: Create a hyperlink for each the type of parameter when 479 :confval:`napoleon_use_params` is False 480* C, added :rst:dir:`c:alias` directive for inserting copies 481 of existing declarations. 482* #7745: html: inventory is broken if the docname contains a space 483* #7991: html search: Allow searching for numbers 484* #7902: html theme: Add a new option :confval:`globaltoc_maxdepth` to control 485 the behavior of globaltoc in sidebar 486* #7840: i18n: Optimize the dependencies check on bootstrap 487* #7768: i18n: :confval:`figure_language_filename` supports ``docpath`` token 488* #5208: linkcheck: Support checks for local links 489* #5090: setuptools: Link verbosity to distutils' -v and -q option 490* #6698: doctest: Add ``:trim-doctest-flags:`` and ``:no-trim-doctest-flags:`` 491 options to doctest, testcode and testoutput directives 492* #7052: add ``:noindexentry:`` to the Python, C, C++, and Javascript domains. 493 Update the documentation to better reflect the relationship between this option 494 and the ``:noindex:`` option. 495* #7899: C, add possibility of parsing of some pre-v3 style type directives and 496 roles and try to convert them to equivalent v3 directives/roles. 497 Set the new option :confval:`c_allow_pre_v3` to ``True`` to enable this. 498 The warnings printed from this functionality can be suppressed by setting 499 :confval:`c_warn_on_allowed_pre_v3`` to ``True``. 500 The functionality is immediately deprecated. 501* #7999: C, add support for named variadic macro arguments. 502* #8071: Allow to suppress "self referenced toctrees" warning 503 504Bugs fixed 505---------- 506 507* #7886: autodoc: TypeError is raised on mocking generic-typed classes 508* #7935: autodoc: function signature is not shown when the function has a 509 parameter having ``inspect._empty`` as its default value 510* #7901: autodoc: type annotations for overloaded functions are not resolved 511* #904: autodoc: An instance attribute cause a crash of autofunction directive 512* #1362: autodoc: ``private-members`` option does not work for class attributes 513* #7983: autodoc: Generator type annotation is wrongly rendered in py36 514* #8030: autodoc: An uninitialized annotated instance variable is not documented 515 when ``:inherited-members:`` option given 516* #8032: autodoc: A type hint for the instance variable defined at parent class 517 is not shown in the document of the derived class 518* #8041: autodoc: An annotated instance variable on super class is not 519 documented when derived class has other annotated instance variables 520* #7839: autosummary: cannot handle umlauts in function names 521* #7865: autosummary: Failed to extract summary line when abbreviations found 522* #7866: autosummary: Failed to extract correct summary line when docstring 523 contains a hyperlink target 524* #7469: autosummary: "Module attributes" header is not translatable 525* #7940: apidoc: An extra newline is generated at the end of the rst file if a 526 module has submodules 527* #4258: napoleon: decorated special methods are not shown 528* #7799: napoleon: parameters are not escaped for combined params in numpydoc 529* #7780: napoleon: multiple paramaters declaration in numpydoc was wrongly 530 recognized when napoleon_use_params=True 531* #7715: LaTeX: ``numfig_secnum_depth > 1`` leads to wrong figure links 532* #7846: html theme: XML-invalid files were generated 533* #7894: gettext: Wrong source info is shown when using rst_epilog 534* #7691: linkcheck: HEAD requests are not used for checking 535* #4888: i18n: Failed to add an explicit title to ``:ref:`` role on translation 536* #7928: py domain: failed to resolve a type annotation for the attribute 537* #8008: py domain: failed to parse a type annotation containing ellipsis 538* #7994: std domain: option directive does not generate old node_id compatible 539 with 2.x or older 540* #7968: i18n: The content of ``math`` directive is interpreted as reST on 541 translation 542* #7768: i18n: The ``root`` element for :confval:`figure_language_filename` is 543 not a path that user specifies in the document 544* #7993: texinfo: TypeError is raised for nested object descriptions 545* #7993: texinfo: a warning not supporting desc_signature_line node is shown 546* #7869: :rst:role:`abbr` role without an explanation will show the explanation 547 from the previous abbr role 548* #8048: graphviz: graphviz.css was copied on building non-HTML document 549* C and C++, removed ``noindex`` directive option as it did 550 nothing. 551* #7619: Duplicated node IDs are generated if node has multiple IDs 552* #2050: Symbols sections are appeared twice in the index page 553* #8017: Fix circular import in sphinx.addnodes 554* #7986: CSS: make "highlight" selector more robust 555* #7944: C++, parse non-type template parameters starting with 556 a dependent qualified name. 557* C, don't deepcopy the entire symbol table and make a mess every time an 558 enumerator is handled. 559 560Release 3.1.2 (released Jul 05, 2020) 561===================================== 562 563Incompatible changes 564-------------------- 565 566* #7650: autodoc: the signature of base function will be shown for decorated 567 functions, not a signature of decorator 568 569Bugs fixed 570---------- 571 572* #7844: autodoc: Failed to detect module when relative module name given 573* #7856: autodoc: AttributeError is raised when non-class object is given to 574 the autoclass directive 575* #7850: autodoc: KeyError is raised for invalid mark up when autodoc_typehints 576 is 'description' 577* #7812: autodoc: crashed if the target name matches to both an attribute and 578 module that are same name 579* #7650: autodoc: function signature becomes ``(*args, **kwargs)`` if the 580 function is decorated by generic decorator 581* #7812: autosummary: generates broken stub files if the target code contains 582 an attribute and module that are same name 583* #7806: viewcode: Failed to resolve viewcode references on 3rd party builders 584* #7838: html theme: List items have extra vertical space 585* #7878: html theme: Undesired interaction between "overflow" and "float" 586 587Release 3.1.1 (released Jun 14, 2020) 588===================================== 589 590Incompatible changes 591-------------------- 592 593* #7808: napoleon: a type for attribute are represented as typed field 594 595Features added 596-------------- 597 598* #7807: autodoc: Show detailed warning when type_comment is mismatched with its 599 signature 600 601Bugs fixed 602---------- 603 604* #7808: autodoc: Warnings raised on variable and attribute type annotations 605* #7802: autodoc: EOFError is raised on parallel build 606* #7821: autodoc: TypeError is raised for overloaded C-ext function 607* #7805: autodoc: an object which descriptors returns is unexpectedly documented 608* #7807: autodoc: wrong signature is shown for the function using contextmanager 609* #7812: autosummary: generates broken stub files if the target code contains 610 an attribute and module that are same name 611* #7808: napoleon: Warnings raised on variable and attribute type annotations 612* #7811: sphinx.util.inspect causes circular import problem 613 614Release 3.1.0 (released Jun 08, 2020) 615===================================== 616 617Dependencies 618------------ 619 620* #7746: mathjax: Update to 2.7.5 621 622Incompatible changes 623-------------------- 624 625* #7477: imgconverter: Invoke "magick convert" command by default on Windows 626 627Deprecated 628---------- 629 630* The first argument for sphinx.ext.autosummary.generate.AutosummaryRenderer has 631 been changed to Sphinx object 632* ``sphinx.ext.autosummary.generate.AutosummaryRenderer`` takes an object type 633 as an argument 634* The ``ignore`` argument of ``sphinx.ext.autodoc.Documenter.get_doc()`` 635* The ``template_dir`` argument of ``sphinx.ext.autosummary.generate. 636 AutosummaryRenderer`` 637* The ``module`` argument of ``sphinx.ext.autosummary.generate. 638 find_autosummary_in_docstring()`` 639* The ``builder`` argument of ``sphinx.ext.autosummary.generate. 640 generate_autosummary_docs()`` 641* The ``template_dir`` argument of ``sphinx.ext.autosummary.generate. 642 generate_autosummary_docs()`` 643* The ``ignore`` argument of ``sphinx.util.docstring.prepare_docstring()`` 644* ``sphinx.ext.autosummary.generate.AutosummaryRenderer.exists()`` 645* ``sphinx.util.rpartition()`` 646 647Features added 648-------------- 649 650* LaTeX: Make the ``toplevel_sectioning`` setting optional in LaTeX theme 651* LaTeX: Allow to override papersize and pointsize from LaTeX themes 652* LaTeX: Add :confval:`latex_theme_options` to override theme options 653* #7410: Allow to suppress "circular toctree references detected" warnings using 654 :confval:`suppress_warnings` 655* C, added scope control directives, :rst:dir:`c:namespace`, 656 :rst:dir:`c:namespace-push`, and :rst:dir:`c:namespace-pop`. 657* #2044: autodoc: Suppress default value for instance attributes 658* #7473: autodoc: consider a member public if docstring contains 659 ``:meta public:`` in info-field-list 660* #7487: autodoc: Allow to generate docs for singledispatch functions by 661 py:autofunction 662* #7143: autodoc: Support final classes and methods 663* #7384: autodoc: Support signatures defined by ``__new__()``, metaclasses and 664 builtin base classes 665* #2106: autodoc: Support multiple signatures on docstring 666* #4422: autodoc: Support GenericAlias in Python 3.7 or above 667* #3610: autodoc: Support overloaded functions 668* #7722: autodoc: Support TypeVar 669* #7466: autosummary: headings in generated documents are not translated 670* #7490: autosummary: Add ``:caption:`` option to autosummary directive to set a 671 caption to the toctree 672* #7469: autosummary: Support module attributes 673* #248, #6040: autosummary: Add ``:recursive:`` option to autosummary directive 674 to generate stub files recursively 675* #4030: autosummary: Add :confval:`autosummary_context` to add template 676 variables for custom templates 677* #7530: html: Support nested <kbd> elements 678* #7481: html theme: Add right margin to footnote/citation labels 679* #7482, #7717: html theme: CSS spacing for code blocks with captions and line 680 numbers 681* #7443: html theme: Add new options :confval:`globaltoc_collapse` and 682 :confval:`globaltoc_includehidden` to control the behavior of globaltoc in 683 sidebar 684* #7484: html theme: Avoid clashes between sidebar and other blocks 685* #7476: html theme: Relbar breadcrumb should contain current page 686* #7506: html theme: A canonical URL is not escaped 687* #7533: html theme: Avoid whitespace at the beginning of genindex.html 688* #7541: html theme: Add a "clearer" at the end of the "body" 689* #7542: html theme: Make admonition/topic/sidebar scrollable 690* #7543: html theme: Add top and bottom margins to tables 691* #7695: html theme: Add viewport meta tag for basic theme 692* #7721: html theme: classic: default codetextcolor/codebgcolor doesn't override 693 Pygments 694* C and C++: allow semicolon in the end of declarations. 695* C++, parse parameterized noexcept specifiers. 696* #7294: C++, parse expressions with user-defined literals. 697* C++, parse trailing return types. 698* #7143: py domain: Add ``:final:`` option to :rst:dir:`py:class:`, 699 :rst:dir:`py:exception:` and :rst:dir:`py:method:` directives 700* #7596: py domain: Change a type annotation for variables to a hyperlink 701* #7770: std domain: :rst:dir:`option` directive support arguments in the form 702 of ``foo[=bar]`` 703* #7582: napoleon: a type for attribute are represented like type annotation 704* #7734: napoleon: overescaped trailing underscore on attribute 705* #7247: linkcheck: Add :confval:`linkcheck_request_headers` to send custom HTTP 706 headers for specific host 707* #7792: setuptools: Support ``--verbosity`` option 708* #7683: Add ``allowed_exceptions`` parameter to ``Sphinx.emit()`` to allow 709 handlers to raise specified exceptions 710* #7295: C++, parse (trailing) requires clauses. 711 712Bugs fixed 713---------- 714 715* #6703: autodoc: incremental build does not work for imported objects 716* #7564: autodoc: annotations not to be shown for descriptors 717* #6588: autodoc: Decorated inherited method has no documentation 718* #7469: autodoc: The change of autodoc-process-docstring for variables is 719 cached unexpectedly 720* #7559: autodoc: misdetects a sync function is async 721* #6857: autodoc: failed to detect a classmethod on Enum class 722* #7562: autodoc: a typehint contains spaces is wrongly rendered under 723 autodoc_typehints='description' mode 724* #7551: autodoc: failed to import nested class 725* #7362: autodoc: does not render correct signatures for built-in functions 726* #7654: autodoc: ``Optional[Union[foo, bar]]`` is presented as 727 ``Union[foo, bar, None]`` 728* #7629: autodoc: autofunction emits an unfriendly warning if an invalid object 729 specified 730* #7650: autodoc: undecorated signature is shown for decorated functions 731* #7676: autodoc: typo in the default value of autodoc_member_order 732* #7676: autodoc: wrong value for :member-order: option is ignored silently 733* #7676: autodoc: member-order="bysource" does not work for C module 734* #3673: autodoc: member-order="bysource" does not work for a module having 735 __all__ 736* #7668: autodoc: wrong retann value is passed to a handler of 737 autodoc-proccess-signature 738* #7711: autodoc: fails with ValueError when processing numpy objects 739* #7791: autodoc: TypeError is raised on documenting singledispatch function 740* #7551: autosummary: a nested class is indexed as non-nested class 741* #7661: autosummary: autosummary directive emits warnings twices if failed to 742 import the target module 743* #7685: autosummary: The template variable "members" contains imported members 744 even if :confval:`autossummary_imported_members` is False 745* #7671: autosummary: The location of import failure warning is missing 746* #7535: sphinx-autogen: crashes when custom template uses inheritance 747* #7536: sphinx-autogen: crashes when template uses i18n feature 748* #7781: sphinx-build: Wrong error message when outdir is not directory 749* #7653: sphinx-quickstart: Fix multiple directory creation for nested relpath 750* #2785: html: Bad alignment of equation links 751* #7718: html theme: some themes does not respect background color of Pygments 752 style (agogo, haiku, nature, pyramid, scrolls, sphinxdoc and traditional) 753* #7544: html theme: inconsistent padding in admonitions 754* #7581: napoleon: bad parsing of inline code in attribute docstrings 755* #7628: imgconverter: runs imagemagick once unnecessary for builders not 756 supporting images 757* #7610: incorrectly renders consecutive backslashes for docutils-0.16 758* #7646: handle errors on event handlers 759* #4187: LaTeX: EN DASH disappears from PDF bookmarks in Japanese documents 760* #7701: LaTeX: Anonymous indirect hyperlink target causes duplicated labels 761* #7723: LaTeX: pdflatex crashed when URL contains a single quote 762* #7756: py domain: The default value for positional only argument is not shown 763* #7760: coverage: Add :confval:`coverage_show_missing_items` to show coverage 764 result to console 765* C++, fix rendering and xrefs in nested names explicitly starting 766 in global scope, e.g., ``::A::B``. 767* C, fix rendering and xrefs in nested names explicitly starting 768 in global scope, e.g., ``.A.B``. 769* #7763: C and C++, don't crash during display stringification of unary 770 expressions and fold expressions. 771 772Release 3.0.4 (released May 27, 2020) 773===================================== 774 775Bugs fixed 776---------- 777 778* #7567: autodoc: parametrized types are shown twice for generic types 779* #7637: autodoc: system defined TypeVars are shown in Python 3.9 780* #7696: html: Updated jQuery version from 3.4.1 to 3.5.1 for security reasons 781* #7611: md5 fails when OpenSSL FIPS is enabled 782* #7626: release package does not contain ``CODE_OF_CONDUCT`` 783 784Release 3.0.3 (released Apr 26, 2020) 785===================================== 786 787Features added 788-------------- 789 790* C, parse array declarators with static, qualifiers, and VLA specification. 791 792Bugs fixed 793---------- 794 795* #7516: autodoc: crashes if target object raises an error on accessing 796 its attributes 797 798Release 3.0.2 (released Apr 19, 2020) 799===================================== 800 801Features added 802-------------- 803 804* C, parse attributes and add :confval:`c_id_attributes` 805 and :confval:`c_paren_attributes` to support user-defined attributes. 806 807Bugs fixed 808---------- 809 810* #7461: py domain: fails with IndexError for empty tuple in type annotation 811* #7510: py domain: keyword-only arguments are documented as having a default of 812 None 813* #7418: std domain: :rst:role:`term` role could not match case-insensitively 814* #7461: autodoc: empty tuple in type annotation is not shown correctly 815* #7479: autodoc: Sphinx builds has been slower since 3.0.0 on mocking 816* C++, fix spacing issue in east-const declarations. 817* #7414: LaTeX: Xindy language options were incorrect 818* sphinx crashes with ImportError on python3.5.1 819 820Release 3.0.1 (released Apr 11, 2020) 821===================================== 822 823Incompatible changes 824-------------------- 825 826* #7418: std domain: :rst:dir:`term` role becomes case sensitive 827 828Bugs fixed 829---------- 830 831* #7428: py domain: a reference to class ``None`` emits a nitpicky warning 832* #7445: py domain: a return annotation ``None`` in the function signature is 833 not converted to a hyperlink when using intersphinx 834* #7418: std domain: duplication warning for glossary terms is case insensitive 835* #7438: C++, fix merging overloaded functions in parallel builds. 836* #7422: autodoc: fails with ValueError when using autodoc_mock_imports 837* #7435: autodoc: ``autodoc_typehints='description'`` doesn't suppress typehints 838 in signature for classes/methods 839* #7451: autodoc: fails with AttributeError when an object returns non-string 840 object as a ``__doc__`` member 841* #7423: crashed when giving a non-string object to logger 842* #7479: html theme: Do not include xmlns attribute with HTML 5 doctype 843* #7426: html theme: Escape some links in HTML templates 844 845Release 3.0.0 (released Apr 06, 2020) 846===================================== 847 848Dependencies 849------------ 850 8513.0.0b1 852 853* LaTeX: drop dependency on :program:`extractbb` for image inclusion in 854 Japanese documents as ``.xbb`` files are unneeded by :program:`dvipdfmx` 855 since TeXLive2015 (refs: #6189) 856* babel-2.0 or above is available (Unpinned) 857 858Incompatible changes 859-------------------- 860 8613.0.0b1 862 863* Drop features and APIs deprecated in 1.8.x 864* #247: autosummary: stub files are overwritten automatically by default. see 865 :confval:`autosummary_generate_overwrite` to change the behavior 866* #5923: autodoc: the members of ``object`` class are not documented by default 867 when ``:inherited-members:`` and ``:special-members:`` are given. 868* #6830: py domain: ``meta`` fields in info-field-list becomes reserved. They 869 are not displayed on output document now 870* #6417: py domain: doctree of desc_parameterlist has been changed. The 871 argument names, annotations and default values are wrapped with inline node 872* The structure of ``sphinx.events.EventManager.listeners`` has changed 873* Due to the scoping changes for :rst:dir:`productionlist` some uses of 874 :rst:role:`token` must be modified to include the scope which was previously 875 ignored. 876* #6903: Internal data structure of Python, reST and standard domains have 877 changed. The node_id is added to the index of objects and modules. Now they 878 contains a pair of docname and node_id for cross reference. 879* #7276: C++ domain: Non intended behavior is removed such as ``say_hello_`` 880 links to ``.. cpp:function:: say_hello()`` 881* #7210: js domain: Non intended behavior is removed such as ``parseInt_`` links 882 to ``.. js:function:: parseInt`` 883* #7229: rst domain: Non intended behavior is removed such as ``numref_`` links 884 to ``.. rst:role:: numref`` 885* #6903: py domain: Non intended behavior is removed such as ``say_hello_`` 886 links to ``.. py:function:: say_hello()`` 887* #7246: py domain: Drop special cross reference helper for exceptions, 888 functions and methods 889* The C domain has been rewritten, with additional directives and roles. 890 The existing ones are now more strict, resulting in new warnings. 891* The attribute ``sphinx_cpp_tagname`` in the ``desc_signature_line`` node 892 has been renamed to ``sphinx_line_type``. 893* #6462: double backslashes in domain directives are no longer replaced by 894 single backslashes as default. A new configuration value 895 :confval:`strip_signature_backslash` can be used by users to reenable it. 896 8973.0.0 final 898 899* #7222: ``sphinx.util.inspect.unwrap()`` is renamed to ``unwrap_all()`` 900 901Deprecated 902---------- 903 9043.0.0b1 905 906* ``desc_signature['first']`` 907* ``sphinx.directives.DescDirective`` 908* ``sphinx.domains.std.StandardDomain.add_object()`` 909* ``sphinx.domains.python.PyDecoratorMixin`` 910* ``sphinx.ext.autodoc.get_documenters()`` 911* ``sphinx.ext.autosummary.process_autosummary_toc()`` 912* ``sphinx.parsers.Parser.app`` 913* ``sphinx.testing.path.Path.text()`` 914* ``sphinx.testing.path.Path.bytes()`` 915* ``sphinx.util.inspect.getargspec()`` 916* ``sphinx.writers.latex.LaTeXWriter.format_docclass()`` 917 918Features added 919-------------- 920 9213.0.0b1 922 923* #247: autosummary: Add :confval:`autosummary_generate_overwrite` to overwrite 924 old stub file 925* #5923: autodoc: ``:inherited-members:`` option takes a name of anchestor class 926 not to document inherited members of the class and uppers 927* #6830: autodoc: consider a member private if docstring contains 928 ``:meta private:`` in info-field-list 929* #7165: autodoc: Support Annotated type (PEP-593) 930* #2815: autodoc: Support singledispatch functions and methods 931* #7079: autodoc: :confval:`autodoc_typehints` accepts ``"description"`` 932 configuration. It shows typehints as object description 933* #7314: apidoc: Propagate ``--maxdepth`` option through package documents 934* #6558: glossary: emit a warning for duplicated glossary entry 935* #3106: domain: Register hyperlink target for index page automatically 936* #6558: std domain: emit a warning for duplicated generic objects 937* #6830: py domain: Add new event: :event:`object-description-transform` 938* #6895: py domain: Do not emit nitpicky warnings for built-in types 939* py domain: Support lambda functions in function signature 940* #6417: py domain: Allow to make a style for arguments of functions and methods 941* #7238, #7239: py domain: Emit a warning on describing a python object if the 942 entry is already added as the same name 943* #7341: py domain: type annotations in singature are converted to cross refs 944* Support priority of event handlers. For more detail, see 945 :py:meth:`.Sphinx.connect()` 946* #3077: Implement the scoping for :rst:dir:`productionlist` as indicated 947 in the documentation. 948* #1027: Support backslash line continuation in :rst:dir:`productionlist`. 949* #7108: config: Allow to show an error message from conf.py via ``ConfigError`` 950* #7032: html: :confval:`html_scaled_image_link` will be disabled for images having 951 ``no-scaled-link`` class 952* #7144: Add CSS class indicating its domain for each desc node 953* #7211: latex: Use babel for Chinese document when using XeLaTeX 954* #6672: LaTeX: Support LaTeX Theming (experimental) 955* #7005: LaTeX: Add LaTeX styling macro for :rst:role:`kbd` role 956* #7220: genindex: Show "main" index entries at first 957* #7103: linkcheck: writes all links to ``output.json`` 958* #7025: html search: full text search can be disabled for individual document 959 using ``:nosearch:`` file-wide metadata 960* #7293: html search: Allow to override JavaScript splitter via 961 ``SearchLanguage.js_splitter_code`` 962* #7142: html theme: Add a theme option: ``pygments_dark_style`` to switch the 963 style of code-blocks in dark mode 964* The C domain has been rewritten adding for example: 965 966 - Cross-referencing respecting the current scope. 967 - Possible to document anonymous entities. 968 - More specific directives and roles for each type of entitiy, 969 e.g., handling scoping of enumerators. 970 - New role :rst:role:`c:expr` for rendering expressions and types 971 in text. 972 973* Added ``SphinxDirective.get_source_info()`` 974 and ``SphinxRole.get_source_info()``. 975* #7324: sphinx-build: Emit a warning if multiple files having different file 976 extensions for same document found 977 9783.0.0 final 979 980* Added ``ObjectDescription.transform_content()``. 981 982Bugs fixed 983---------- 984 9853.0.0b1 986 987* C++, fix cross reference lookup in certain cases involving 988 function overloads. 989* #5078: C++, fix cross reference lookup when a directive contains multiple 990 declarations. 991* C++, suppress warnings for directly dependent typenames in cross references 992 generated automatically in signatures. 993* #5637: autodoc: Incorrect handling of nested class names on show-inheritance 994* #7267: autodoc: error message for invalid directive options has wrong location 995* #7329: autodoc: info-field-list is wrongly generated from type hints into the 996 class description even if ``autoclass_content='class'`` set 997* #7331: autodoc: a cython-function is not recognized as a function 998* #5637: inheritance_diagram: Incorrect handling of nested class names 999* #7139: ``code-block:: guess`` does not work 1000* #7325: html: source_suffix containing dot leads to wrong source link 1001* #7357: html: Resizing SVG image fails with ValueError 1002* #7278: html search: Fix use of ``html_file_suffix`` instead of 1003 ``html_link_suffix`` in search results 1004* #7297: html theme: ``bizstyle`` does not support ``sidebarwidth`` 1005* #3842: singlehtml: Path to images broken when master doc is not in source root 1006* #7179: std domain: Fix whitespaces are suppressed on referring GenericObject 1007* #7289: console: use bright colors instead of bold 1008* #1539: C, parse array types. 1009* #2377: C, parse function pointers even in complex types. 1010* #7345: sphinx-build: Sphinx crashes if output directory exists as a file 1011* #7290: sphinx-build: Ignore bdb.BdbQuit when handling exceptions 1012* #6240: napoleon: Attributes and Methods sections ignore :noindex: option 1013 10143.0.0 final 1015 1016* #7364: autosummary: crashed when :confval:`autosummary_generate` is False 1017* #7370: autosummary: raises UnboundLocalError when unknown module given 1018* #7367: C++, alternate operator spellings are now supported. 1019* C, alternate operator spellings are now supported. 1020* #7368: C++, comma operator in expressions, pack expansion in template 1021 argument lists, and more comprehensive error messages in some cases. 1022* C, C++, fix crash and wrong duplicate warnings related to anon symbols. 1023* #6477: Escape first "!" in a cross reference linking no longer possible 1024* #7219: py domain: The index entry generated by ``py:function`` directive is 1025 different with one from ``index`` directive with "builtin" type 1026* #7301: capital characters are not allowed for node_id 1027* #7301: epub: duplicated node_ids are generated 1028* #6564: html: a width of table was ignored on HTML builder 1029* #7401: Incorrect argument is passed for :event:`env-get-outdated` handlers 1030* #7355: autodoc: a signature of cython-function is not recognized well 1031* #7222: autodoc: ``__wrapped__`` functions are not documented correctly 1032* #7409: intersphinx: ValueError is raised when an extension sets up 1033 :confval:`intersphinx_mapping` on :event:`config-inited` event 1034* #7343: Sphinx builds has been slower since 2.4.0 on debug mode 1035 1036Release 2.4.4 (released Mar 05, 2020) 1037===================================== 1038 1039Bugs fixed 1040---------- 1041 1042* #7197: LaTeX: platex cause error to build image directive with target url 1043* #7223: Sphinx builds has been slower since 2.4.0 1044 1045Release 2.4.3 (released Feb 22, 2020) 1046===================================== 1047 1048Bugs fixed 1049---------- 1050 1051* #7184: autodoc: ``*args`` and ``**kwarg`` in type comments are not handled 1052 properly 1053* #7189: autodoc: classmethod coroutines are not detected 1054* #7183: intersphinx: ``:attr:`` reference to property is broken 1055* #6244, #6387: html search: Search breaks/hangs when built with dirhtml builder 1056* #7195: todo: emit doctree-resolved event with non-document node incorrectly 1057 1058Release 2.4.2 (released Feb 19, 2020) 1059===================================== 1060 1061Bugs fixed 1062---------- 1063 1064* #7138: autodoc: ``autodoc.typehints`` crashed when variable has unbound object 1065 as a value 1066* #7156: autodoc: separator for keyword only arguments is not shown 1067* #7146: autodoc: IndexError is raised on suppressed type_comment found 1068* #7161: autodoc: typehints extension does not support parallel build 1069* #7178: autodoc: TypeError is raised on fetching type annotations 1070* #7151: crashed when extension assigns a value to ``env.indexentries`` 1071* #7170: text: Remove debug print 1072* #7137: viewcode: Avoid to crash when non-python code given 1073 1074Release 2.4.1 (released Feb 11, 2020) 1075===================================== 1076 1077Bugs fixed 1078---------- 1079 1080* #7120: html: crashed when on scaling SVG images which have float dimensions 1081* #7126: autodoc: TypeError: 'getset_descriptor' object is not iterable 1082 1083Release 2.4.0 (released Feb 09, 2020) 1084===================================== 1085 1086Deprecated 1087---------- 1088 1089* The ``decode`` argument of ``sphinx.pycode.ModuleAnalyzer()`` 1090* ``sphinx.directives.other.Index`` 1091* ``sphinx.environment.temp_data['gloss_entries']`` 1092* ``sphinx.environment.BuildEnvironment.indexentries`` 1093* ``sphinx.environment.collectors.indexentries.IndexEntriesCollector`` 1094* ``sphinx.ext.apidoc.INITPY`` 1095* ``sphinx.ext.apidoc.shall_skip()`` 1096* ``sphinx.io.FiletypeNotFoundError`` 1097* ``sphinx.io.get_filetype()`` 1098* ``sphinx.pycode.ModuleAnalyzer.encoding`` 1099* ``sphinx.roles.Index`` 1100* ``sphinx.util.detect_encoding()`` 1101* ``sphinx.util.get_module_source()`` 1102* ``sphinx.util.inspect.Signature`` 1103* ``sphinx.util.inspect.safe_getmembers()`` 1104* ``sphinx.writers.latex.LaTeXTranslator.settings.author`` 1105* ``sphinx.writers.latex.LaTeXTranslator.settings.contentsname`` 1106* ``sphinx.writers.latex.LaTeXTranslator.settings.docclass`` 1107* ``sphinx.writers.latex.LaTeXTranslator.settings.docname`` 1108* ``sphinx.writers.latex.LaTeXTranslator.settings.title`` 1109* ``sphinx.writers.latex.ADDITIONAL_SETTINGS`` 1110* ``sphinx.writers.latex.DEFAULT_SETTINGS`` 1111* ``sphinx.writers.latex.LUALATEX_DEFAULT_FONTPKG`` 1112* ``sphinx.writers.latex.PDFLATEX_DEFAULT_FONTPKG`` 1113* ``sphinx.writers.latex.XELATEX_DEFAULT_FONTPKG`` 1114* ``sphinx.writers.latex.XELATEX_GREEK_DEFAULT_FONTPKG`` 1115 1116Features added 1117-------------- 1118 1119* #6910: inheritance_diagram: Make the background of diagrams transparent 1120* #6446: duration: Add ``sphinx.ext.durations`` to inspect which documents slow 1121 down the build 1122* #6837: LaTeX: Support a nested table 1123* #7115: LaTeX: Allow to override LATEXOPTS and LATEXMKOPTS via environment 1124 variable 1125* #6966: graphviz: Support ``:class:`` option 1126* #6696: html: ``:scale:`` option of image/figure directive not working for SVG 1127 images (imagesize-1.2.0 or above is required) 1128* #6994: imgconverter: Support illustrator file (.ai) to .png conversion 1129* autodoc: Support Positional-Only Argument separator (PEP-570 compliant) 1130* autodoc: Support type annotations for variables 1131* #2755: autodoc: Add new event: :event:`autodoc-before-process-signature` 1132* #2755: autodoc: Support type_comment style (ex. ``# type: (str) -> str``) 1133 annotation (python3.8+ or `typed_ast <https://github.com/python/typed_ast>`_ 1134 is required) 1135* #7051: autodoc: Support instance variables without defaults (PEP-526) 1136* #6418: autodoc: Add a new extension ``sphinx.ext.autodoc.typehints``. It shows 1137 typehints as object description if ``autodoc_typehints = "description"`` set. 1138 This is an experimental extension and it will be integrated into autodoc core 1139 in Sphinx-3.0 1140* SphinxTranslator now calls visitor/departure method for super node class if 1141 visitor/departure method for original node class not found 1142* #6418: Add new event: :event:`object-description-transform` 1143* py domain: :rst:dir:`py:data` and :rst:dir:`py:attribute` take new options 1144 named ``:type:`` and ``:value:`` to describe its type and initial value 1145* #6785: py domain: ``:py:attr:`` is able to refer properties again 1146* #6772: apidoc: Add ``-q`` option for quiet mode 1147 1148Bugs fixed 1149---------- 1150 1151* #6925: html: Remove redundant type="text/javascript" from <script> elements 1152* #7112: html: SVG image is not layouted as float even if aligned 1153* #6906, #6907: autodoc: failed to read the source codes encoeded in cp1251 1154* #6961: latex: warning for babel shown twice 1155* #7059: latex: LaTeX compilation falls into infinite loop (wrapfig issue) 1156* #6581: latex: ``:reversed:`` option for toctree does not effect to LaTeX build 1157* #6559: Wrong node-ids are generated in glossary directive 1158* #6986: apidoc: misdetects module name for .so file inside module 1159* #6899: apidoc: private members are not shown even if ``--private`` given 1160* #6327: apidoc: Support a python package consisted of __init__.so file 1161* #6999: napoleon: fails to parse tilde in :exc: role 1162* #7019: gettext: Absolute path used in message catalogs 1163* #7023: autodoc: nested partial functions are not listed 1164* #7023: autodoc: partial functions imported from other modules are listed as 1165 module members without :impoprted-members: option 1166* #6889: autodoc: Trailing comma in ``:members::`` option causes cryptic warning 1167* #6568: autosummary: ``autosummary_imported_members`` is ignored on generating 1168 a stub file for submodule 1169* #7055: linkcheck: redirect is treated as an error 1170* #7088: HTML template: If ``navigation_with_keys`` option is activated, 1171 modifier keys are ignored, which means the feature can interfere with browser 1172 features 1173* #7090: std domain: Can't assign numfig-numbers for custom container nodes 1174* #7106: std domain: enumerated nodes are marked as duplicated when extensions 1175 call ``note_explicit_target()`` 1176* #7095: dirhtml: Cross references are broken via intersphinx and ``:doc:`` role 1177* C++: 1178 1179 - Don't crash when using the ``struct`` role in some cases. 1180 - Don't warn when using the ``var``/``member`` role for function 1181 parameters. 1182 - Render call and braced-init expressions correctly. 1183* #7097: Filenames of images generated by 1184 ``sphinx.transforms.post_transforms.images.ImageConverter`` 1185 or its subclasses (used for latex build) are now sanitized, 1186 to prevent broken paths 1187 1188Release 2.3.1 (released Dec 22, 2019) 1189===================================== 1190 1191Bugs fixed 1192---------- 1193 1194* #6936: sphinx-autogen: raises AttributeError 1195 1196Release 2.3.0 (released Dec 15, 2019) 1197===================================== 1198 1199Incompatible changes 1200-------------------- 1201 1202* #6742: ``end-before`` option of :rst:dir:`literalinclude` directive does not 1203 match the first line of the code block. 1204* #1331: Change default User-Agent header to ``"Sphinx/X.Y.Z requests/X.Y.Z 1205 python/X.Y.Z"``. It can be changed via :confval:`user_agent`. 1206* #6867: text: content of admonitions starts after a blank line 1207 1208Deprecated 1209---------- 1210 1211* ``sphinx.builders.gettext.POHEADER`` 1212* ``sphinx.io.SphinxStandaloneReader.app`` 1213* ``sphinx.io.SphinxStandaloneReader.env`` 1214* ``sphinx.util.texescape.tex_escape_map`` 1215* ``sphinx.util.texescape.tex_hl_escape_map_new`` 1216* ``sphinx.writers.latex.LaTeXTranslator.no_contractions`` 1217 1218Features added 1219-------------- 1220 1221* #6707: C++, support bit-fields. 1222* #267: html: Eliminate prompt characters of doctest block from copyable text 1223* #6548: html: Use favicon for OpenSearch if available 1224* #6729: html theme: agogo theme now supports ``rightsidebar`` option 1225* #6780: Add PEP-561 Support 1226* #6762: latex: Allow to load additional LaTeX packages via ``extrapackages`` key 1227 of :confval:`latex_elements` 1228* #1331: Add new config variable: :confval:`user_agent` 1229* #6000: LaTeX: have backslash also be an inline literal word wrap break 1230 character 1231* #4186: LaTeX: Support upLaTeX as a new :confval:`latex_engine` (experimental) 1232* #6812: Improve a warning message when extensions are not parallel safe 1233* #6818: Improve Intersphinx performance for multiple remote inventories. 1234* #2546: apidoc: .so file support 1235* #6798: autosummary: emit ``autodoc-skip-member`` event on generating stub file 1236* #6483: i18n: make explicit titles in toctree translatable 1237* #6816: linkcheck: Add :confval:`linkcheck_auth` option to provide 1238 authentication information when doing ``linkcheck`` builds 1239* #6872: linkcheck: Handles HTTP 308 Permanent Redirect 1240* #6613: html: Wrap section number in span tag 1241* #6781: gettext: Add :confval:`gettext_last_translator' and 1242 :confval:`gettext_language_team` to customize headers of POT file 1243 1244Bugs fixed 1245---------- 1246 1247* #6668: LaTeX: Longtable before header has incorrect distance 1248 (refs: `latex3/latex2e#173`_) 1249 1250 .. _latex3/latex2e#173: https://github.com/latex3/latex2e/issues/173 1251* #6618: LaTeX: Avoid section names at the end of a page 1252* #6738: LaTeX: Do not replace unicode characters by LaTeX macros on unicode 1253 supported LaTeX engines: ¶, §, €, ∞, ±, →, ‣, –, superscript and subscript 1254 digits go through "as is" (as default OpenType font supports them) 1255* #6704: linkcheck: Be defensive and handle newly defined HTTP error code 1256* #6806: linkcheck: Failure on parsing content 1257* #6655: image URLs containing ``data:`` causes gettext builder crashed 1258* #6584: i18n: Error when compiling message catalogs on Hindi 1259* #6718: i18n: KeyError is raised if section title and table title are same 1260* #6743: i18n: :confval:`rst_prolog` breaks the translation 1261* #6708: mathbase: Some deprecated functions have removed 1262* #6709: autodoc: mock object does not work as a class decorator 1263* #5070: epub: Wrong internal href fragment links 1264* #6712: Allow not to install sphinx.testing as runtime (mainly for ALT Linux) 1265* #6741: html: search result was broken with empty :confval:`html_file_suffix` 1266* #6001: LaTeX does not wrap long code lines at backslash character 1267* #6804: LaTeX: PDF build breaks if admonition of danger type contains 1268 code-block long enough not to fit on one page 1269* #6809: LaTeX: code-block in a danger type admonition can easily spill over 1270 bottom of page 1271* #6793: texinfo: Code examples broken following "sidebar" 1272* #6813: An orphan warning is emitted for included document on Windows. Thanks 1273 to @drillan 1274* #6850: Fix smartypants module calls re.sub() with wrong options 1275* #6824: HTML search: If a search term is partially matched in the title and 1276 fully matched in a text paragraph on the same page, the search does not 1277 include this match. 1278* #6848: config.py shouldn't pop extensions from overrides 1279* #6867: text: extra spaces are inserted to hyphenated words on folding lines 1280* #6886: LaTeX: xelatex converts straight double quotes into right curly ones 1281 (shows when :confval:`smartquotes` is ``False``) 1282* #6890: LaTeX: even with smartquotes off, PDF output transforms straight 1283 quotes and consecutive hyphens into curly quotes and dashes 1284* #6876: LaTeX: multi-line display of authors on title page has ragged edges 1285* #6887: Sphinx crashes with docutils-0.16b0 1286* #6920: sphinx-build: A console message is wrongly highlighted 1287* #6900: sphinx-build: ``-D`` option does not considers ``0`` and ``1`` as a 1288 boolean value 1289 1290Release 2.2.2 (released Dec 03, 2019) 1291===================================== 1292 1293Incompatible changes 1294-------------------- 1295 1296* #6803: For security reason of python, parallel mode is disabled on macOS and 1297 Python3.8+ 1298 1299Bugs fixed 1300---------- 1301 1302* #6776: LaTeX: 2019-10-01 LaTeX release breaks :file:`sphinxcyrillic.sty` 1303* #6815: i18n: French, Hindi, Chinese, Japanese and Korean translation messages 1304 has been broken 1305* #6803: parallel build causes AttributeError on macOS and Python3.8 1306 1307Release 2.2.1 (released Oct 26, 2019) 1308===================================== 1309 1310Bugs fixed 1311---------- 1312 1313* #6641: LaTeX: Undefined control sequence ``\sphinxmaketitle`` 1314* #6710: LaTeX not well configured for Greek language as main language 1315* #6759: validation of html static paths and extra paths no longer throws 1316 an error if the paths are in different directories 1317 1318Release 2.2.0 (released Aug 19, 2019) 1319===================================== 1320 1321Incompatible changes 1322-------------------- 1323 1324* apidoc: template files are renamed to ``.rst_t`` 1325* html: Field lists will be styled by grid layout 1326 1327Deprecated 1328---------- 1329 1330* ``sphinx.domains.math.MathDomain.add_equation()`` 1331* ``sphinx.domains.math.MathDomain.get_next_equation_number()`` 1332* The ``info`` and ``warn`` arguments of 1333 ``sphinx.ext.autosummary.generate.generate_autosummary_docs()`` 1334* ``sphinx.ext.autosummary.generate._simple_info()`` 1335* ``sphinx.ext.autosummary.generate._simple_warn()`` 1336* ``sphinx.ext.todo.merge_info()`` 1337* ``sphinx.ext.todo.process_todo_nodes()`` 1338* ``sphinx.ext.todo.process_todos()`` 1339* ``sphinx.ext.todo.purge_todos()`` 1340 1341Features added 1342-------------- 1343 1344* #5124: graphviz: ``:graphviz_dot:`` option is renamed to ``:layout:`` 1345* #1464: html: emit a warning if :confval:`html_static_path` and 1346 :confval:`html_extra_path` directories are inside output directory 1347* #6514: html: Add a label to search input for accessability purposes 1348* #5602: apidoc: Add ``--templatedir`` option 1349* #6475: Add ``override`` argument to ``app.add_autodocumenter()`` 1350* #6310: imgmath: let :confval:`imgmath_use_preview` work also with the SVG 1351 format for images rendering inline math 1352* #6533: LaTeX: refactor visit_enumerated_list() to use ``\sphinxsetlistlabels`` 1353* #6628: quickstart: Use ``https://docs.python.org/3/`` for default setting of 1354 :confval:`intersphinx_mapping` 1355* #6419: sphinx-build: give reasons why rebuilded 1356 1357Bugs fixed 1358---------- 1359 1360* py domain: duplicated warning does not point the location of source code 1361* #6499: html: Sphinx never updates a copy of :confval:`html_logo` even if 1362 original file has changed 1363* #1125: html theme: scrollbar is hard to see on classic theme and macOS 1364* #5502: linkcheck: Consider HTTP 503 response as not an error 1365* #6439: Make generated download links reproducible 1366* #6486: UnboundLocalError is raised if broken extension installed 1367* #6567: autodoc: :confval:`autodoc_inherit_docstrings` does not effect to 1368 ``__init__()`` and ``__new__()`` 1369* #6574: autodoc: :confval:`autodoc_member_order` does not refer order of 1370 imports when ``'bysource'`` order 1371* #6574: autodoc: missing type annotation for variadic and keyword parameters 1372* #6589: autodoc: Formatting issues with autodoc_typehints='none' 1373* #6605: autodoc: crashed when target code contains custom method-like objects 1374* #6498: autosummary: crashed with wrong autosummary_generate setting 1375* #6507: autosummary: crashes without no autosummary_generate setting 1376* #6511: LaTeX: autonumbered list can not be customized in LaTeX 1377 since Sphinx 1.8.0 (refs: #6533) 1378* #6531: Failed to load last environment object when extension added 1379* #736: Invalid sort in pair index 1380* #6527: :confval:`last_updated` wrongly assumes timezone as UTC 1381* #5592: std domain: :rst:dir:`option` directive registers an index entry for 1382 each comma separated option 1383* #6549: sphinx-build: Escaped characters in error messages 1384* #6545: doctest comments not getting trimmed since Sphinx 1.8.0 1385* #6561: glossary: Wrong hyperlinks are generated for non alphanumeric terms 1386* #6620: i18n: classifiers of definition list are not translated with 1387 docutils-0.15 1388* #6474: ``DocFieldTransformer`` raises AttributeError when given directive is 1389 not a subclass of ObjectDescription 1390 1391Release 2.1.2 (released Jun 19, 2019) 1392===================================== 1393 1394Bugs fixed 1395---------- 1396 1397* #6497: custom lexers fails highlighting when syntax error 1398* #6478, #6488: info field lists are incorrectly recognized 1399 1400Release 2.1.1 (released Jun 10, 2019) 1401===================================== 1402 1403Incompatible changes 1404-------------------- 1405 1406* #6447: autodoc: Stop to generate document for undocumented module variables 1407 1408Bugs fixed 1409---------- 1410 1411* #6442: LaTeX: admonitions of :rst:dir:`note` type can get separated from 1412 immediately preceding section title by pagebreak 1413* #6448: autodoc: crashed when autodocumenting classes with ``__slots__ = None`` 1414* #6451: autodoc: generates docs for "optional import"ed modules as variables 1415* #6452: autosummary: crashed when generating document of properties 1416* #6455: napoleon: docstrings for properties are not processed 1417* #6436: napoleon: "Unknown target name" error if variable name ends with 1418 underscore 1419* #6440: apidoc: missing blank lines between modules 1420 1421Release 2.1.0 (released Jun 02, 2019) 1422===================================== 1423 1424Incompatible changes 1425-------------------- 1426 1427* Ignore filenames without file extension given to ``Builder.build_specific()`` 1428 API directly 1429* #6230: The anchor of term in glossary directive is changed if it is consisted 1430 by non-ASCII characters 1431* #4550: html: Centering tables by default using CSS 1432* #6239: latex: xelatex and xeCJK are used for Chinese documents by default 1433* ``Sphinx.add_lexer()`` now takes a Lexer class instead of instance. An 1434 instance of lexers are still supported until Sphinx-3.x. 1435 1436Deprecated 1437---------- 1438 1439* ``sphinx.builders.latex.LaTeXBuilder.apply_transforms()`` 1440* ``sphinx.builders._epub_base.EpubBuilder.esc()`` 1441* ``sphinx.directives.Acks`` 1442* ``sphinx.directives.Author`` 1443* ``sphinx.directives.Centered`` 1444* ``sphinx.directives.Class`` 1445* ``sphinx.directives.CodeBlock`` 1446* ``sphinx.directives.Figure`` 1447* ``sphinx.directives.HList`` 1448* ``sphinx.directives.Highlight`` 1449* ``sphinx.directives.Include`` 1450* ``sphinx.directives.Index`` 1451* ``sphinx.directives.LiteralInclude`` 1452* ``sphinx.directives.Meta`` 1453* ``sphinx.directives.Only`` 1454* ``sphinx.directives.SeeAlso`` 1455* ``sphinx.directives.TabularColumns`` 1456* ``sphinx.directives.TocTree`` 1457* ``sphinx.directives.VersionChange`` 1458* ``sphinx.domains.python.PyClassmember`` 1459* ``sphinx.domains.python.PyModulelevel`` 1460* ``sphinx.domains.std.StandardDomain._resolve_citation_xref()`` 1461* ``sphinx.domains.std.StandardDomain.note_citations()`` 1462* ``sphinx.domains.std.StandardDomain.note_citation_refs()`` 1463* ``sphinx.domains.std.StandardDomain.note_labels()`` 1464* ``sphinx.environment.NoUri`` 1465* ``sphinx.ext.apidoc.format_directive()`` 1466* ``sphinx.ext.apidoc.format_heading()`` 1467* ``sphinx.ext.apidoc.makename()`` 1468* ``sphinx.ext.autodoc.importer.MockFinder`` 1469* ``sphinx.ext.autodoc.importer.MockLoader`` 1470* ``sphinx.ext.autodoc.importer.mock()`` 1471* ``sphinx.ext.autosummary.autolink_role()`` 1472* ``sphinx.ext.imgmath.DOC_BODY`` 1473* ``sphinx.ext.imgmath.DOC_BODY_PREVIEW`` 1474* ``sphinx.ext.imgmath.DOC_HEAD`` 1475* ``sphinx.transforms.CitationReferences`` 1476* ``sphinx.transforms.SmartQuotesSkipper`` 1477* ``sphinx.util.docfields.DocFieldTransformer.preprocess_fieldtypes()`` 1478* ``sphinx.util.node.find_source_node()`` 1479* ``sphinx.util.i18n.find_catalog()`` 1480* ``sphinx.util.i18n.find_catalog_files()`` 1481* ``sphinx.util.i18n.find_catalog_source_files()`` 1482 1483For more details, see :ref:`deprecation APIs list <dev-deprecated-apis>`. 1484 1485Features added 1486-------------- 1487 1488* Add a helper class ``sphinx.transforms.post_transforms.SphinxPostTransform`` 1489* Add helper methods 1490 1491 - ``PythonDomain.note_module()`` 1492 - ``PythonDomain.note_object()`` 1493 - ``SphinxDirective.set_source_info()`` 1494 1495* #6180: Support ``--keep-going`` with BuildDoc setup command 1496* ``math`` directive now supports ``:class:`` option 1497* todo: ``todo`` directive now supports ``:name:`` option 1498* Enable override via environment of ``SPHINXOPTS`` and ``SPHINXBUILD`` Makefile 1499 variables (refs: #6232, #6303) 1500* #6287: autodoc: Unable to document bound instance methods exported as module 1501 functions 1502* #6289: autodoc: :confval:`autodoc_default_options` now supports 1503 ``imported-members`` option 1504* #4777: autodoc: Support coroutine 1505* #744: autodoc: Support abstractmethod 1506* #6325: autodoc: Support attributes in __slots__. For dict-style __slots__, 1507 autodoc considers values as a docstring of the attribute 1508* #6361: autodoc: Add :confval:`autodoc_typehints` to suppress typehints from 1509 signature 1510* #1063: autodoc: ``automodule`` directive now handles undocumented module level 1511 variables 1512* #6212 autosummary: Add :confval:`autosummary_imported_members` to display 1513 imported members on autosummary 1514* #6271: ``make clean`` is catastrophically broken if building into '.' 1515* #6363: Support ``%O%`` environment variable in make.bat 1516* #4777: py domain: Add ``:async:`` option to :rst:dir:`py:function` directive 1517* py domain: Add new options to :rst:dir:`py:method` directive 1518 1519 - ``:abstractmethod:`` 1520 - ``:async:`` 1521 - ``:classmethod:`` 1522 - ``:property:`` 1523 - ``:staticmethod:`` 1524 1525* rst domain: Add :rst:dir:`directive:option` directive to describe the option 1526 for directive 1527* #6306: html: Add a label to search form for accessability purposes 1528* #4390: html: Consistent and semantic CSS for signatures 1529* #6358: The ``rawsource`` property of ``production`` nodes now contains the 1530 full production rule 1531* #6373: autosectionlabel: Allow suppression of warnings 1532* coverage: Support a new ``coverage_ignore_pyobjects`` option 1533* #6239: latex: Support to build Chinese documents 1534 1535Bugs fixed 1536---------- 1537 1538* #6230: Inappropriate node_id has been generated by glossary directive if term 1539 is consisted by non-ASCII characters 1540* #6213: ifconfig: contents after headings are not shown 1541* commented term in glossary directive is wrongly recognized 1542* #6299: rst domain: rst:directive directive generates waste space 1543* #6379: py domain: Module index (py-modindex.html) has duplicate titles 1544* #6331: man: invalid output when doctest follows rubric 1545* #6351: "Hyperlink target is not referenced" message is shown even if 1546 referenced 1547* #6165: autodoc: ``tab_width`` setting of docutils has been ignored 1548* #6347: autodoc: crashes with a plain Tuple on Python 3.6 and 3.5 1549* #6311: autosummary: autosummary table gets confused by complex type hints 1550* #6350: autosummary: confused by an argument having some kind of default value 1551* Generated Makefiles lack a final EOL (refs: #6232) 1552* #6375: extlinks: Cannot escape angle brackets in link caption 1553* #6378: linkcheck: Send commonly used User-Agent 1554* #6387: html search: failed to search document with haiku and scrolls themes 1555* #6408: html search: Fix the ranking of search results 1556* #6406: Wrong year is returned for ``SOURCE_DATE_EPOCH`` 1557* #6402: image directive crashes by unknown image format 1558* #6286: C++, allow 8 and 9 in hexadecimal integer literals. 1559* #6305: Fix the string in quickstart for 'path' argument of parser 1560* LaTeX: Figures in admonitions produced errors (refs: #6364) 1561 1562Release 2.0.1 (released Apr 08, 2019) 1563===================================== 1564 1565Bugs fixed 1566---------- 1567 1568* LaTeX: some system labels are not translated 1569* RemovedInSphinx30Warning is marked as pending 1570* deprecation warnings are not emitted 1571 1572 - sphinx.application.CONFIG_FILENAME 1573 - sphinx.builders.htmlhelp 1574 - :confval:`viewcode_import` 1575 1576* #6208: C++, properly parse full xrefs that happen to have a short xref as 1577 prefix 1578* #6220, #6225: napoleon: AttributeError is raised for raised section having 1579 references 1580* #6245: circular import error on importing SerializingHTMLBuilder 1581* #6243: LaTeX: 'releasename' setting for latex_elements is ignored 1582* #6244: html: Search function is broken with 3rd party themes 1583* #6263: html: HTML5Translator crashed with invalid field node 1584* #6262: html theme: The style of field lists has changed in bizstyle theme 1585 1586Release 2.0.0 (released Mar 29, 2019) 1587===================================== 1588 1589Dependencies 1590------------ 1591 15922.0.0b1 1593 1594* LaTeX builder now depends on TeX Live 2015 or above. 1595* LaTeX builder (with ``'pdflatex'`` :confval:`latex_engine`) will process 1596 Unicode Greek letters in text (not in math mark-up) via the text font and 1597 will not escape them to math mark-up. See the discussion of the 1598 ``'fontenc'`` key of :confval:`latex_elements`; such (optional) support for 1599 Greek adds, for example on Ubuntu xenial, the ``texlive-lang-greek`` and (if 1600 default font set-up is not modified) ``cm-super(-minimal)`` as additional 1601 Sphinx LaTeX requirements. 1602* LaTeX builder with :confval:`latex_engine` set to ``'xelatex'`` or to 1603 ``'lualatex'`` requires (by default) the ``FreeFont`` fonts, 1604 which in Ubuntu xenial are provided by package ``fonts-freefont-otf``, and 1605 e.g. in Fedora 29 via package ``texlive-gnu-freefont``. 1606* requests 2.5.0 or above 1607* The six package is no longer a dependency 1608* The sphinxcontrib-websupport package is no longer a dependency 1609* Some packages are separated to sub packages: 1610 1611 - sphinxcontrib.applehelp 1612 - sphinxcontrib.devhelp 1613 - sphinxcontrib.htmlhelp 1614 - sphinxcontrib.jsmath 1615 - sphinxcontrib.serializinghtml 1616 - sphinxcontrib.qthelp 1617 1618Incompatible changes 1619-------------------- 1620 16212.0.0b1 1622 1623* Drop python 2.7 and 3.4 support 1624* Drop docutils 0.11 support 1625* Drop features and APIs deprecated in 1.7.x 1626* The default setting for :confval:`master_doc` is changed to ``'index'`` which 1627 has been longly used as default of sphinx-quickstart. 1628* LaTeX: Move message resources to ``sphinxmessage.sty`` 1629* LaTeX: Stop using ``\captions<lang>`` macro for some labels 1630* LaTeX: for ``'xelatex'`` and ``'lualatex'``, use the ``FreeFont`` OpenType 1631 fonts as default choice (refs: #5645) 1632* LaTeX: ``'xelatex'`` and ``'lualatex'`` now use ``\small`` in code-blocks 1633 (due to ``FreeMono`` character width) like ``'pdflatex'`` already did (due 1634 to ``Courier`` character width). You may need to adjust this via 1635 :confval:`latex_elements` ``'fvset'`` key, in case of usage of some other 1636 OpenType fonts (refs: #5768) 1637* LaTeX: Greek letters in text are not escaped to math mode mark-up, and they 1638 will use the text font not the math font. The ``LGR`` font encoding must be 1639 added to the ``'fontenc'`` key of :confval:`latex_elements` for this to work 1640 (only if it is needed by the document, of course). 1641* LaTeX: setting the :confval:`language` to ``'en'`` triggered ``Sonny`` option 1642 of ``fncychap``, now it is ``Bjarne`` to match case of no language specified. 1643 (refs: #5772) 1644* #5770: doctest: Follow :confval:`highlight_language` on highlighting doctest 1645 block. As a result, they are highlighted as python3 by default. 1646* The order of argument for ``HTMLTranslator``, ``HTML5Translator`` and 1647 ``ManualPageTranslator`` are changed 1648* LaTeX: hard-coded redefinitions of ``\l@section`` and ``\l@subsection`` 1649 formerly done during loading of ``'manual'`` docclass get executed later, at 1650 time of ``\sphinxtableofcontents``. This means that custom user definitions 1651 from LaTeX preamble now get overwritten. Use ``\sphinxtableofcontentshook`` 1652 to insert custom user definitions. See :ref:`latex-macros`. 1653* quickstart: Simplify generated ``conf.py`` 1654* #4148: quickstart: some questions are removed. They are still able to specify 1655 via command line options 1656* websupport: unbundled from sphinx core. Please use sphinxcontrib-websupport 1657* C++, the visibility of base classes is now always rendered as present in the 1658 input. That is, ``private`` is now shown, where it was ellided before. 1659* LaTeX: graphics inclusion of oversized images rescales to not exceed 1660 the text width and height, even if width and/or height option were used. 1661 (refs: #5956) 1662* epub: ``epub_title`` defaults to the :confval:`project` option 1663* #4550: All tables and figures without ``align`` option are displayed to center 1664* #4587: html: Output HTML5 by default 1665 16662.0.0b2 1667 1668* texinfo: image files are copied into ``name-figure`` directory 1669 1670Deprecated 1671---------- 1672 16732.0.0b1 1674 1675* Support for evaluating Python 2 syntax is deprecated. This includes 1676 configuration files which should be converted to Python 3. 1677* The arguments of ``EpubBuilder.build_mimetype()``, 1678 ``EpubBuilder.build_container()``, ``EpubBuilder.bulid_content()``, 1679 ``EpubBuilder.build_toc()`` and ``EpubBuilder.build_epub()`` 1680* The arguments of ``Epub3Builder.build_navigation_doc()`` 1681* The config variables 1682 1683 - :confval:`html_experimental_html5_writer` 1684 1685* The ``encoding`` argument of ``autodoc.Documenter.get_doc()``, 1686 ``autodoc.DocstringSignatureMixin.get_doc()``, 1687 ``autodoc.DocstringSignatureMixin._find_signature()``, and 1688 ``autodoc.ClassDocumenter.get_doc()`` are deprecated. 1689* The ``importer`` argument of ``sphinx.ext.autodoc.importer._MockModule`` 1690* The ``nodetype`` argument of ``sphinx.search.WordCollector. 1691 is_meta_keywords()`` 1692* The ``suffix`` argument of ``env.doc2path()`` is deprecated. 1693* The string style ``base`` argument of ``env.doc2path()`` is deprecated. 1694* The fallback to allow omitting the ``filename`` argument from an overridden 1695 ``IndexBuilder.feed()`` method is deprecated. 1696* ``sphinx.addnodes.abbreviation`` 1697* ``sphinx.application.Sphinx._setting_up_extension`` 1698* ``sphinx.builders.epub3.Epub3Builder.validate_config_value()`` 1699* ``sphinx.builders.html.SingleFileHTMLBuilder`` 1700* ``sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()`` 1701* ``sphinx.cmd.quickstart.term_decode()`` 1702* ``sphinx.cmd.quickstart.TERM_ENCODING`` 1703* ``sphinx.config.check_unicode()`` 1704* ``sphinx.config.string_classes`` 1705* ``sphinx.domains.cpp.DefinitionError.description`` 1706* ``sphinx.domains.cpp.NoOldIdError.description`` 1707* ``sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded`` 1708* ``sphinx.ext.autodoc.importer._MockImporter`` 1709* ``sphinx.ext.autosummary.Autosummary.warn()`` 1710* ``sphinx.ext.autosummary.Autosummary.genopt`` 1711* ``sphinx.ext.autosummary.Autosummary.warnings`` 1712* ``sphinx.ext.autosummary.Autosummary.result`` 1713* ``sphinx.ext.doctest.doctest_encode()`` 1714* ``sphinx.io.SphinxBaseFileInput`` 1715* ``sphinx.io.SphinxFileInput.supported`` 1716* ``sphinx.io.SphinxRSTFileInput`` 1717* ``sphinx.registry.SphinxComponentRegistry.add_source_input()`` 1718* ``sphinx.roles.abbr_role()`` 1719* ``sphinx.roles.emph_literal_role()`` 1720* ``sphinx.roles.menusel_role()`` 1721* ``sphinx.roles.index_role()`` 1722* ``sphinx.roles.indexmarkup_role()`` 1723* ``sphinx.testing.util.remove_unicode_literal()`` 1724* ``sphinx.util.attrdict`` 1725* ``sphinx.util.force_decode()`` 1726* ``sphinx.util.get_matching_docs()`` 1727* ``sphinx.util.inspect.Parameter`` 1728* ``sphinx.util.jsonimpl`` 1729* ``sphinx.util.osutil.EEXIST`` 1730* ``sphinx.util.osutil.EINVAL`` 1731* ``sphinx.util.osutil.ENOENT`` 1732* ``sphinx.util.osutil.EPIPE`` 1733* ``sphinx.util.osutil.walk()`` 1734* ``sphinx.util.PeekableIterator`` 1735* ``sphinx.util.pycompat.NoneType`` 1736* ``sphinx.util.pycompat.TextIOWrapper`` 1737* ``sphinx.util.pycompat.UnicodeMixin`` 1738* ``sphinx.util.pycompat.htmlescape`` 1739* ``sphinx.util.pycompat.indent`` 1740* ``sphinx.util.pycompat.sys_encoding`` 1741* ``sphinx.util.pycompat.terminal_safe()`` 1742* ``sphinx.util.pycompat.u`` 1743* ``sphinx.writers.latex.ExtBabel`` 1744* ``sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()`` 1745* ``sphinx.writers.latex.LaTeXTranslator.babel_defmacro()`` 1746* ``sphinx.writers.latex.LaTeXTranslator.collect_footnotes()`` 1747* ``sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()`` 1748* ``sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()`` 1749* ``sphinx.writers.text.TextTranslator._make_depart_admonition()`` 1750* template variables for LaTeX template 1751 1752 - ``logo`` 1753 - ``numfig_format`` 1754 - ``pageautorefname`` 1755 - ``translatablestrings`` 1756 1757For more details, see :ref:`deprecation APIs list <dev-deprecated-apis>`. 1758 1759Features added 1760-------------- 1761 17622.0.0b1 1763 1764* #1618: The search results preview of generated HTML documentation is 1765 reader-friendlier: instead of showing the snippets as raw reStructuredText 1766 markup, Sphinx now renders the corresponding HTML. This means the Sphinx 1767 extension `Sphinx: pretty search results`__ is no longer necessary. Note that 1768 changes to the search function of your custom or 3rd-party HTML template might 1769 overwrite this improvement. 1770 1771 __ https://github.com/sphinx-contrib/sphinx-pretty-searchresults 1772 1773* #4182: autodoc: Support :confval:`suppress_warnings` 1774* #5533: autodoc: :confval:`autodoc_default_options` supports ``member-order`` 1775* #5394: autodoc: Display readable names in type annotations for mocked objects 1776* #5459: autodoc: :confval:`autodoc_default_options` accepts ``True`` as a value 1777* #1148: autodoc: Add :rst:dir:`autodecorator` directive for decorators 1778* #5635: autosummary: Add :confval:`autosummary_mock_imports` to mock external 1779 libraries on importing targets 1780* #4018: htmlhelp: Add :confval:`htmlhelp_file_suffix` and 1781 :confval:`htmlhelp_link_suffix` 1782* #5559: text: Support complex tables (colspan and rowspan) 1783* LaTeX: support rendering (not in math, yet) of Greek and Cyrillic Unicode 1784 letters in non-Cyrillic document even with ``'pdflatex'`` as 1785 :confval:`latex_engine` (refs: #5645) 1786* #5660: The ``versionadded``, ``versionchanged`` and ``deprecated`` directives 1787 are now generated with their own specific CSS classes 1788 (``added``, ``changed`` and ``deprecated``, respectively) in addition to the 1789 generic ``versionmodified`` class. 1790* #5841: apidoc: Add --extensions option to sphinx-apidoc 1791* #4981: C++, added an alias directive for inserting lists of declarations, 1792 that references existing declarations (e.g., for making a synopsis). 1793* C++: add ``cpp:struct`` to complement ``cpp:class``. 1794* #1341 the HTML search considers words that contain a search term of length 1795 three or longer a match. 1796* #4611: epub: Show warning for duplicated ToC entries 1797* #1851: Allow to omit an argument for :rst:dir:`code-block` directive. If 1798 omitted, it follows :rst:dir:`highlight` or :confval:`highlight_language` 1799* #4587: html: Add :confval:`html4_writer` to use old HTML4 writer 1800* #6016: HTML search: A placeholder for the search summary prevents search 1801 result links from changing their position when the search terminates. This 1802 makes navigating search results easier. 1803* #5196: linkcheck also checks remote images exist 1804* #5924: githubpages: create CNAME file for custom domains when 1805 :confval:`html_baseurl` set 1806* #4261: autosectionlabel: restrict the labeled sections by new config value; 1807 :confval:`autosectionlabel_maxdepth` 1808 1809 1810Bugs fixed 1811---------- 1812 18132.0.0b1 1814 1815* #1682: LaTeX: writer should not translate Greek unicode, but use textgreek 1816 package 1817* #5247: LaTeX: PDF does not build with default font config for Russian 1818 language and ``'xelatex'`` or ``'lualatex'`` as :confval:`latex_engine` 1819 (refs: #5251) 1820* #5248: LaTeX: Greek letters in section titles disappear from PDF bookmarks 1821* #5249: LaTeX: Unicode Greek letters in math directive break PDF build 1822 (fix requires extra set-up, see :confval:`latex_elements` ``'textgreek'`` key 1823 and/or :confval:`latex_engine` setting) 1824* #5772: LaTeX: should the Bjarne style of fncychap be used for English also 1825 if passed as language option? 1826* #5179: LaTeX: (lualatex only) escaping of ``>`` by ``\textgreater{}`` is not 1827 enough as ``\textgreater{}\textgreater{}`` applies TeX-ligature 1828* LaTeX: project name is not escaped if :confval:`latex_documents` omitted 1829* LaTeX: authors are not shown if :confval:`latex_documents` omitted 1830* HTML: Invalid HTML5 file is generated for a glossary having multiple terms for 1831 one description (refs: #4611) 1832* QtHelp: OS dependent path separator is used in .qhp file 1833* HTML search: search always returns nothing when multiple search terms are 1834 used and one term is shorter than three characters 1835 18362.0.0b2 1837 1838* #6096: html: Anchor links are not added to figures 1839* #3620: html: Defer searchindex.js rather than loading it via ajax 1840* #6113: html: Table cells and list items have large margins 1841* #5508: ``linenothreshold`` option for ``highlight`` directive was ignored 1842* texinfo: ``make install-info`` causes syntax error 1843* texinfo: ``make install-info`` fails on macOS 1844* #3079: texinfo: image files are not copied on ``make install-info`` 1845* #5391: A cross reference in heading is rendered as literal 1846* #5946: C++, fix ``cpp:alias`` problems in LaTeX (and singlehtml) 1847* #6147: classes attribute of ``citation_reference`` node is lost 1848* AssertionError is raised when custom ``citation_reference`` node having 1849 classes attribute refers missing citation (refs: #6147) 1850* #2155: Support ``code`` directive 1851* C++, fix parsing of braced initializers. 1852* #6172: AttributeError is raised for old styled index nodes 1853* #4872: inheritance_diagram: correctly describe behavior of ``parts`` option in 1854 docs, allow negative values. 1855* #6178: i18n: Captions missing in translations for hidden TOCs 1856 18572.0.0 final 1858 1859* #6196: py domain: unexpected prefix is generated 1860 1861Testing 1862-------- 1863 18642.0.0b1 1865 1866* Stop to use ``SPHINX_TEST_TEMPDIR`` envvar 1867 18682.0.0b2 1869 1870* Add a helper function: ``sphinx.testing.restructuredtext.parse()`` 1871 1872Release 1.8.5 (released Mar 10, 2019) 1873===================================== 1874 1875Bugs fixed 1876---------- 1877 1878* LaTeX: Remove extraneous space after author names on PDF title page (refs: 1879 #6004) 1880* #6026: LaTeX: A cross reference to definition list does not work 1881* #6046: LaTeX: ``TypeError`` is raised when invalid latex_elements given 1882* #6067: LaTeX: images having a target are concatenated to next line 1883* #6067: LaTeX: images having a target are not aligned even if specified 1884* #6149: LaTeX: ``:index:`` role in titles causes ``Use of \@icentercr doesn't 1885 match its definition`` error on latexpdf build 1886* #6019: imgconverter: Including multipage PDF fails 1887* #6047: autodoc: ``autofunction`` emits a warning for method objects 1888* #6028: graphviz: Ensure the graphviz filenames are reproducible 1889* #6068: doctest: ``skipif`` option may remove the code block from documentation 1890* #6136: ``:name:`` option for ``math`` directive causes a crash 1891* #6139: intersphinx: ValueError on failure reporting 1892* #6135: changes: Fix UnboundLocalError when any module found 1893* #3859: manpage: code-block captions are not displayed correctly 1894 1895Release 1.8.4 (released Feb 03, 2019) 1896===================================== 1897 1898Bugs fixed 1899---------- 1900 1901* #3707: latex: no bold checkmark (✔) available. 1902* #5605: with the documentation language set to Chinese, English words could not 1903 be searched. 1904* #5889: LaTeX: user ``numfig_format`` is stripped of spaces and may cause 1905 build failure 1906* C++, fix hyperlinks for declarations involving east cv-qualifiers. 1907* #5755: C++, fix duplicate declaration error on function templates with 1908 constraints in the return type. 1909* C++, parse unary right fold expressions and binary fold expressions. 1910* pycode could not handle egg files on windows 1911* #5928: KeyError: 'DOCUTILSCONFIG' when running build 1912* #5936: LaTeX: PDF build broken by inclusion of image taller than page height 1913 in an admonition 1914* #5231: "make html" does not read and build "po" files in "locale" dir 1915* #5954: ``:scale:`` image option may break PDF build if image in an admonition 1916* #5966: mathjax has not been loaded on incremental build 1917* #5960: LaTeX: modified PDF layout since September 2018 TeXLive update of 1918 :file:`parskip.sty` 1919* #5948: LaTeX: duplicated labels are generated for sections 1920* #5958: versionadded directive causes crash with Python 3.5.0 1921* #5995: autodoc: autodoc_mock_imports conflict with metaclass on Python 3.7 1922* #5871: texinfo: a section title ``.`` is not allowed 1923 1924Release 1.8.3 (released Dec 26, 2018) 1925===================================== 1926 1927Features added 1928-------------- 1929 1930* LaTeX: it is possible to insert custom material to appear on back of title 1931 page, see discussion of ``'maketitle'`` key of :confval:`latex_elements` 1932 (``'manual'`` docclass only) 1933 1934Bugs fixed 1935---------- 1936 1937* #5725: mathjax: Use CDN URL for "latest" version by default 1938* #5460: html search does not work with some 3rd party themes 1939* #5520: LaTeX, caption package incompatibility since Sphinx 1.6 1940* #5614: autodoc: incremental build is broken when builtin modules are imported 1941* #5627: qthelp: index.html missing in QtHelp 1942* #5659: linkcheck: crashes for a hyperlink containing multibyte character 1943* #5754: DOC: Fix some mistakes in :doc:`/latex` 1944* #5810: LaTeX: sphinxVerbatim requires explicit "hllines" set-up since 1.6.6 1945 (refs: #1238) 1946* #5636: C++, fix parsing of floating point literals. 1947* #5496 (again): C++, fix assertion in partial builds with duplicates. 1948* #5724: quickstart: sphinx-quickstart fails when $LC_ALL is empty 1949* #1956: Default conf.py is not PEP8-compliant 1950* #5849: LaTeX: document class ``\maketitle`` is overwritten with no 1951 possibility to use original meaning in place of Sphinx custom one 1952* #5834: apidoc: wrong help for ``--tocfile`` 1953* #5800: todo: crashed if todo is defined in TextElement 1954* #5846: htmlhelp: convert hex escaping to decimal escaping in .hhc/.hhk files 1955* htmlhelp: broken .hhk file generated when title contains a double quote 1956 1957Release 1.8.2 (released Nov 11, 2018) 1958===================================== 1959 1960Incompatible changes 1961-------------------- 1962 1963* #5497: Do not include MathJax.js and jsmath.js unless it is really needed 1964 1965Features added 1966-------------- 1967 1968* #5471: Show appropriate deprecation warnings 1969 1970Bugs fixed 1971---------- 1972 1973* #5490: latex: enumerated list causes a crash with recommonmark 1974* #5492: sphinx-build fails to build docs w/ Python < 3.5.2 1975* #3704: latex: wrong ``\label`` positioning for figures with a legend 1976* #5496: C++, fix assertion when a symbol is declared more than twice. 1977* #5493: gettext: crashed with broken template 1978* #5495: csv-table directive with file option in included file is broken (refs: 1979 #4821) 1980* #5498: autodoc: unable to find type hints for a ``functools.partial`` 1981* #5480: autodoc: unable to find type hints for unresolvable Forward references 1982* #5419: incompatible math_block node has been generated 1983* #5548: Fix ensuredir() in case of pre-existing file 1984* #5549: graphviz Correctly deal with non-existing static dir 1985* #3002: i18n: multiple footnote_references referring same footnote cause 1986 duplicated node_ids 1987* #5563: latex: footnote_references generated by extension causes a LaTeX 1988 builder crash 1989* #5561: make all-pdf fails with old xindy version 1990* #5557: quickstart: --no-batchfile isn't honored 1991* #3080: texinfo: multiline rubrics are broken 1992* #3080: texinfo: multiline citations are broken 1993 1994Release 1.8.1 (released Sep 22, 2018) 1995===================================== 1996 1997Incompatible changes 1998-------------------- 1999 2000* LaTeX ``\pagestyle`` commands have been moved to the LaTeX template. No 2001 changes in PDF, except possibly if ``\sphinxtableofcontents``, which 2002 contained them, had been customized in :file:`conf.py`. (refs: #5455) 2003 2004Bugs fixed 2005---------- 2006 2007* #5418: Incorrect default path for sphinx-build -d/doctrees files 2008* #5421: autodoc emits deprecation warning for :confval:`autodoc_default_flags` 2009* #5422: lambda object causes PicklingError on storing environment 2010* #5417: Sphinx fails to build with syntax error in Python 2.7.5 2011* #4911: add latexpdf to make.bat for non make-mode 2012* #5436: Autodoc does not work with enum subclasses with properties/methods 2013* #5437: autodoc: crashed on modules importing eggs 2014* #5433: latex: ImportError: cannot import name 'DEFAULT_SETTINGS' 2015* #5431: autodoc: ``autofunction`` emits a warning for callable objects 2016* #5457: Fix TypeError in error message when override is prohibited 2017* #5453: PDF builds of 'howto' documents have no page numbers 2018* #5463: mathbase: math_role and MathDirective was disappeared in 1.8.0 2019* #5454: latex: Index has disappeared from PDF for Japanese documents 2020* #5432: py domain: ``:type:`` field can't process ``:term:`` references 2021* #5426: py domain: TypeError has been raised for class attribute 2022 2023Release 1.8.0 (released Sep 13, 2018) 2024===================================== 2025 2026Dependencies 2027------------ 2028 20291.8.0b1 2030 2031* LaTeX: :confval:`latex_use_xindy`, if ``True`` (default for 2032 ``xelatex/lualatex``), instructs ``make latexpdf`` to use :program:`xindy` 2033 for general index. Make sure your LaTeX distribution includes it. 2034 (refs: #5134) 2035* LaTeX: ``latexmk`` is required for ``make latexpdf`` on Windows 2036 2037Incompatible changes 2038-------------------- 2039 20401.8.0b2 2041 2042* #5282: html theme: refer ``pygments_style`` settings of HTML themes 2043 preferentially 2044* The URL of download files are changed 2045* #5127: quickstart: ``Makefile`` and ``make.bat`` are not overwritten if exists 2046 20471.8.0b1 2048 2049* #5156: the :py:mod:`sphinx.ext.graphviz: extension runs `dot` in the 2050 directory of the document being built instead of in the root directory of 2051 the documentation. 2052* #4460: extensions which stores any data to environment should return the 2053 version of its env data structure as metadata. In detail, please see 2054 :ref:`ext-metadata`. 2055* Sphinx expects source parser modules to have supported file formats as 2056 ``Parser.supported`` attribute 2057* The default value of :confval:`epub_author` and :confval:`epub_publisher` are 2058 changed from ``'unknown'`` to the value of :confval:`author`. This is same as 2059 a ``conf.py`` file sphinx-build generates. 2060* The ``gettext_compact`` attribute is removed from ``document.settings`` 2061 object. Please use ``config.gettext_compact`` instead. 2062* The processing order on reading phase is changed. smart_quotes, sphinx 2063 domains, :event:`doctree-read` event and versioning doctrees are invoked 2064 earlier than so far. For more details, please read a description of 2065 :py:meth:`.Sphinx.add_transform()` 2066* #4827: All ``substitution_definition`` nodes are removed from doctree on 2067 reading phase 2068* ``docutils.conf`` in ``$HOME`` or ``/etc`` directories are ignored. Only 2069 ``docutils.conf`` from confdir is obeyed. 2070* #789: ``:samp:`` role supports to escape curly braces with backslash 2071* #4811: The files under :confval:`html_static_path` are excluded from source 2072 files. 2073* latex: Use ``\sphinxcite`` for citation references instead ``\hyperref`` 2074* The config value ``viewcode_import`` is renamed to 2075 :confval:`viewcode_follow_imported_members` (refs: #4035) 2076* #1857: latex: :confval:`latex_show_pagerefs` does not add pagerefs for 2077 citations 2078* #4648: latex: Now "rubric" elements are rendered as unnumbered section title 2079* #4983: html: The anchor for productionlist tokens has been changed 2080* Modifying a template variable ``script_files`` in templates is allowed now. 2081 Please use ``app.add_js_file()`` instead. 2082* #5072: Save environment object also with only new documents 2083* #5035: qthelp builder allows dashes in :confval:`qthelp_namespace` 2084* LaTeX: with lualatex or xelatex use by default :program:`xindy` as 2085 UTF-8 able replacement of :program:`makeindex` (refs: #5134). After 2086 upgrading Sphinx, please clean latex build repertory of existing project 2087 before new build. 2088* #5163: html: hlist items are now aligned to top 2089* ``highlightlang`` directive is processed on resolving phase 2090* #4000: LaTeX: template changed. Following elements moved to it: 2091 2092 - ``\begin{document}`` 2093 - ``shorthandoff`` variable 2094 - ``maketitle`` variable 2095 - ``tableofcontents`` variable 2096 2097Deprecated 2098---------- 2099 21001.8.0b2 2101 2102* ``sphinx.io.SphinxI18nReader.set_lineno_for_reporter()`` is deprecated 2103* ``sphinx.io.SphinxI18nReader.line`` is deprecated 2104* ``sphinx.util.i18n.find_catalog_source_file()`` has changed; the 2105 *gettext_compact* argument has been deprecated 2106* #5403: ``sphinx.util.images.guess_mimetype()`` has changed; the *content* 2107 argument has been deprecated 2108 21091.8.0b1 2110 2111* :confval:`source_parsers` is deprecated 2112* :confval:`autodoc_default_flags` is deprecated 2113* quickstart: ``--epub`` option becomes default, so it is deprecated 2114* Drop function based directive support. For now, Sphinx only supports class 2115 based directives (see :class:`~Directive`) 2116* ``sphinx.util.docutils.directive_helper()`` is deprecated 2117* ``sphinx.cmdline`` is deprecated 2118* ``sphinx.make_mode`` is deprecated 2119* ``sphinx.locale.l_()`` is deprecated 2120* #2157: helper function ``warn()`` for HTML themes is deprecated 2121* ``app.override_domain()`` is deprecated 2122* ``app.add_stylesheet()`` is deprecated 2123* ``app.add_javascript()`` is deprecated 2124* ``app.import_object()`` is deprecated 2125* ``app.add_source_parser()`` has changed; the *suffix* argument has been 2126 deprecated 2127* ``sphinx.versioning.prepare()`` is deprecated 2128* ``Config.__init__()`` has changed; the *dirname*, *filename* and *tags* 2129 argument has been deprecated 2130* ``Config.check_types()`` is deprecated 2131* ``Config.check_unicode()`` is deprecated 2132* ``sphinx.application.CONFIG_FILENAME`` is deprecated 2133* ``highlightlang`` directive is deprecated 2134* ``BuildEnvironment.load()`` is deprecated 2135* ``BuildEnvironment.loads()`` is deprecated 2136* ``BuildEnvironment.frompickle()`` is deprecated 2137* ``env.read_doc()`` is deprecated 2138* ``env.update()`` is deprecated 2139* ``env._read_serial()`` is deprecated 2140* ``env._read_parallel()`` is deprecated 2141* ``env.write_doctree()`` is deprecated 2142* ``env._nitpick_ignore`` is deprecated 2143* ``env.versionchanges`` is deprecated 2144* ``env.dump()`` is deprecated 2145* ``env.dumps()`` is deprecated 2146* ``env.topickle()`` is deprecated 2147* ``env.note_versionchange()`` is deprecated 2148* ``sphinx.writers.latex.Table.caption_footnotetexts`` is deprecated 2149* ``sphinx.writers.latex.Table.header_footnotetexts`` is deprecated 2150* ``sphinx.writers.latex.LaTeXTranslator.footnotestack`` is deprecated 2151* ``sphinx.writers.latex.LaTeXTranslator.in_container_literal_block`` is 2152 deprecated 2153* ``sphinx.writers.latex.LaTeXTranslator.next_section_ids`` is deprecated 2154* ``sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids`` is deprecated 2155* ``sphinx.writers.latex.LaTeXTranslator.restrict_footnote()`` is deprecated 2156* ``sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote()`` is deprecated 2157* ``sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids()`` is deprecated 2158* ``sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids()`` is deprecated 2159* ``sphinx.writers.latex.LaTeXTranslator.check_latex_elements()`` is deprecated 2160* ``sphinx.writers.latex.LaTeXTranslator.bibitems`` is deprecated 2161* ``sphinx.writers.latex.LaTeXTranslator.hlsettingstack`` is deprecated 2162* ``sphinx.writers.latex.ExtBabel.get_shorthandoff()`` is deprecated 2163* ``sphinx.writers.html.HTMLTranslator.highlightlang`` is deprecated 2164* ``sphinx.writers.html.HTMLTranslator.highlightlang_base`` is deprecated 2165* ``sphinx.writers.html.HTMLTranslator.highlightlangopts`` is deprecated 2166* ``sphinx.writers.html.HTMLTranslator.highlightlinenothreshold`` is deprecated 2167* ``sphinx.writers.html5.HTMLTranslator.highlightlang`` is deprecated 2168* ``sphinx.writers.html5.HTMLTranslator.highlightlang_base`` is deprecated 2169* ``sphinx.writers.html5.HTMLTranslator.highlightlangopts`` is deprecated 2170* ``sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold`` is deprecated 2171* ``sphinx.ext.mathbase`` extension is deprecated 2172* ``sphinx.ext.mathbase.math`` node is deprecated 2173* ``sphinx.ext.mathbase.displaymath`` node is deprecated 2174* ``sphinx.ext.mathbase.eqref`` node is deprecated 2175* ``sphinx.ext.mathbase.is_in_section_title()`` is deprecated 2176* ``sphinx.ext.mathbase.MathDomain`` is deprecated 2177* ``sphinx.ext.mathbase.MathDirective`` is deprecated 2178* ``sphinx.ext.mathbase.math_role`` is deprecated 2179* ``sphinx.ext.mathbase.setup_math()`` is deprecated 2180* ``sphinx.directives.other.VersionChanges`` is deprecated 2181* ``sphinx.highlighting.PygmentsBridge.unhighlight()`` is deprecated 2182* ``sphinx.ext.mathbase.get_node_equation_number()`` is deprecated 2183* ``sphinx.ext.mathbase.wrap_displaymath()`` is deprecated 2184* The ``trim_doctest_flags`` argument of ``sphinx.highlighting.PygmentsBridge`` 2185 is deprecated 2186 2187For more details, see `deprecation APIs list 2188<http://www.sphinx-doc.org/en/master/extdev/index.html#deprecated-apis>`_ 2189 2190Features added 2191-------------- 2192 21931.8.0b2 2194 2195* #5388: Ensure frozen object descriptions are reproducible 2196* #5362: apidoc: Add ``--tocfile`` option to change the filename of ToC 2197 21981.8.0b1 2199 2200* Add :event:`config-inited` event 2201* Add ``sphinx.config.Any`` to represent the config value accepts any type of 2202 value 2203* :confval:`source_suffix` allows a mapping fileext to file types 2204* Add :confval:`author` as a configuration value 2205* #2852: imgconverter: Support to convert GIF to PNG 2206* ``sphinx-build`` command supports i18n console output 2207* Add ``app.add_message_catalog()`` and ``sphinx.locale.get_translations()`` to 2208 support translation for 3rd party extensions 2209* helper function ``warning()`` for HTML themes is added 2210* Add ``Domain.enumerable_nodes`` to manage own enumerable nodes for domains 2211 (experimental) 2212* Add a new keyword argument ``override`` to Application APIs 2213* LaTeX: new key ``'fvset'`` for :confval:`latex_elements`. For 2214 XeLaTeX/LuaLaTeX its default sets ``fanvyvrb`` to use normal, not small, 2215 fontsize in code-blocks (refs: #4793) 2216* Add :confval:`html_css_files` and :confval:`epub_css_files` for adding CSS 2217 files from configuration 2218* Add :confval:`html_js_files` for adding JS files from configuration 2219* #4834: Ensure set object descriptions are reproducible. 2220* #4828: Allow to override :confval:`numfig_format` partially. Full definition 2221 is not needed. 2222* Improve warning messages during including (refs: #4818) 2223* LaTeX: separate customizability of :rst:role:`guilabel` and 2224 :rst:role:`menuselection` (refs: #4830) 2225* Add ``Config.read()`` classmethod to create a new config object from 2226 configuration file 2227* #4866: Wrap graphviz diagrams in ``<div>`` tag 2228* viewcode: Add :event:`viewcode-find-source` and 2229 :event:`viewcode-follow-imported` to load source code without loading 2230* #4785: napoleon: Add strings to translation file for localisation 2231* #4927: Display a warning when invalid values are passed to linenothreshold 2232 option of highlight directive 2233* C++: 2234 2235 - Add a ``cpp:texpr`` role as a sibling to ``cpp:expr``. 2236 - Add support for unions. 2237 - #3593, #2683: add support for anonymous entities using names staring with 2238 ``@``. 2239 - #5147: add support for (most) character literals. 2240 - Cross-referencing entities inside primary templates is supported, 2241 and now properly documented. 2242 - #1552: add new cross-referencing format for ``cpp:any`` and ``cpp:func`` 2243 roles, for referencing specific function overloads. 2244 2245* #3606: MathJax should be loaded with async attribute 2246* html: Output ``canonical_url`` metadata if :confval:`html_baseurl` set (refs: 2247 #4193) 2248* #5029: autosummary: expose ``inherited_members`` to template 2249* #3784: mathjax: Add :confval:`mathjax_options` to give options to script tag 2250 for mathjax 2251* #726, #969: mathjax: Add :confval:`mathjax_config` to give in-line 2252 configurations for mathjax 2253* #4362: latex: Don't overwrite .tex file if document not changed 2254* #1431: latex: Add alphanumeric enumerated list support 2255* Add :confval:`latex_use_xindy` for UTF-8 savvy indexing, defaults to ``True`` 2256 if :confval:`latex_engine` is ``'xelatex'`` or ``'lualatex'``. (refs: #5134, 2257 #5192, #5212) 2258* #4976: ``SphinxLoggerAdapter.info()`` now supports ``location`` parameter 2259* #5122: setuptools: support nitpicky option 2260* #2820: autoclass directive supports nested class 2261* Add ``app.add_html_math_renderer()`` to register a math renderer for HTML 2262* Apply :confval:`trim_doctest_flags` to all builders (cf. text, manpages) 2263* #5140: linkcheck: Add better Accept header to HTTP client 2264* #4614: sphinx-build: Add ``--keep-going`` option to show all warnings 2265* Add :rst:role:`math:numref` role to refer equations (Same as :rst:role:`eq`) 2266* quickstart: epub builder is enabled by default 2267* #5246: Add :confval:`singlehtml_sidebars` to configure sidebars for singlehtml 2268 builder 2269* #5273: doctest: Skip doctest conditionally 2270* #5306: autodoc: emit a warning for invalid typehints 2271* #4075, #5215: autodoc: Add :confval:`autodoc_default_options` which accepts 2272 option values as dict 2273 2274Bugs fixed 2275---------- 2276 22771.8.0b2 2278 2279* html: search box overrides to other elements if scrolled 2280* i18n: warnings for translation catalogs have wrong line numbers (refs: #5321) 2281* #5325: latex: cross references has been broken by multiply labeled objects 2282* C++, fixes for symbol addition and lookup. Lookup should no longer break 2283 in partial builds. See also #5337. 2284* #5348: download reference to remote file is not displayed 2285* #5282: html theme: ``pygments_style`` of theme was overridden by ``conf.py`` 2286 by default 2287* #4379: toctree shows confusing warning when document is excluded 2288* #2401: autodoc: ``:members:`` causes ``:special-members:`` not to be shown 2289* autodoc: ImportError is replaced by AttributeError for deeper module 2290* #2720, #4034: Incorrect links with ``:download:``, duplicate names, and 2291 parallel builds 2292* #5290: autodoc: failed to analyze source code in egg package 2293* #5399: Sphinx crashes if unknown po file exists 2294 22951.8.0b1 2296 2297* i18n: message catalogs were reset on each initialization 2298* #4850: latex: footnote inside footnote was not rendered 2299* #4945: i18n: fix lang_COUNTRY not fallback correctly for IndexBuilder. Thanks 2300 to Shengjing Zhu. 2301* #4983: productionlist directive generates invalid IDs for the tokens 2302* #5132: lualatex: PDF build fails if indexed word starts with Unicode character 2303* #5133: latex: index headings "Symbols" and "Numbers" not internationalized 2304* #5114: sphinx-build: Handle errors on scanning documents 2305* epub: spine has been broken when "self" is listed on toctree (refs: #4611) 2306* #344: autosummary does not understand docstring of module level attributes 2307* #5191: C++, prevent nested declarations in functions to avoid lookup problems. 2308* #5126: C++, add missing isPack method for certain template parameter types. 2309* #5187: C++, parse attributes on declarators as well. 2310* C++, parse delete expressions and basic new expressions as well. 2311* #5002: graphviz: SVGs do not adapt to the column width 2312 2313Features removed 2314---------------- 2315 23161.8.0b1 2317 2318* ``sphinx.ext.pngmath`` extension 2319 2320Documentation 2321------------- 2322 23231.8.0b1 2324 2325* #5083: Fix wrong make.bat option for internationalization. 2326* #5115: napoleon: add admonitions added by #4613 to the docs. 2327 2328Release 1.7.9 (released Sep 05, 2018) 2329===================================== 2330 2331Features added 2332-------------- 2333 2334* #5359: Make generated texinfo files reproducible by sorting the anchors 2335 2336Bugs fixed 2337---------- 2338 2339* #5361: crashed on incremental build if document uses include directive 2340 2341Release 1.7.8 (released Aug 29, 2018) 2342===================================== 2343 2344Incompatible changes 2345-------------------- 2346 2347* The type of ``env.included`` has been changed to dict of set 2348 2349Bugs fixed 2350---------- 2351 2352* #5320: intersphinx: crashed if invalid url given 2353* #5326: manpage: crashed when invalid docname is specified as ``man_pages`` 2354* #5322: autodoc: ``Any`` typehint causes formatting error 2355* #5327: "document isn't included in any toctree" warning on rebuild with 2356 generated files 2357* #5335: quickstart: escape sequence has been displayed with MacPorts' python 2358 2359Release 1.7.7 (released Aug 19, 2018) 2360===================================== 2361 2362Bugs fixed 2363---------- 2364 2365* #5198: document not in toctree warning when including files only for parallel 2366 builds 2367* LaTeX: reduce "Token not allowed in a PDF string" hyperref warnings in latex 2368 console output (refs: #5236) 2369* LaTeX: suppress "remreset Warning: The remreset package is obsolete" in latex 2370 console output with recent LaTeX (refs: #5237) 2371* #5234: PDF output: usage of PAPER environment variable is broken since Sphinx 2372 1.5 2373* LaTeX: fix the :confval:`latex_engine` documentation regarding Latin Modern 2374 font with XeLaTeX/LuaLateX (refs: #5251) 2375* #5280: autodoc: Fix wrong type annotations for complex typing 2376* autodoc: Optional types are wrongly rendered 2377* #5291: autodoc crashed by ForwardRef types 2378* #5211: autodoc: No docs generated for functools.partial functions 2379* #5306: autodoc: ``getargspec()`` raises NameError for invalid typehints 2380* #5298: imgmath: math_number_all causes equations to have two numbers in html 2381* #5294: sphinx-quickstart blank prompts in PowerShell 2382 2383Release 1.7.6 (released Jul 17, 2018) 2384===================================== 2385 2386Bugs fixed 2387---------- 2388 2389* #5037: LaTeX ``\sphinxupquote{}`` breaks in Russian 2390* sphinx.testing uses deprecated pytest API; ``Node.get_marker(name)`` 2391* #5016: crashed when recommonmark.AutoStrictify is enabled 2392* #5022: latex: crashed with docutils package provided by Debian/Ubuntu 2393* #5009: latex: a label for table is vanished if table does not have a caption 2394* #5048: crashed with numbered toctree 2395* #2410: C, render empty argument lists for macros. 2396* C++, fix lookup of full template specializations with no template arguments. 2397* #4667: C++, fix assertion on missing references in global scope when using 2398 intersphinx. Thanks to Alan M. Carroll. 2399* #5019: autodoc: crashed by Form Feed Character 2400* #5032: autodoc: loses the first staticmethod parameter for old styled classes 2401* #5036: quickstart: Typing Ctrl-U clears the whole of line 2402* #5066: html: "relations" sidebar is not shown by default 2403* #5091: latex: curly braces in index entries are not handled correctly 2404* #5070: epub: Wrong internal href fragment links 2405* #5104: apidoc: Interface of ``sphinx.apidoc:main()`` has changed 2406* #4272: PDF builds of French projects have issues with XeTeX 2407* #5076: napoleon raises RuntimeError with python 3.7 2408* #5125: sphinx-build: Interface of ``sphinx:main()`` has changed 2409* sphinx-build: ``sphinx.cmd.build.main()`` refers ``sys.argv`` instead of given 2410 argument 2411* #5146: autosummary: warning is emitted when the first line of docstring ends 2412 with literal notation 2413* autosummary: warnings of autosummary indicates wrong location (refs: #5146) 2414* #5143: autodoc: crashed on inspecting dict like object which does not support 2415 sorting 2416* #5139: autodoc: Enum argument missing if it shares value with another 2417* #4946: py domain: rtype field could not handle "None" as a type 2418* #5176: LaTeX: indexing of terms containing ``@``, ``!``, or ``"`` fails 2419* #5161: html: crashes if copying static files are failed 2420* #5167: autodoc: Fix formatting type annotations for tuples with more than two 2421 arguments 2422* #3329: i18n: crashed by auto-symbol footnote references 2423* #5158: autosummary: module summary has been broken when it starts with heading 2424 2425Release 1.7.5 (released May 29, 2018) 2426===================================== 2427 2428Bugs fixed 2429---------- 2430 2431* #4924: html search: Upper characters problem in any other languages 2432* #4932: apidoc: some subpackage is ignored if sibling subpackage contains a 2433 module starting with underscore 2434* #4863, #4938, #4939: i18n doesn't handle correctly node.title as used for 2435 contents, topic, admonition, table and section. 2436* #4913: i18n: literal blocks in bullet list are not translated 2437* #4962: C++, raised TypeError on duplicate declaration. 2438* #4825: C++, properly parse expr roles and give better error messages when 2439 (escaped) line breaks are present. 2440* C++, properly use ``desc_addname`` nodes for prefixes of names. 2441* C++, parse pack expansions in function calls. 2442* #4915, #4916: links on search page are broken when using dirhtml builder 2443* #4969: autodoc: constructor method should not have return annotation 2444* latex: deeply nested enumerated list which is beginning with non-1 causes 2445 LaTeX engine crashed 2446* #4978: latex: shorthandoff is not set up for Brazil locale 2447* #4928: i18n: Ignore dot-directories like .git/ in LC_MESSAGES/ 2448* #4946: py domain: type field could not handle "None" as a type 2449* #4979: latex: Incorrect escaping of curly braces in index entries 2450* #4956: autodoc: Failed to extract document from a subclass of the class on 2451 mocked module 2452* #4973: latex: glossary directive adds whitespace to each item 2453* #4980: latex: Explicit labels on code blocks are duplicated 2454* #4919: node.asdom() crashes if toctree has :numbered: option 2455* #4914: autodoc: Parsing error when using dataclasses without default values 2456* #4931: autodoc: crashed when handler for autodoc-skip-member raises an error 2457* #4931: autodoc: crashed when subclass of mocked class are processed by 2458 napoleon module 2459* #5007: sphinx-build crashes when error log contains a "%" character 2460 2461Release 1.7.4 (released Apr 25, 2018) 2462===================================== 2463 2464Bugs fixed 2465---------- 2466 2467* #4885, #4887: domains: Crashed with duplicated objects 2468* #4889: latex: sphinx.writers.latex causes recursive import 2469 2470Release 1.7.3 (released Apr 23, 2018) 2471===================================== 2472 2473Bugs fixed 2474---------- 2475 2476* #4769: autodoc loses the first staticmethod parameter 2477* #4790: autosummary: too wide two column tables in PDF builds 2478* #4795: Latex customization via ``_templates/longtable.tex_t`` is broken 2479* #4789: imgconverter: confused by convert.exe of Windows 2480* #4783: On windows, Sphinx crashed when drives of srcdir and outdir are 2481 different 2482* #4812: autodoc ignores type annotated variables 2483* #4817: wrong URLs on warning messages 2484* #4784: latex: :confval:`latex_show_urls` assigns incorrect footnote numbers if 2485 hyperlinks exists inside substitutions 2486* #4837: latex with class memoir Error: Font command ``\sf`` is not supported 2487* #4803: latex: too slow in proportion to number of auto numbered footnotes 2488* #4838: htmlhelp: The entries in .hhp file is not ordered 2489* toctree directive tries to glob for URL having query_string 2490* #4871: html search: Upper characters problem in German 2491* #4717: latex: Compilation for German docs failed with LuaLaTeX and XeLaTeX 2492* #4459: duplicated labels detector does not work well in parallel build 2493* #4878: Crashed with extension which returns invalid metadata 2494 2495Release 1.7.2 (released Mar 21, 2018) 2496===================================== 2497 2498Incompatible changes 2499-------------------- 2500* #4520: apidoc: folders with an empty __init__.py are no longer excluded from 2501 TOC 2502 2503Bugs fixed 2504---------- 2505 2506* #4669: sphinx.build_main and sphinx.make_main throw NameError 2507* #4685: autosummary emits meaningless warnings 2508* autodoc: crashed when invalid options given 2509* pydomain: always strip parenthesis if empty (refs: #1042) 2510* #4689: autosummary: unexpectedly strips docstrings containing "i.e." 2511* #4701: viewcode: Misplaced ``<div>`` in viewcode html output 2512* #4444: Don't require numfig to use :numref: on sections 2513* #4727: Option clash for package textcomp 2514* #4725: Sphinx does not work with python 3.5.0 and 3.5.1 2515* #4716: Generation PDF file with TexLive on Windows, file not found error 2516* #4574: vertical space before equation in latex 2517* #4720: message when an image is mismatched for builder is not clear 2518* #4655, #4684: Incomplete localization strings in Polish and Chinese 2519* #2286: Sphinx crashes when error is happens in rendering HTML pages 2520* #4688: Error to download remote images having long URL 2521* #4754: sphinx/pycode/__init__.py raises AttributeError 2522* #1435: qthelp builder should htmlescape keywords 2523* epub: Fix docTitle elements of toc.ncx is not escaped 2524* #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed 2525* #4767: html: search highlighting breaks mathjax equations 2526 2527Release 1.7.1 (released Feb 23, 2018) 2528===================================== 2529 2530Deprecated 2531---------- 2532 2533* #4623: ``sphinx.build_main()`` is deprecated. 2534* autosummary: The interface of ``sphinx.ext.autosummary.get_documenter()`` has 2535 been changed (Since 1.7.0) 2536* #4664: ``sphinx.ext.intersphinx.debug()`` is deprecated. 2537 2538For more details, see `deprecation APIs list 2539<http://www.sphinx-doc.org/en/master/extdev/index.html#deprecated-apis>`_ 2540 2541Bugs fixed 2542---------- 2543 2544* #4608: epub: Invalid meta tag is generated 2545* #4260: autodoc: keyword only argument separator is not disappeared if it is 2546 appeared at top of the argument list 2547* #4622: epub: :confval:`epub_scheme` does not effect to content.opf 2548* #4627: graphviz: Fit graphviz images to page 2549* #4617: quickstart: PROJECT_DIR argument is required 2550* #4623: sphinx.build_main no longer exists in 1.7.0 2551* #4615: The argument of ``sphinx.build`` has been changed in 1.7.0 2552* autosummary: The interface of ``sphinx.ext.autosummary.get_documenter()`` has 2553 been changed 2554* #4630: Have order on msgids in sphinx.pot deterministic 2555* #4563: autosummary: Incorrect end of line punctuation detection 2556* #4577: Enumerated sublists with explicit start with wrong number 2557* #4641: A external link in TOC cannot contain "?" with ``:glob:`` option 2558* C++, add missing parsing of explicit casts and typeid in expression parsing. 2559* C++, add missing parsing of ``this`` in expression parsing. 2560* #4655: Fix incomplete localization strings in Polish 2561* #4653: Fix error reporting for parameterless ImportErrors 2562* #4664: Reading objects.inv fails again 2563* #4662: ``any`` refs with ``term`` targets crash when an ambiguity is 2564 encountered 2565 2566Release 1.7.0 (released Feb 12, 2018) 2567===================================== 2568 2569Dependencies 2570------------ 2571 25721.7.0b1 2573 2574* Add ``packaging`` package 2575 2576Incompatible changes 2577-------------------- 2578 25791.7.0b1 2580 2581* #3668: The arguments has changed of main functions for each command 2582* #3893: Unknown html_theme_options throw warnings instead of errors 2583* #3927: Python parameter/variable types should match classes, not all objects 2584* #3962: sphinx-apidoc now recognizes given directory as an implicit namespace 2585 package when ``--implicit-namespaces`` option given, not subdirectories of 2586 given directory. 2587* #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc 2588* #4226: apidoc: Generate new style makefile (make-mode) 2589* #4274: sphinx-build returns 2 as an exit code on argument error 2590* #4389: output directory will be created after loading extensions 2591* autodoc does not generate warnings messages to the generated document even if 2592 :confval:`keep_warnings` is True. They are only emitted to stderr. 2593* shebang line is removed from generated conf.py 2594* #2557: autodoc: :confval:`autodoc_mock_imports` only mocks specified modules 2595 with their descendants. It does not mock their ancestors. If you want to 2596 mock them, please specify the name of ancestors explicitly. 2597* #3620: html theme: move DOCUMENTATION_OPTIONS to independent JavaScript file 2598 (refs: #4295) 2599* #4246: Limit width of text body for all themes. Configurable via theme 2600 options ``body_min_width`` and ``body_max_width``. 2601* #4771: apidoc: The ``exclude_patterns`` arguments are ignored if they are 2602 placed just after command line options 2603 26041.7.0b2 2605 2606* #4467: html theme: Rename ``csss`` block to ``css`` 2607 2608Deprecated 2609---------- 2610 26111.7.0b1 2612 2613* using a string value for :confval:`html_sidebars` is deprecated and only list 2614 values will be accepted at 2.0. 2615* ``format_annotation()`` and ``formatargspec()`` is deprecated. Please use 2616 ``sphinx.util.inspect.Signature`` instead. 2617* ``sphinx.ext.autodoc.AutodocReporter`` is replaced by ``sphinx.util.docutils. 2618 switch_source_input()`` and now deprecated. It will be removed in Sphinx-2.0. 2619* ``sphinx.ext.autodoc.add_documenter()`` and ``AutoDirective._register`` is now 2620 deprecated. Please use ``app.add_autodocumenter()`` instead. 2621* ``AutoDirective._special_attrgetters`` is now deprecated. Please use 2622 ``app.add_autodoc_attrgetter()`` instead. 2623 2624Features added 2625-------------- 2626 26271.7.0b1 2628 2629* C++, handle ``decltype(auto)``. 2630* #2406: C++, add proper parsing of expressions, including linking of 2631 identifiers. 2632* C++, add a ``cpp:expr`` role for inserting inline C++ expressions or types. 2633* C++, support explicit member instantiations with shorthand ``template`` prefix 2634* C++, make function parameters linkable, like template params. 2635* #3638: Allow to change a label of reference to equation using 2636 ``math_eqref_format`` 2637* Now :confval:`suppress_warnings` accepts following configurations: 2638 2639 - ``ref.python`` (ref: #3866) 2640 2641* #3872: Add latex key to configure literal blocks caption position in PDF 2642 output (refs #3792, #1723) 2643* In case of missing docstring try to retrieve doc from base classes (ref: 2644 #3140) 2645* #4023: Clarify error message when any role has more than one target. 2646* #3973: epub: allow to override build date 2647* #3972: epub: Sort manifest entries by filename 2648* #4052: viewcode: Sort before highlighting module code 2649* #1448: qthelp: Add new config value; :confval:`qthelp_namespace` 2650* #4140: html themes: Make body tag inheritable 2651* #4168: improve zh search with jieba 2652* HTML themes can set up default sidebars through ``theme.conf`` 2653* #3160: html: Use ``<kdb>`` to represent ``:kbd:`` role 2654* #4212: autosummary: catch all exceptions when importing modules 2655* #4166: Add :confval:`math_numfig` for equation numbering by section (refs: 2656 #3991, #4080). Thanks to Oliver Jahn. 2657* #4311: Let LaTeX obey :confval:`numfig_secnum_depth` for figures, tables, and 2658 code-blocks 2659* #947: autodoc now supports ignore-module-all to ignore a module's ``__all__`` 2660* #4332: Let LaTeX obey :confval:`math_numfig` for equation numbering 2661* #4093: sphinx-build creates empty directories for unknown targets/builders 2662* Add ``top-classes`` option for the ``sphinx.ext.inheritance_diagram`` 2663 extension to limit the scope of inheritance graphs. 2664* #4183: doctest: ``:pyversion:`` option also follows PEP-440 specification 2665* #4235: html: Add :confval:`manpages_url` to make manpage roles to hyperlinks 2666* #3570: autodoc: Do not display 'typing.' module for type hints 2667* #4354: sphinx-build now emits finish message. Builders can modify it through 2668 ``Builder.epilog`` attribute 2669* #4245: html themes: Add ``language`` to javascript vars list 2670* #4079: html: Add ``notranslate`` class to each code-blocks, literals and maths 2671 to let Google Translate know they are not translatable 2672* #4137: doctest: doctest block is always highlighted as python console (pycon) 2673* #4137: doctest: testcode block is always highlighted as python 2674* #3998: text: Assign section numbers by default. You can control it using 2675 :confval:`text_add_secnumbers` and :confval:`text_secnumber_suffix` 2676 26771.7.0b2 2678 2679* #4271: sphinx-build supports an option called ``-j auto`` to adjust numbers of 2680 processes automatically. 2681* Napoleon: added option to specify custom section tags. 2682 2683 2684Features removed 2685---------------- 2686 26871.7.0b1 2688 2689* Configuration variables 2690 2691 - html_use_smartypants 2692 - latex_keep_old_macro_names 2693 - latex_elements['footer'] 2694 2695* utility methods of ``sphinx.application.Sphinx`` class 2696 2697 - buildername (property) 2698 - _display_chunk() 2699 - old_status_iterator() 2700 - status_iterator() 2701 - _directive_helper() 2702 2703* utility methods of ``sphinx.environment.BuildEnvironment`` class 2704 2705 - currmodule (property) 2706 - currclass (property) 2707 2708* epub2 builder 2709* prefix and colorfunc parameter for warn() 2710* ``sphinx.util.compat`` module 2711* ``sphinx.util.nodes.process_only_nodes()`` 2712* LaTeX environment ``notice``, use ``sphinxadmonition`` instead 2713* LaTeX ``\sphinxstylethead``, use ``\sphinxstyletheadfamily`` 2714* C++, support of function concepts. Thanks to mickk-on-cpp. 2715* Not used and previously not documented LaTeX macros ``\shortversion`` 2716 and ``\setshortversion`` 2717 2718 2719Bugs fixed 2720---------- 2721 27221.7.0b1 2723 2724* #3882: Update the order of files for HTMLHelp and QTHelp 2725* #3962: sphinx-apidoc does not recognize implicit namespace packages correctly 2726* #4094: C++, allow empty template argument lists. 2727* C++, also hyperlink types in the name of declarations with qualified names. 2728* C++, do not add index entries for declarations inside concepts. 2729* C++, support the template disambiguator for dependent names. 2730* #4314: For PDF 'howto' documents, numbering of code-blocks differs from the 2731 one of figures and tables 2732* #4330: PDF 'howto' documents have an incoherent default LaTeX tocdepth counter 2733 setting 2734* #4198: autosummary emits multiple 'autodoc-process-docstring' event. Thanks 2735 to Joel Nothman. 2736* #4081: Warnings and errors colored the same when building 2737* latex: Do not display 'Release' label if :confval:`release` is not set 2738 27391.7.0b2 2740 2741* #4415: autodoc classifies inherited classmethods as regular methods 2742* #4415: autodoc classifies inherited staticmethods as regular methods 2743* #4472: DOCUMENTATION_OPTIONS is not defined 2744* #4491: autodoc: prefer _MockImporter over other importers in sys.meta_path 2745* #4490: autodoc: type annotation is broken with python 3.7.0a4+ 2746* utils package is no longer installed 2747* #3952: apidoc: module header is too escaped 2748* #4275: Formats accepted by sphinx.util.i18n.format_date are limited 2749* #4493: recommonmark raises AttributeError if AutoStructify enabled 2750* #4209: intersphinx: In link title, "v" should be optional if target has no 2751 version 2752* #4230: slowdown in writing pages with sphinx 1.6 2753* #4522: epub: document is not rebuilt even if config changed 2754 27551.7.0b3 2756 2757* #4019: inheritance_diagram AttributeError stopping make process 2758* #4531: autosummary: methods are not treated as attributes 2759* #4538: autodoc: ``sphinx.ext.autodoc.Options`` has been moved 2760* #4539: autodoc emits warnings for partialmethods 2761* #4223: doctest: failing tests reported in wrong file, at wrong line 2762* i18n: message catalogs are not compiled if specific filenames are given for 2763 ``sphinx-build`` as arguments (refs: #4560) 2764* #4027: sphinx.ext.autosectionlabel now expects labels to be the same as they 2765 are in the raw source; no smart quotes, nothig fancy. 2766* #4581: apidoc: Excluded modules still included 2767 2768 2769Testing 2770-------- 2771 27721.7.0b1 2773 2774* Add support for docutils 0.14 2775* Add tests for the ``sphinx.ext.inheritance_diagram`` extension. 2776 2777Release 1.6.7 (released Feb 04, 2018) 2778===================================== 2779 2780Bugs fixed 2781---------- 2782 2783* #1922: html search: Upper characters problem in French 2784* #4412: Updated jQuery version from 3.1.0 to 3.2.1 2785* #4438: math: math with labels with whitespace cause html error 2786* #2437: make full reference for classes, aliased with "alias of" 2787* #4434: pure numbers as link targets produce warning 2788* #4477: Build fails after building specific files 2789* #4449: apidoc: include "empty" packages that contain modules 2790* #3917: citation labels are transformed to ellipsis 2791* #4501: graphviz: epub3 validation error caused if graph is not clickable 2792* #4514: graphviz: workaround for wrong map ID which graphviz generates 2793* #4525: autosectionlabel does not support parallel build 2794* #3953: Do not raise warning when there is a working intersphinx inventory 2795* #4487: math: ValueError is raised on parallel build. Thanks to jschueller. 2796* #2372: autosummary: invalid signatures are shown for type annotated functions 2797* #3942: html: table is not aligned to center even if ``:align: center`` 2798 2799Release 1.6.6 (released Jan 08, 2018) 2800===================================== 2801 2802Features added 2803-------------- 2804 2805* #4181: autodoc: Sort dictionary keys when possible 2806* ``VerbatimHighlightColor`` is a new 2807 :ref:`LaTeX 'sphinxsetup' <latexsphinxsetup>` key (refs: #4285) 2808* Easier customizability of LaTeX macros involved in rendering of code-blocks 2809* Show traceback if conf.py raises an exception (refs: #4369) 2810* Add :confval:`smartquotes` to disable smart quotes through ``conf.py`` 2811 (refs: #3967) 2812* Add :confval:`smartquotes_action` and :confval:`smartquotes_excludes` 2813 (refs: #4142, #4357) 2814 2815Bugs fixed 2816---------- 2817 2818* #4334: sphinx-apidoc: Don't generate references to non-existing files in TOC 2819* #4206: latex: reST label between paragraphs loses paragraph break 2820* #4231: html: Apply fixFirefoxAnchorBug only under Firefox 2821* #4221: napoleon depends on autodoc, but users need to load it manually 2822* #2298: automodule fails to document a class attribute 2823* #4099: C++: properly link class reference to class from inside constructor 2824* #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character 2825* #4249: PDF output: Pygments error highlighting increases line spacing in 2826 code blocks 2827* #1238: Support ``:emphasize-lines:`` in PDF output 2828* #4279: Sphinx crashes with pickling error when run with multiple processes and 2829 remote image 2830* #1421: Respect the quiet flag in sphinx-quickstart 2831* #4281: Race conditions when creating output directory 2832* #4315: For PDF 'howto' documents, ``latex_toplevel_sectioning='part'`` 2833 generates ``\chapter`` commands 2834* #4214: Two todolist directives break sphinx-1.6.5 2835* Fix links to external option docs with intersphinx (refs: #3769) 2836* #4091: Private members not documented without :undoc-members: 2837 2838Release 1.6.5 (released Oct 23, 2017) 2839===================================== 2840 2841Features added 2842-------------- 2843 2844* #4107: Make searchtools.js compatible with pre-Sphinx1.5 templates 2845* #4112: Don't override the smart_quotes setting if it was already set 2846* #4125: Display reference texts of original and translated passages on 2847 i18n warning message 2848* #4147: Include the exception when logging PO/MO file read/write 2849 2850Bugs fixed 2851---------- 2852 2853* #4085: Failed PDF build from image in parsed-literal using ``:align:`` option 2854* #4100: Remove debug print from autodoc extension 2855* #3987: Changing theme from alabaster causes HTML build to fail 2856* #4096: C++, don't crash when using the wrong role type. Thanks to mitya57. 2857* #4070, #4111: crashes when the warning message contains format strings (again) 2858* #4108: Search word highlighting breaks SVG images 2859* #3692: Unable to build HTML if writing .buildinfo failed 2860* #4152: HTML writer crashes if a field list is placed on top of the document 2861* #4063: Sphinx crashes when labeling directive ``.. todolist::`` 2862* #4134: [doc] :file:`docutils.conf` is not documented explicitly 2863* #4169: Chinese language doesn't trigger Chinese search automatically 2864* #1020: ext.todo todolist not linking to the page in pdflatex 2865* #3965: New quickstart generates wrong SPHINXBUILD in Makefile 2866* #3739: ``:module:`` option is ignored at content of pyobjects 2867* #4149: Documentation: Help choosing :confval:`latex_engine` 2868* #4090: [doc] :confval:`latex_additional_files` with extra LaTeX macros should 2869 not use ``.tex`` extension 2870* Failed to convert reST parser error to warning (refs: #4132) 2871 2872Release 1.6.4 (released Sep 26, 2017) 2873===================================== 2874 2875Features added 2876-------------- 2877 2878* #3926: Add ``autodoc_warningiserror`` to suppress the behavior of ``-W`` 2879 option during importing target modules on autodoc 2880 2881Bugs fixed 2882---------- 2883 2884* #3924: docname lost after dynamically parsing RST in extension 2885* #3946: Typo in sphinx.sty (this was a bug with no effect in default context) 2886* :pep: and :rfc: does not supports ``default-role`` directive (refs: #3960) 2887* #3960: default_role = 'guilabel' not functioning 2888* Missing ``texinputs_win/Makefile`` to be used in latexpdf builder on windows. 2889* #4026: nature: Fix macOS Safari scrollbar color 2890* #3877: Fix for C++ multiline signatures. 2891* #4006: Fix crash on parallel build 2892* #3969: private instance attributes causes AttributeError 2893* #4041: C++, remove extra name linking in function pointers. 2894* #4038: C, add missing documentation of ``member`` role. 2895* #4044: An empty multicolumn cell causes extra row height in PDF output 2896* #4049: Fix typo in output of sphinx-build -h 2897* #4062: hashlib.sha1() must take bytes, not unicode on Python 3 2898* Avoid indent after index entries in latex (refs: #4066) 2899* #4070: crashes when the warning message contains format strings 2900* #4067: Return non-zero exit status when make subprocess fails 2901* #4055: graphviz: the :align: option does not work for SVG output 2902* #4055: graphviz: the :align: center option does not work for latex output 2903* #4051: ``warn()`` function for HTML theme outputs 'None' string 2904 2905Release 1.6.3 (released Jul 02, 2017) 2906===================================== 2907 2908Features added 2909-------------- 2910 2911* latex: hint that code-block continues on next page (refs: #3764, #3792) 2912 2913Bugs fixed 2914---------- 2915 2916* #3821: Failed to import sphinx.util.compat with docutils-0.14rc1 2917* #3829: sphinx-quickstart template is incomplete regarding use of alabaster 2918* #3772: 'str object' has no attribute 'filename' 2919* Emit wrong warnings if citation label includes hyphens (refs: #3565) 2920* #3858: Some warnings are not colored when using --color option 2921* #3775: Remove unwanted whitespace in default template 2922* #3835: sphinx.ext.imgmath fails to convert SVG images if project directory 2923 name contains spaces 2924* #3850: Fix color handling in make mode's help command 2925* #3865: use of self.env.warn in sphinx extension fails 2926* #3824: production lists apply smart quotes transform since Sphinx 1.6.1 2927* latex: fix ``\sphinxbfcode`` swallows initial space of argument 2928* #3878: Quotes in auto-documented class attributes should be straight quotes 2929 in PDF output 2930* #3881: LaTeX figure floated to next page sometimes leaves extra vertical 2931 whitespace 2932* #3885: duplicated footnotes raises IndexError 2933* #3873: Failure of deprecation warning mechanism of 2934 ``sphinx.util.compat.Directive`` 2935* #3874: Bogus warnings for "citation not referenced" for cross-file citations 2936* #3860: Don't download images when builders not supported images 2937* #3860: Remote image URIs without filename break builders not supported remote 2938 images 2939* #3833: command line messages are translated unintentionally with ``language`` 2940 setting. 2941* #3840: make checking ``epub_uid`` strict 2942* #3851, #3706: Fix about box drawing characters for PDF output 2943* #3900: autosummary could not find methods 2944* #3902: Emit error if ``latex_documents`` contains non-unicode string in py2 2945 2946Release 1.6.2 (released May 28, 2017) 2947===================================== 2948 2949Incompatible changes 2950-------------------- 2951 2952* #3789: Do not require typing module for python>=3.5 2953 2954Bugs fixed 2955---------- 2956 2957* #3754: HTML builder crashes if HTML theme appends own stylesheets 2958* #3756: epub: Entity 'mdash' not defined 2959* #3758: Sphinx crashed if logs are emitted in conf.py 2960* #3755: incorrectly warns about dedent with literalinclude 2961* #3742: `RTD <https://readthedocs.org/>`_ PDF builds of Sphinx own docs are 2962 missing an index entry in the bookmarks and table of contents. This is 2963 `rtfd/readthedocs.org#2857 2964 <https://github.com/rtfd/readthedocs.org/issues/2857>`_ issue, a workaround 2965 is obtained using some extra LaTeX code in Sphinx's own :file:`conf.py` 2966* #3770: Build fails when a "code-block" has the option emphasize-lines and the 2967 number indicated is higher than the number of lines 2968* #3774: Incremental HTML building broken when using citations 2969* #3763: got epubcheck validations error if epub_cover is set 2970* #3779: 'ImportError' in sphinx.ext.autodoc due to broken 'sys.meta_path'. 2971 Thanks to Tatiana Tereshchenko. 2972* #3796: env.resolve_references() crashes when non-document node given 2973* #3803: Sphinx crashes with invalid PO files 2974* #3791: PDF "continued on next page" for long tables isn't internationalized 2975* #3788: smartquotes emits warnings for unsupported languages 2976* #3807: latex Makefile for ``make latexpdf`` is only for unixen 2977* #3781: double hyphens in option directive are compiled as endashes 2978* #3817: latex builder raises AttributeError 2979 2980Release 1.6.1 (released May 16, 2017) 2981===================================== 2982 2983Dependencies 2984------------ 2985 29861.6b1 2987 2988* (updated) latex output is tested with Ubuntu trusty's texlive packages (Feb. 2989 2014) and earlier tex installations may not be fully compliant, particularly 2990 regarding Unicode engines xelatex and lualatex 2991* (added) latexmk is required for ``make latexpdf`` on GNU/Linux and Mac OS X 2992 (refs: #3082) 2993 2994Incompatible changes 2995-------------------- 2996 29971.6b1 2998 2999* #1061, #2336, #3235: Now generation of autosummary doesn't contain imported 3000 members by default. Thanks to Luc Saffre. 3001* LaTeX ``\includegraphics`` command isn't overloaded: only 3002 ``\sphinxincludegraphics`` has the custom code to fit image to available width 3003 if oversized. 3004* The subclasses of ``sphinx.domains.Index`` should override ``generate()`` 3005 method. The default implementation raises NotImplementedError 3006* LaTeX positioned long tables horizontally centered, and short ones 3007 flushed left (no text flow around table.) The position now defaults to center 3008 in both cases, and it will obey Docutils 0.13 ``:align:`` option (refs #3415, 3009 #3377) 3010* option directive also allows all punctuations for the option name (refs: 3011 #3366) 3012* #3413: if :rst:dir:`literalinclude`'s ``:start-after:`` is used, make 3013 ``:lines:`` relative (refs #3412) 3014* ``literalinclude`` directive does not allow the combination of ``:diff:`` 3015 option and other options (refs: #3416) 3016* LuaLaTeX engine uses ``fontspec`` like XeLaTeX. It is advised ``latex_engine 3017 = 'lualatex'`` be used only on up-to-date TeX installs (refs #3070, #3466) 3018* :confval:`latex_keep_old_macro_names` default value has been changed from 3019 ``True`` to ``False``. This means that some LaTeX macros for styling are 3020 by default defined only with ``\sphinx..`` prefixed names. (refs: #3429) 3021* Footer "Continued on next page" of LaTeX longtable's now not framed (refs: 3022 #3497) 3023* #3529: The arguments of ``BuildEnvironment.__init__`` is changed 3024* #3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms only) 3025* #3558: Emit warnings if footnotes and citations are not referenced. The 3026 warnings can be suppressed by ``suppress_warnings``. 3027* latex made available (non documented) colour macros from a file distributed 3028 with pdftex engine for Plain TeX. This is removed in order to provide better 3029 support for multiple TeX engines. Only interface from ``color`` or 3030 ``xcolor`` packages should be used by extensions of Sphinx latex writer. 3031 (refs #3550) 3032* ``Builder.env`` is not filled at instantiation 3033* #3594: LaTeX: single raw directive has been considered as block level element 3034* #3639: If ``html_experimental_html5_writer`` is available, epub builder use it 3035 by default. 3036* ``Sphinx.add_source_parser()`` raises an error if duplicated 3037 30381.6b2 3039 3040* #3345: Replace the custom smartypants code with Docutils' smart_quotes. 3041 Thanks to Dmitry Shachnev, and to Günter Milde at Docutils. 3042 30431.6b3 3044 3045* LaTeX package ``eqparbox`` is not used and not loaded by Sphinx anymore 3046* LaTeX package ``multirow`` is not used and not loaded by Sphinx anymore 3047* Add line numbers to citation data in std domain 3048 30491.6 final 3050 3051* LaTeX package ``threeparttable`` is not used and not loaded by Sphinx 3052 anymore (refs #3686, #3532, #3377) 3053 3054Features removed 3055---------------- 3056 3057* Configuration variables 3058 3059 - epub3_contributor 3060 - epub3_description 3061 - epub3_page_progression_direction 3062 - html_translator_class 3063 - html_use_modindex 3064 - latex_font_size 3065 - latex_paper_size 3066 - latex_preamble 3067 - latex_use_modindex 3068 - latex_use_parts 3069 3070* ``termsep`` node 3071* defindex.html template 3072* LDML format support in ``today``, ``today_fmt`` and ``html_last_updated_fmt`` 3073* ``:inline:`` option for the directives of sphinx.ext.graphviz extension 3074* sphinx.ext.pngmath extension 3075* ``sphinx.util.compat.make_admonition()`` 3076 3077Features added 3078-------------- 3079 30801.6b1 3081 3082* #3136: Add ``:name:`` option to the directives in ``sphinx.ext.graphviz`` 3083* #2336: Add ``imported_members`` option to ``sphinx-autogen`` command to 3084 document imported members. 3085* C++, add ``:tparam-line-spec:`` option to templated declarations. 3086 When specified, each template parameter will be rendered on a separate line. 3087* #3359: Allow sphinx.js in a user locale dir to override sphinx.js from Sphinx 3088* #3303: Add ``:pyversion:`` option to the doctest directive. 3089* #3378: (latex) support for ``:widths:`` option of table directives 3090 (refs: #3379, #3381) 3091* #3402: Allow to suppress "download file not readable" warnings using 3092 :confval:`suppress_warnings`. 3093* #3377: latex: Add support for Docutils 0.13 ``:align:`` option for tables 3094 (but does not implement text flow around table). 3095* latex: footnotes from inside tables are hyperlinked (except from captions or 3096 headers) (refs: #3422) 3097* Emit warning if over dedent has detected on ``literalinclude`` directive 3098 (refs: #3416) 3099* Use for LuaLaTeX same default settings as for XeLaTeX (i.e. ``fontspec`` and 3100 ``polyglossia``). (refs: #3070, #3466) 3101* Make ``'extraclassoptions'`` key of ``latex_elements`` public (refs #3480) 3102* #3463: Add warning messages for required EPUB3 metadata. Add default value to 3103 ``epub_description`` to avoid warning like other settings. 3104* #3476: setuptools: Support multiple builders 3105* latex: merged cells in LaTeX tables allow code-blocks, lists, blockquotes... 3106 as do normal cells (refs: #3435) 3107* HTML builder uses experimental HTML5 writer if 3108 ``html_experimental_html5_writer`` is True and docutils 0.13 or later is 3109 installed. 3110* LaTeX macros to customize space before and after tables in PDF output (refs 3111 #3504) 3112* #3348: Show decorators in literalinclude and viewcode directives 3113* #3108: Show warning if :start-at: and other literalinclude options does not 3114 match to the text 3115* #3609: Allow to suppress "duplicate citation" warnings using 3116 ``suppress_warnings`` 3117* #2803: Discovery of builders by entry point 3118* #1764, #1676: Allow setting 'rel' and 'title' attributes for stylesheets 3119* #3589: Support remote images on non-HTML builders 3120* #3589: Support images in Data URI on non-HTML builders 3121* #2961: improve :confval:`autodoc_mock_imports`. Now the config value only 3122 requires to declare the top-level modules that should be mocked. 3123 Thanks to Robin Jarry. 3124* #3449: On py3, autodoc use inspect.signature for more accurate signature 3125 calculation. Thanks to Nathaniel J. Smith. 3126* #3641: Epub theme supports HTML structures that are generated by HTML5 writer. 3127* #3644 autodoc uses inspect instead of checking types. Thanks to 3128 Jeroen Demeyer. 3129* Add a new extension; ``sphinx.ext.imgconverter``. It converts images in the 3130 document to appropriate format for builders 3131* latex: Use templates to render tables (refs #3389, 2a37b0e) 3132 31331.6b2 3134 3135* ``LATEXMKOPTS`` variable for the Makefile in ``$BUILDDIR/latex`` to pass 3136 options to ``latexmk`` when executing ``make latexpdf`` (refs #3695, #3720) 3137* Add a new event `env-check-consistency` to check consistency to extensions 3138* Add `Domain.check_consistency()` to check consistency 3139 3140Bugs fixed 3141---------- 3142 31431.6b1 3144 3145* ``literalinclude`` directive expands tabs after dedent-ing (refs: #3416) 3146* #1574: Paragraphs in table cell doesn't work in Latex output 3147* #3288: Table with merged headers not wrapping text 3148* #3491: Inconsistent vertical space around table and longtable in PDF 3149* #3506: Depart functions for all admonitions in HTML writer now properly pass 3150 ``node`` to ``depart_admonition``. 3151* #2693: Sphinx latex style file wrongly inhibits colours for section headings 3152 for latex+dvi(ps,pdf,pdfmx) 3153* C++, properly look up ``any`` references. 3154* #3624: sphinx.ext.intersphinx couldn't load inventories compressed with gzip 3155* #3551: PDF information dictionary is lacking author and title data 3156* #3351: intersphinx does not refers context like ``py:module``, ``py:class`` 3157 and so on. 3158* Fail to load template file if the parent template is archived 3159 31601.6b2 3161 3162* #3661: sphinx-build crashes on parallel build 3163* #3669: gettext builder fails with "ValueError: substring not found" 3164* #3660: Sphinx always depends on sphinxcontrib-websupport and its dependencies 3165* #3472: smart quotes getting wrong in latex (at least with list of strings via 3166 autoattribute) (refs: #3345, #3666) 3167 31681.6b3 3169 3170* #3588: No compact (p tag) html output in the i18n document build even when 3171 :confval:`html_compact_lists` is True. 3172* The ``make latexpdf`` from 1.6b1 (for GNU/Linux and Mac OS, using 3173 ``latexmk``) aborted earlier in case of LaTeX errors than was the case with 3174 1.5 series, due to hard-coded usage of ``--halt-on-error`` option (refs #3695) 3175* #3683: sphinx.websupport module is not provided by default 3176* #3683: Failed to build document if builder.css_file.insert() is called 3177* #3714: viewcode extension not taking ``highlight_code='none'`` in account 3178* #3698: Moving :doc: to std domain broke backwards compatibility 3179* #3633: misdetect unreferenced citations 3180 31811.6 final 3182 3183* LaTeX tables do not allow multiple paragraphs in a header cell 3184* LATEXOPTS is not passed over correctly to pdflatex since 1.6b3 3185* #3532: Figure or literal block captions in cells of short tables cause havoc 3186 in PDF output 3187* Fix: in PDF captions of tables are rendered differently whether table is of 3188 longtable class or not (refs #3686) 3189* #3725: Todo looks different from note in LaTeX output 3190* #3479: stub-columns have no effect in LaTeX output 3191* #3738: Nonsensical code in theming.py 3192* #3746: PDF builds fail with latexmk 4.48 or earlier due to undefined 3193 options ``-pdfxe`` and ``-pdflua`` 3194 3195Deprecated 3196---------- 3197 31981.6b1 3199 3200* ``sphinx.util.compat.Directive`` class is now deprecated. Please use instead 3201 ``docutils.parsers.rst.Directive`` 3202* ``sphinx.util.compat.docutils_version`` is now deprecated 3203* #2367: ``Sphinx.warn()``, ``Sphinx.info()`` and other logging methods are now 3204 deprecated. Please use ``sphinx.util.logging`` (:ref:`logging-api`) instead. 3205* #3318: ``notice`` is now deprecated as LaTeX environment name and will be 3206 removed at Sphinx 1.7. Extension authors please use ``sphinxadmonition`` 3207 instead (as Sphinx does since 1.5.) 3208* ``Sphinx.status_iterator()`` and ``Sphinx.old_status_iterator()`` is now 3209 deprecated. Please use ``sphinx.util:status_iterator()`` instead. 3210* ``Sphinx._directive_helper()`` is deprecated. Please use 3211 ``sphinx.util.docutils.directive_helper()`` instead. 3212* ``BuildEnvironment.set_warnfunc()`` is now deprecated 3213* Following methods of ``BuildEnvironment`` is now deprecated. 3214 3215 - ``BuildEnvironment.note_toctree()`` 3216 - ``BuildEnvironment.get_toc_for()`` 3217 - ``BuildEnvironment.get_toctree_for()`` 3218 - ``BuildEnvironment.create_index()`` 3219 3220 Please use ``sphinx.environment.adapters`` modules instead. 3221* latex package ``footnote`` is not loaded anymore by its bundled replacement 3222 ``footnotehyper-sphinx``. The redefined macros keep the same names as in the 3223 original package. 3224* #3429: deprecate config setting ``latex_keep_old_macro_names``. It will be 3225 removed at 1.7, and already its default value has changed from ``True`` to 3226 ``False``. 3227* #3221: epub2 builder is deprecated 3228* #3254: ``sphinx.websupport`` is now separated into independent package; 3229 ``sphinxcontrib-websupport``. ``sphinx.websupport`` will be removed in 3230 Sphinx-2.0. 3231* #3628: ``sphinx_themes`` entry_point is deprecated. Please use 3232 ``sphinx.html_themes`` instead. 3233 32341.6b2 3235 3236* #3662: ``builder.css_files`` is deprecated. Please use ``add_stylesheet()`` 3237 API instead. 3238 32391.6 final 3240 3241* LaTeX ``\sphinxstylethead`` is deprecated at 1.6 and will be removed at 1.7. 3242 Please move customization into new macro ``\sphinxstyletheadfamily``. 3243 3244Testing 3245-------- 3246 32471.6 final 3248 3249* #3458: Add ``sphinx.testing`` (experimental) 3250 3251Release 1.6 (unreleased) 3252======================== 3253 3254* not released (because of package script error) 3255 3256Release 1.5.6 (released May 15, 2017) 3257===================================== 3258 3259Bugs fixed 3260---------- 3261 3262* #3614: Sphinx crashes with requests-2.5.0 3263* #3618: autodoc crashes with tupled arguments 3264* #3664: No space after the bullet in items of a latex list produced by Sphinx 3265* #3657: EPUB builder crashes if a document starting with genindex exists 3266* #3588: No compact (p tag) html output in the i18n document build even when 3267 :confval:`html_compact_lists` is True. 3268* #3685: AttributeError when using 3rd party domains 3269* #3702: LaTeX writer styles figure legends with a hard-coded ``\small`` 3270* #3708: LaTeX writer allows irc scheme 3271* #3717: Stop enforcing that favicon's must be .ico 3272* #3731, #3732: Protect isenumclass predicate against non-class arguments 3273* #3320: Warning about reference target not being found for container types 3274* Misspelled ARCHIVEPREFIX in Makefile for latex build repertory 3275 3276Release 1.5.5 (released Apr 03, 2017) 3277===================================== 3278 3279Bugs fixed 3280---------- 3281 3282* #3597: python domain raises UnboundLocalError if invalid name given 3283* #3599: Move to new MathJax CDN 3284 3285Release 1.5.4 (released Apr 02, 2017) 3286===================================== 3287 3288Features added 3289-------------- 3290 3291* #3470: Make genindex support all kinds of letters, not only Latin ones 3292 3293Bugs fixed 3294---------- 3295 3296* #3445: setting ``'inputenc'`` key to ``\\usepackage[utf8x]{inputenc}`` leads 3297 to failed PDF build 3298* EPUB file has duplicated ``nav.xhtml`` link in ``content.opf`` 3299 except first time build 3300* #3488: objects.inv has broken when ``release`` or ``version`` contain 3301 return code 3302* #2073, #3443, #3490: gettext builder that writes pot files unless the content 3303 are same without creation date. Thanks to Yoshiki Shibukawa. 3304* #3487: intersphinx: failed to refer options 3305* #3496: latex longtable's last column may be much wider than its contents 3306* #3507: wrong quotes in latex output for productionlist directive 3307* #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of links 3308 rendered as code 3309* #2665, #2607: Link names in C++ docfields, and make it possible for other 3310 domains. 3311* #3542: C++, fix parsing error of non-type template argument with template. 3312* #3065, #3520: python domain fails to recognize nested class 3313* #3575: Problems with pdflatex in a Turkish document built with sphinx has 3314 reappeared (refs #2997, #2397) 3315* #3577: Fix intersphinx debug tool 3316* A LaTeX command such as ``\\large`` inserted in the title items of 3317 :confval:`latex_documents` causes failed PDF build (refs #3551, #3567) 3318 3319Release 1.5.3 (released Feb 26, 2017) 3320===================================== 3321 3322Features added 3323-------------- 3324 3325* Support requests-2.0.0 (experimental) (refs: #3367) 3326* (latex) PDF page margin dimensions may be customized (refs: #3387) 3327* ``literalinclude`` directive allows combination of ``:pyobject:`` and 3328 ``:lines:`` options (refs: #3416) 3329* #3400: make-mode doesn't use subprocess on building docs 3330 3331Bugs fixed 3332---------- 3333 3334* #3370: the caption of code-block is not picked up for translation 3335* LaTeX: :confval:`release` is not escaped (refs: #3362) 3336* #3364: sphinx-quickstart prompts overflow on Console with 80 chars width 3337* since 1.5, PDF's TOC and bookmarks lack an entry for general Index 3338 (refs: #3383) 3339* #3392: ``'releasename'`` in :confval:`latex_elements` is not working 3340* #3356: Page layout for Japanese ``'manual'`` docclass has a shorter text area 3341* #3394: When ``'pointsize'`` is not ``10pt``, Japanese ``'manual'`` document 3342 gets wrong PDF page dimensions 3343* #3399: quickstart: conf.py was not overwritten by template 3344* #3366: option directive does not allow punctuations 3345* #3410: return code in :confval:`release` breaks html search 3346* #3427: autodoc: memory addresses are not stripped on Windows 3347* #3428: xetex build tests fail due to fontspec v2.6 defining ``\strong`` 3348* #3349: Result of ``IndexBuilder.load()`` is broken 3349* #3450:   is appeared in EPUB docs 3350* #3418: Search button is misaligned in nature and pyramid theme 3351* #3421: Could not translate a caption of tables 3352* #3552: linkcheck raises UnboundLocalError 3353 3354Release 1.5.2 (released Jan 22, 2017) 3355===================================== 3356 3357Incompatible changes 3358-------------------- 3359 3360* Dependency requirement updates: requests 2.4.0 or above (refs: #3268, #3310) 3361 3362Features added 3363-------------- 3364 3365* #3241: emit latex warning if buggy titlesec (ref #3210) 3366* #3194: Refer the $MAKE environment variable to determine ``make`` command 3367* Emit warning for nested numbered toctrees (refs: #3142) 3368* #978: `intersphinx_mapping` also allows a list as a parameter 3369* #3340: (LaTeX) long lines in :dudir:`parsed-literal` are wrapped like in 3370 :rst:dir:`code-block`, inline math and footnotes are fully functional. 3371 3372Bugs fixed 3373---------- 3374 3375* #3246: xapian search adapter crashes 3376* #3253: In Py2 environment, building another locale with a non-captioned 3377 toctree produces ``None`` captions 3378* #185: References to section title including raw node has broken 3379* #3255: In Py3.4 environment, autodoc doesn't support documentation for 3380 attributes of Enum class correctly. 3381* #3261: ``latex_use_parts`` makes sphinx crash 3382* The warning type ``misc.highlighting_failure`` does not work 3383* #3294: ``add_latex_package()`` make crashes non-LaTeX builders 3384* The caption of table are rendered as invalid HTML (refs: #3287) 3385* #3268: Sphinx crashes with requests package from Debian jessie 3386* #3284: Sphinx crashes on parallel build with an extension which raises 3387 unserializable exception 3388* #3315: Bibliography crashes on latex build with docclass 'memoir' 3389* #3328: Could not refer rubric implicitly 3390* #3329: emit warnings if po file is invalid and can't read it. Also writing mo 3391* #3337: Ugly rendering of definition list term's classifier 3392* #3335: gettext does not extract field_name of a field in a field_list 3393* #2952: C++, fix refs to operator() functions. 3394* Fix Unicode super- and subscript digits in :rst:dir:`code-block` and 3395 parsed-literal LaTeX output (ref #3342) 3396* LaTeX writer: leave ``"`` character inside parsed-literal as is (ref #3341) 3397* #3234: intersphinx failed for encoded inventories 3398* #3158: too much space after captions in PDF output 3399* #3317: An URL in parsed-literal contents gets wrongly rendered in PDF if 3400 with hyphen 3401* LaTeX crash if the filename of an image inserted in parsed-literal 3402 via a substitution contains an hyphen (ref #3340) 3403* LaTeX rendering of inserted footnotes in parsed-literal is wrong (ref #3340) 3404* Inline math in parsed-literal is not rendered well by LaTeX (ref #3340) 3405* #3308: Parsed-literals don't wrap very long lines with pdf builder (ref #3340) 3406* #3295: Could not import extension sphinx.builders.linkcheck 3407* #3285: autosummary: asterisks are escaped twice 3408* LaTeX, pass dvipdfm option to geometry package for Japanese documents (ref 3409 #3363) 3410* Fix parselinenos() could not parse left half open range (cf. "-4") 3411 3412 3413Release 1.5.1 (released Dec 13, 2016) 3414===================================== 3415 3416Features added 3417-------------- 3418 3419* #3214: Allow to suppress "unknown mimetype" warnings from epub builder using 3420 :confval:`suppress_warnings`. 3421 3422Bugs fixed 3423---------- 3424 3425* #3195: Can not build in parallel 3426* #3198: AttributeError is raised when toctree has 'self' 3427* #3211: Remove untranslated sphinx locale catalogs (it was covered by 3428 untranslated it_IT) 3429* #3212: HTML Builders crashes with docutils-0.13 3430* #3207: more latex problems with references inside parsed-literal directive 3431 (``\DUrole``) 3432* #3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14) 3433* #3220: KeyError when having a duplicate citation 3434* #3200: LaTeX: xref inside desc_name not allowed 3435* #3228: ``build_sphinx`` command crashes when missing dependency 3436* #2469: Ignore updates of catalog files for gettext builder. Thanks to 3437 Hiroshi Ohkubo. 3438* #3183: Randomized jump box order in generated index page. 3439 3440Release 1.5 (released Dec 5, 2016) 3441================================== 3442 3443Incompatible changes 3444-------------------- 3445 34461.5a1 3447 3448* latex, package fancybox is not any longer a dependency of sphinx.sty 3449* Use ``'locales'`` as a default value of `locale_dirs` 3450* latex, package ifthen is not any longer a dependency of sphinx.sty 3451* latex, style file does not modify fancyvrb's Verbatim (also available as 3452 OriginalVerbatim) but uses sphinxVerbatim for name of custom wrapper. 3453* latex, package newfloat is not used (and not included) anymore (ref #2660; 3454 it was used since 1.3.4 and shipped with Sphinx since 1.4). 3455* latex, literal blocks in tables do not use OriginalVerbatim but 3456 sphinxVerbatimintable which handles captions and wraps lines (ref #2704). 3457* latex, replace ``pt`` by TeX equivalent ``bp`` if found in ``width`` or 3458 ``height`` attribute of an image. 3459* latex, if ``width`` or ``height`` attribute of an image is given with no unit, 3460 use ``px`` rather than ignore it. 3461* latex: Separate stylesheets of pygments to independent .sty file 3462* #2454: The filename of sourcelink is now changed. The value of 3463 `html_sourcelink_suffix` will be appended to the original filename (like 3464 ``index.rst.txt``). 3465* ``sphinx.util.copy_static_entry()`` is now deprecated. 3466 Use ``sphinx.util.fileutil.copy_asset()`` instead. 3467* ``sphinx.util.osutil.filecopy()`` skips copying if the file has not been 3468 changed (ref: #2510, #2753) 3469* Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped 3470 because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634, #2773) 3471* QtHelpBuilder doesn't generate search page (ref: #2352) 3472* QtHelpBuilder uses ``nonav`` theme instead of default one 3473 to improve readability. 3474* latex: To provide good default settings to Japanese documents, Sphinx uses 3475 ``jreport`` and ``jsbook`` as docclass if :confval:`language` is 3476 ``ja``. 3477* ``sphinx-quickstart`` now allows a project version is empty 3478* Fix :download: role on epub/qthelp builder. They ignore the role because they 3479 don't support it. 3480* ``sphinx.ext.viewcode`` doesn't work on epub building by default. 3481 ``viewcode_enable_epub`` option 3482* ``sphinx.ext.viewcode`` disabled on singlehtml builder. 3483* Use make-mode of ``sphinx-quickstart`` by default. To disable this, use 3484 ``-M`` option 3485* Fix ``genindex.html``, Sphinx's document template, link address to itself to 3486 satisfy xhtml standard. 3487* Use epub3 builder by default. And the old epub builder is renamed to epub2. 3488* Fix ``epub`` and ``epub3`` builders that contained links to ``genindex`` even 3489 if ``epub_use_index = False``. 3490* ``html_translator_class`` is now deprecated. 3491 Use `Sphinx.set_translator()` API instead. 3492* Drop python 2.6 and 3.3 support 3493* Drop epub3 builder's ``epub3_page_progression_direction`` option (use 3494 ``epub3_writing_mode``). 3495* #2877: Rename ``latex_elements['footer']`` to 3496 ``latex_elements['atendofbody']`` 3497 34981.5a2 3499 3500* #2983: Rename ``epub3_description`` and ``epub3_contributor`` to 3501 ``epub_description`` and ``epub_contributor``. 3502* Remove themes/basic/defindex.html; no longer used 3503* Sphinx does not ship anymore (but still uses) LaTeX style file ``fncychap`` 3504* #2435: Slim down quickstarted conf.py 3505* The ``sphinx.sty`` latex package does not load itself "hyperref", as this 3506 is done later in the preamble of the latex output via ``'hyperref'`` key. 3507* Sphinx does not ship anymore a custom modified LaTeX style file ``tabulary``. 3508 The non-modified package is used. 3509* #3057: By default, footnote marks in latex PDF output are not preceded by a 3510 space anymore, ``\sphinxBeforeFootnote`` allows user customization if needed. 3511* LaTeX target requires that option ``hyperfootnotes`` of package ``hyperref`` 3512 be left unchanged to its default (i.e. ``true``) (refs: #3022) 3513 35141.5 final 3515 3516* #2986: ``themes/basic/defindex.html`` is now deprecated 3517* Emit warnings that will be deprecated in Sphinx 1.6 by default. 3518 Users can change the behavior by setting the environment variable 3519 PYTHONWARNINGS. Please refer :ref:`when-deprecation-warnings-are-displayed`. 3520* #2454: new JavaScript variable ``SOURCELINK_SUFFIX`` is added 3521 3522Deprecated 3523---------- 3524 3525These features are removed in Sphinx-1.6: 3526 3527* LDML format support in i18n feature 3528* ``sphinx.addnodes.termsep`` 3529* Some functions and classes in ``sphinx.util.pycompat``: 3530 ``zip_longest``, ``product``, ``all``, ``any``, ``next``, ``open``, 3531 ``class_types``, ``base_exception``, ``relpath``, ``StringIO``, ``BytesIO``. 3532 Please use the standard library version instead; 3533 3534If any deprecation warning like ``RemovedInSphinxXXXWarning`` are displayed, 3535please refer :ref:`when-deprecation-warnings-are-displayed`. 3536 3537Features added 3538-------------- 3539 35401.5a1 3541 3542* #2951: Add ``--implicit-namespaces`` PEP-0420 support to apidoc. 3543* Add ``:caption:`` option for sphinx.ext.inheritance_diagram. 3544* #2471: Add config variable for default doctest flags. 3545* Convert linkcheck builder to requests for better encoding handling 3546* #2463, #2516: Add keywords of "meta" directive to search index 3547* ``:maxdepth:`` option of toctree affects ``secnumdepth`` (ref: #2547) 3548* #2575: Now ``sphinx.ext.graphviz`` allows ``:align:`` option 3549* Show warnings if unknown key is specified to `latex_elements` 3550* Show warnings if no domains match with `primary_domain` (ref: #2001) 3551* C++, show warnings when the kind of role is misleading for the kind 3552 of target it refers to (e.g., using the `class` role for a function). 3553* latex, writer abstracts more of text styling into customizable macros, e.g. 3554 the ``visit_emphasis`` will output ``\sphinxstyleemphasis`` rather than 3555 ``\emph`` (which may be in use elsewhere or in an added LaTeX package). See 3556 list at end of ``sphinx.sty`` (ref: #2686) 3557* latex, public names for environments and parameters used by note, warning, 3558 and other admonition types, allowing full customizability from the 3559 ``'preamble'`` key or an input file (ref: feature request #2674, #2685) 3560* latex, better computes column widths of some tables (as a result, there will 3561 be slight changes as tables now correctly fill the line width; ref: #2708) 3562* latex, sphinxVerbatim environment is more easily customizable (ref: #2704). 3563 In addition to already existing VerbatimColor and VerbatimBorderColor: 3564 3565 - two lengths ``\sphinxverbatimsep`` and ``\sphinxverbatimborder``, 3566 - booleans ``\ifsphinxverbatimwithframe`` and ``\ifsphinxverbatimwrapslines``. 3567 3568* latex, captions for literal blocks inside tables are handled, and long code 3569 lines wrapped to fit table cell (ref: #2704) 3570* #2597: Show warning messages as darkred 3571* latex, allow image dimensions using px unit (default is 96px=1in) 3572* Show warnings if invalid dimension units found 3573* #2650: Add ``--pdb`` option to setup.py command 3574* latex, make the use of ``\small`` for code listings customizable (ref #2721) 3575* #2663: Add ``--warning-is-error`` option to setup.py command 3576* Show warnings if deprecated latex options are used 3577* Add sphinx.config.ENUM to check the config values is in candidates 3578* math: Add hyperlink marker to each equations in HTML output 3579* Add new theme ``nonav`` that doesn't include any navigation links. 3580 This is for any help generator like qthelp. 3581* #2680: `sphinx.ext.todo` now emits warnings if `todo_emit_warnings` enabled. 3582 Also, it emits an additional event named `todo-defined` to handle the TODO 3583 entries in 3rd party extensions. 3584* Python domain signature parser now uses the xref mixin for 'exceptions', 3585 allowing exception classes to be autolinked. 3586* #2513: Add `latex_engine` to switch the LaTeX engine by conf.py 3587* #2682: C++, basic support for attributes (C++11 style and GNU style). 3588 The new configuration variables 'cpp_id_attributes' and 'cpp_paren_attributes' 3589 can be used to introduce custom attributes. 3590* #1958: C++, add configuration variable 'cpp_index_common_prefix' for removing 3591 prefixes from the index text of C++ objects. 3592* C++, added concept directive. Thanks to mickk-on-cpp. 3593* C++, added support for template introduction syntax. Thanks to mickk-on-cpp. 3594* #2725: latex builder: allow to use user-defined template file (experimental) 3595* apidoc now avoids invalidating cached files by not writing to files whose 3596 content doesn't change. This can lead to significant performance wins if 3597 apidoc is run frequently. 3598* #2851: ``sphinx.ext.math`` emits missing-reference event if equation not found 3599* #1210: ``eqref`` role now supports cross reference 3600* #2892: Added ``-a`` (``--append-syspath``) option to ``sphinx-apidoc`` 3601* #1604: epub3 builder: Obey font-related CSS when viewing in iBooks. 3602* #646: ``option`` directive support '.' character as a part of options 3603* Add document about kindlegen and fix document structure for it. 3604* #2474: Add ``intersphinx_timeout`` option to ``sphinx.ext.intersphinx`` 3605* #2926: EPUB3 builder supports vertical mode (``epub3_writing_mode`` option) 3606* #2695: ``build_sphinx`` subcommand for setuptools handles exceptions as same 3607 as ``sphinx-build`` does 3608* #326: `numref` role can also refer sections 3609* #2916: `numref` role can also refer caption as an its linktext 3610 36111.5a2 3612 3613* #3008: ``linkcheck`` builder ignores self-signed certificate URL 3614* #3020: new ``'geometry'`` key to ``latex_elements`` whose default uses 3615 LaTeX style file ``geometry.sty`` to set page layout 3616* #2843: Add :start-at: and :end-at: options to literalinclude directive 3617* #2527: Add ``:reversed:`` option to toctree directive 3618* Add ``-t`` and ``-d`` option to ``sphinx-quickstart`` to support templating 3619 generated sphinx project. 3620* #3028: Add ``{path}`` and ``{basename}`` to the format of 3621 ``figure_language_filename`` 3622* new ``'hyperref'`` key in the ``latex_elements`` dictionary (ref #3030) 3623* #3022: Allow code-blocks in footnotes for LaTeX PDF output 3624 36251.5b1 3626 3627* #2513: A better default settings for XeLaTeX 3628* #3096: ``'maxlistdepth'`` key to work around LaTeX list limitations 3629* #3060: autodoc supports documentation for attributes of Enum class. Now 3630 autodoc render just the value of Enum attributes instead of Enum attribute 3631 representation. 3632* Add ``--extensions`` to ``sphinx-quickstart`` to support enable arbitrary 3633 extensions from command line (ref: #2904) 3634* #3104, #3122: ``'sphinxsetup'`` for key=value styling of Sphinx LaTeX 3635* #3071: Autodoc: Allow mocked module decorators to pass-through functions 3636 unchanged 3637* #2495: linkcheck: Allow skipping anchor checking using 3638 :confval:`linkcheck_anchors_ignore` 3639* #3083: let Unicode no-break space act like LaTeX ``~`` (fixed #3019) 3640* #3116: allow word wrap in PDF output for inline literals (ref #3110) 3641* #930: sphinx-apidoc allow wildcards for excluding paths. Thanks to Nick 3642 Coghlan. 3643* #3121: add ``inlineliteralwraps`` option to control if inline literal 3644 word-wraps in latex 3645 36461.5 final 3647 3648* #3095: Add :confval:`tls_verify` and :confval:`tls_cacerts` to support 3649 self-signed HTTPS servers in linkcheck and intersphinx 3650* #2215: make.bat generated by sphinx-quickstart can be called from another dir. 3651 Thanks to Timotheus Kampik. 3652* #3185: Add new warning type ``misc.highlighting_failure`` 3653 3654Bugs fixed 3655---------- 3656 36571.5a1 3658 3659* #2707: (latex) the column width is badly computed for tabular 3660* #2799: Sphinx installs roles and directives automatically on importing sphinx 3661 module. Now Sphinx installs them on running application. 3662* `sphinx.ext.autodoc` crashes if target code imports * from mock modules 3663 by `autodoc_mock_imports`. 3664* #1953: ``Sphinx.add_node`` does not add handlers the translator installed by 3665 ``html_translator_class`` 3666* #1797: text builder inserts blank line on top 3667* #2894: quickstart main() doesn't use argv argument 3668* #2874: gettext builder could not extract all text under the ``only`` 3669 directives 3670* #2485: autosummary crashes with multiple source_suffix values 3671* #1734: Could not translate the caption of toctree directive 3672* Could not translate the content of meta directive (ref: #1734) 3673* #2550: external links are opened in help viewer 3674* #2687: Running Sphinx multiple times produces 'already registered' warnings 3675 36761.5a2 3677 3678* #2810: Problems with pdflatex in an Italian document 3679* Use ``latex_elements.papersize`` to specify papersize of LaTeX in Makefile 3680* #2988: linkcheck: retry with GET request if denied HEAD request 3681* #2990: linkcheck raises "Can't convert 'bytes' object to str implicitly" error 3682 if linkcheck_anchors enabled 3683* #3004: Invalid link types "top" and "up" are used 3684* #3009: Bad rendering of parsed-literals in LaTeX since Sphinx 1.4.4 3685* #3000: ``option`` directive generates invalid HTML anchors 3686* #2984: Invalid HTML has been generated if `html_split_index` enabled 3687* #2986: themes/basic/defindex.html should be changed for html5 friendly 3688* #2987: Invalid HTML has been generated if multiple IDs are assigned to a list 3689* #2891: HTML search does not provide all the results 3690* #1986: Title in PDF Output 3691* #147: Problem with latex chapter style 3692* #3018: LaTeX problem with page layout dimensions and chapter titles 3693* Fix an issue with ``\pysigline`` in LaTeX style file (ref #3023) 3694* #3038: ``sphinx.ext.math*`` raises TypeError if labels are duplicated 3695* #3031: incompatibility with LaTeX package ``tocloft`` 3696* #3003: literal blocks in footnotes are not supported by Latex 3697* #3047: spacing before footnote in pdf output is not coherent and allows breaks 3698* #3045: HTML search index creator should ignore "raw" content if now html 3699* #3039: English stemmer returns wrong word if the word is capitalized 3700* Fix make-mode Makefile template (ref #3056, #2936) 3701 37021.5b1 3703 3704* #2432: Fix unwanted * between varargs and keyword only args. Thanks to Alex 3705 Grönholm. 3706* #3062: Failed to build PDF using 1.5a2 (undefined ``\hypersetup`` for 3707 Japanese documents since PR#3030) 3708* Better rendering of multiline signatures in html. 3709* #777: LaTeX output "too deeply nested" (ref #3096) 3710* Let LaTeX image inclusion obey ``scale`` before textwidth fit (ref #2865, 3711 #3059) 3712* #3019: LaTeX fails on description of C function with arguments (ref #3083) 3713* fix latex inline literals where ``< > -`` gobbled a space 3714 37151.5 final 3716 3717* #3069: Even if ``'babel'`` key is set to empty string, LaTeX output contains 3718 one ``\addto\captions...`` 3719* #3123: user ``'babel'`` key setting is not obeyed anymore 3720* #3155: Fix JavaScript for `html_sourcelink_suffix` fails with IE and Opera 3721* #3085: keep current directory after breaking build documentation. Thanks to 3722 Timotheus Kampik. 3723* #3181: pLaTeX crashes with a section contains endash 3724* #3180: latex: add stretch/shrink between successive singleline or 3725 multipleline cpp signatures (ref #3072) 3726* #3128: globing images does not support .svgz file 3727* #3015: fix a broken test on Windows. 3728* #1843: Fix documentation of descriptor classes that have a custom metaclass. 3729 Thanks to Erik Bray. 3730* #3190: util.split_docinfo fails to parse multi-line field bodies 3731* #3024, #3037: In Python3, application.Sphinx._log crushed when the log message 3732 cannot be encoded into console encoding. 3733 3734Testing 3735-------- 3736 3737* To simplify, sphinx uses external mock package even if unittest.mock exists. 3738 3739 3740Release 1.4.9 (released Nov 23, 2016) 3741===================================== 3742 3743Bugs fixed 3744---------- 3745 3746* #2936: Fix doc/Makefile that can't build man because doc/man exists 3747* #3058: Using the same 'caption' attribute in multiple 'toctree' directives 3748 results in warning / error 3749* #3068: Allow the '=' character in the -D option of sphinx-build.py 3750* #3074: ``add_source_parser()`` crashes in debug mode 3751* #3135: ``sphinx.ext.autodoc`` crashes with plain Callable 3752* #3150: Fix query word splitter in JavaScript. It behaves as same as Python's 3753 regular expression. 3754* #3093: gettext build broken on substituted images. 3755* #3093: gettext build broken on image node under ``note`` directive. 3756* imgmath: crashes on showing error messages if image generation failed 3757* #3117: LaTeX writer crashes if admonition is placed before first section title 3758* #3164: Change search order of ``sphinx.ext.inheritance_diagram`` 3759 3760Release 1.4.8 (released Oct 1, 2016) 3761==================================== 3762 3763Bugs fixed 3764---------- 3765 3766* #2996: The wheel package of Sphinx got crash with ImportError 3767 3768Release 1.4.7 (released Oct 1, 2016) 3769==================================== 3770 3771Bugs fixed 3772---------- 3773 3774* #2890: Quickstart should return an error consistently on all error conditions 3775* #2870: flatten genindex columns' heights. 3776* #2856: Search on generated HTML site doesn't find some symbols 3777* #2882: Fall back to a GET request on 403 status in linkcheck 3778* #2902: jsdump.loads fails to load search index if keywords starts with 3779 underscore 3780* #2900: Fix epub content.opf: add auto generated orphan files to spine. 3781* #2899: Fix ``hasdoc()`` function in Jinja2 template. It will detect 3782 ``genindex``, ``search`` also. 3783* #2901: Fix epub result: skip creating links from image tags to original image 3784 files. 3785* #2917: inline code is hyphenated on HTML 3786* #1462: autosummary warns for namedtuple with attribute with trailing 3787 underscore 3788* Could not reference equations if ``:nowrap:`` option specified 3789* #2873: code-block overflow in latex (due to commas) 3790* #1060, #2056: sphinx.ext.intersphinx: broken links are generated if relative 3791 paths are used in `intersphinx_mapping` 3792* #2931: code-block directive with same :caption: causes warning of duplicate 3793 target. Now `code-block` and `literalinclude` does not define hyperlink 3794 target using its caption automatically. 3795* #2962: latex: missing label of longtable 3796* #2968: autodoc: show-inheritance option breaks docstrings 3797 3798Release 1.4.6 (released Aug 20, 2016) 3799===================================== 3800 3801Incompatible changes 3802-------------------- 3803 3804* #2867: linkcheck builder crashes with six-1.4. Now Sphinx depends on six-1.5 3805 or later 3806 3807Bugs fixed 3808---------- 3809 3810* applehelp: Sphinx crashes if ``hiutil`` or ``codesign`` commands not found 3811* Fix ``make clean`` abort issue when build dir contains regular files like 3812 ``DS_Store``. 3813* Reduce epubcheck warnings/errors: 3814 3815 * Fix DOCTYPE to html5 3816 * Change extension from .html to .xhtml. 3817 * Disable search page on epub results 3818 3819* #2778: Fix autodoc crashes if obj.__dict__ is a property method and raises 3820 exception 3821* Fix duplicated toc in epub3 output. 3822* #2775: Fix failing linkcheck with servers not supporting identity encoding 3823* #2833: Fix formatting instance annotations in ext.autodoc. 3824* #1911: ``-D`` option of ``sphinx-build`` does not override the ``extensions`` 3825 variable 3826* #2789: `sphinx.ext.intersphinx` generates wrong hyperlinks if the inventory is 3827 given 3828* parsing errors for caption of code-blocks are displayed in document 3829 (ref: #2845) 3830* #2846: ``singlehtml`` builder does not include figure numbers 3831* #2816: Fix data from builds cluttering the ``Domain.initial_data`` class 3832 attributes 3833 3834Release 1.4.5 (released Jul 13, 2016) 3835===================================== 3836 3837Incompatible changes 3838-------------------- 3839 3840* latex, inclusion of non-inline images from image directive resulted in 3841 non-coherent whitespaces depending on original image width; new behaviour 3842 by necessity differs from earlier one in some cases. (ref: #2672) 3843* latex, use of ``\includegraphics`` to refer to Sphinx custom variant is 3844 deprecated; in future it will revert to original LaTeX macro, custom one 3845 already has alternative name ``\sphinxincludegraphics``. 3846 3847Features added 3848-------------- 3849 3850* new config option ``latex_keep_old_macro_names``, defaults to True. If False, 3851 lets macros (for text styling) be defined only with ``\sphinx``-prefixed names 3852* latex writer allows user customization of "shadowed" boxes (topics), via 3853 three length variables. 3854* woff-format web font files now supported by the epub builder. 3855 3856Bugs fixed 3857---------- 3858 3859* jsdump fix for python 3: fixes the HTML search on python > 3 3860* #2676: (latex) Error with verbatim text in captions since Sphinx 1.4.4 3861* #2629: memoir class crashes LaTeX. Fixed by 3862 ``latex_keep_old_macro_names=False`` (ref 2675) 3863* #2684: `sphinx.ext.intersphinx` crashes with six-1.4.1 3864* #2679: ``float`` package needed for ``'figure_align': 'H'`` latex option 3865* #2671: image directive may lead to inconsistent spacing in pdf 3866* #2705: ``toctree`` generates empty bullet_list if ``:titlesonly:`` specified 3867* #2479: `sphinx.ext.viewcode` uses python2 highlighter by default 3868* #2700: HtmlHelp builder has hard coded index.html 3869* latex, since 1.4.4 inline literal text is followed by spurious space 3870* #2722: C++, fix id generation for var/member declarations to include 3871 namespaces. 3872* latex, images (from image directive) in lists or quoted blocks did not obey 3873 indentation (fixed together with #2671) 3874* #2733: since Sphinx-1.4.4 ``make latexpdf`` generates lots of hyperref 3875 warnings 3876* #2731: `sphinx.ext.autodoc` does not access propertymethods which raises any 3877 exceptions 3878* #2666: C++, properly look up nested names involving constructors. 3879* #2579: Could not refer a label including both spaces and colons via 3880 `sphinx.ext.intersphinx` 3881* #2718: Sphinx crashes if the document file is not readable 3882* #2699: hyperlinks in help HTMLs are broken if `html_file_suffix` is set 3883* #2723: extra spaces in latex pdf output from multirow cell 3884* #2735: latexpdf ``Underfull \hbox (badness 10000)`` warnings from title page 3885* #2667: latex crashes if resized images appeared in section title 3886* #2763: (html) Provide default value for required ``alt`` attribute for image 3887 tags of SVG source, required to validate and now consistent w/ other formats. 3888 3889 3890Release 1.4.4 (released Jun 12, 2016) 3891===================================== 3892 3893Bugs fixed 3894---------- 3895 3896* #2630: latex: sphinx.sty notice environment formatting problem 3897* #2632: Warning directives fail in quote environment latex build 3898* #2633: Sphinx crashes with old styled indices 3899* Fix a ``\begin{\minipage}`` typo in sphinx.sty from 1.4.2 (ref: 68becb1) 3900* #2622: Latex produces empty pages after title and table of contents 3901* #2640: 1.4.2 LaTeX crashes if code-block inside warning directive 3902* Let LaTeX use straight quotes also in inline code (ref #2627) 3903* #2351: latex crashes if enumerated lists are placed on footnotes 3904* #2646: latex crashes if math contains twice empty lines 3905* #2480: `sphinx.ext.autodoc`: memory addresses were shown 3906* latex: allow code-blocks appearing inside lists and quotes at maximal nesting 3907 depth (ref #777, #2624, #2651) 3908* #2635: Latex code directives produce inconsistent frames based on viewing 3909 resolution 3910* #2639: Sphinx now bundles iftex.sty 3911* Failed to build PDF with framed.sty 0.95 3912* Sphinx now bundles needspace.sty 3913 3914 3915Release 1.4.3 (released Jun 5, 2016) 3916==================================== 3917 3918Bugs fixed 3919---------- 3920 3921* #2530: got "Counter too large" error on building PDF if large numbered 3922 footnotes existed in admonitions 3923* ``width`` option of figure directive does not work if ``align`` option 3924 specified at same time (ref: #2595) 3925* #2590: The ``inputenc`` package breaks compiling under lualatex and xelatex 3926* #2540: date on latex front page use different font 3927* Suppress "document isn't included in any toctree" warning if the document is 3928 included (ref: #2603) 3929* #2614: Some tables in PDF output will end up shifted if user sets non zero 3930 \parindent in preamble 3931* #2602: URL redirection breaks the hyperlinks generated by 3932 `sphinx.ext.intersphinx` 3933* #2613: Show warnings if merged extensions are loaded 3934* #2619: make sure amstext LaTeX package always loaded (ref: d657225, 488ee52, 3935 9d82cad and #2615) 3936* #2593: latex crashes if any figures in the table 3937 3938 3939Release 1.4.2 (released May 29, 2016) 3940===================================== 3941 3942Features added 3943-------------- 3944 3945* Now :confval:`suppress_warnings` accepts following configurations 3946 (ref: #2451, #2466): 3947 3948 - ``app.add_node`` 3949 - ``app.add_directive`` 3950 - ``app.add_role`` 3951 - ``app.add_generic_role`` 3952 - ``app.add_source_parser`` 3953 - ``image.data_uri`` 3954 - ``image.nonlocal_uri`` 3955 3956* #2453: LaTeX writer allows page breaks in topic contents; and their 3957 horizontal extent now fits in the line width (with shadow in margin). Also 3958 warning-type admonitions allow page breaks and their vertical spacing has 3959 been made more coherent with the one for hint-type notices (ref #2446). 3960 3961* #2459: the framing of literal code-blocks in LaTeX output (and not only the 3962 code lines themselves) obey the indentation in lists or quoted blocks. 3963 3964* #2343: the long source lines in code-blocks are wrapped (without modifying 3965 the line numbering) in LaTeX output (ref #1534, #2304). 3966 3967Bugs fixed 3968---------- 3969 3970* #2370: the equations are slightly misaligned in LaTeX writer 3971* #1817, #2077: suppress pep8 warnings on conf.py generated by sphinx-quickstart 3972* #2407: building docs crash if document includes large data image URIs 3973* #2436: Sphinx does not check version by :confval:`needs_sphinx` if loading 3974 extensions failed 3975* #2397: Setup shorthandoff for Turkish documents 3976* #2447: VerbatimBorderColor wrongly used also for captions of PDF 3977* #2456: C++, fix crash related to document merging (e.g., singlehtml and Latex 3978 builders). 3979* #2446: latex(pdf) sets local tables of contents (or more generally topic 3980 nodes) in unbreakable boxes, causes overflow at bottom 3981* #2476: Omit MathJax markers if :nowrap: is given 3982* #2465: latex builder fails in case no caption option is provided to toctree 3983 directive 3984* Sphinx crashes if self referenced toctree found 3985* #2481: spelling mistake for mecab search splitter. Thanks to Naoki Sato. 3986* #2309: Fix could not refer "indirect hyperlink targets" by ref-role 3987* intersphinx fails if mapping URL contains any port 3988* #2088: intersphinx crashes if the mapping URL requires basic auth 3989* #2304: auto line breaks in latexpdf codeblocks 3990* #1534: Word wrap long lines in Latex verbatim blocks 3991* #2460: too much white space on top of captioned literal blocks in PDF output 3992* Show error reason when multiple math extensions are loaded (ref: #2499) 3993* #2483: any figure number was not assigned if figure title contains only non 3994 text objects 3995* #2501: Unicode subscript numbers are normalized in LaTeX 3996* #2492: Figure directive with :figwidth: generates incorrect Latex-code 3997* The caption of figure is always put on center even if ``:align:`` was 3998 specified 3999* #2526: LaTeX writer crashes if the section having only images 4000* #2522: Sphinx touches mo files under installed directory that caused 4001 permission error. 4002* #2536: C++, fix crash when an immediately nested scope has the same name as 4003 the current scope. 4004* #2555: Fix crash on any-references with unicode. 4005* #2517: wrong bookmark encoding in PDF if using LuaLaTeX 4006* #2521: generated Makefile causes BSD make crashed if sphinx-build not found 4007* #2470: ``typing`` backport package causes autodoc errors with python 2.7 4008* ``sphinx.ext.intersphinx`` crashes if non-string value is used for key of 4009 `intersphinx_mapping` 4010* #2518: `intersphinx_mapping` disallows non alphanumeric keys 4011* #2558: unpack error on devhelp builder 4012* #2561: Info builder crashes when a footnote contains a link 4013* #2565: The descriptions of objects generated by ``sphinx.ext.autosummary`` 4014 overflow lines at LaTeX writer 4015* Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551) 4016* #2445: `rst_prolog` and `rst_epilog` affect to non reST sources 4017* #2576: ``sphinx.ext.imgmath`` crashes if subprocess raises error 4018* #2577: ``sphinx.ext.imgmath``: Invalid argument are passed to dvisvgm 4019* #2556: Xapian search does not work with Python 3 4020* #2581: The search doesn't work if language="es" (Spanish) 4021* #2382: Adjust spacing after abbreviations on figure numbers in LaTeX writer 4022* #2383: The generated footnote by `latex_show_urls` overflows lines 4023* #2497, #2552: The label of search button does not fit for the button itself 4024 4025 4026Release 1.4.1 (released Apr 12, 2016) 4027===================================== 4028 4029Incompatible changes 4030-------------------- 4031 4032* The default format of `today_fmt` and `html_last_updated_fmt` is back to 4033 strftime format again. Locale Date Markup Language is also supported for 4034 backward compatibility until Sphinx-1.5. 4035 4036Translations 4037------------ 4038 4039* Added Welsh translation, thanks to Geraint Palmer. 4040* Added Greek translation, thanks to Stelios Vitalis. 4041* Added Esperanto translation, thanks to Dinu Gherman. 4042* Added Hindi translation, thanks to Purnank H. Ghumalia. 4043* Added Romanian translation, thanks to Razvan Stefanescu. 4044 4045Bugs fixed 4046---------- 4047 4048* C++, added support for ``extern`` and ``thread_local``. 4049* C++, type declarations are now using the prefixes ``typedef``, ``using``, and 4050 ``type``, depending on the style of declaration. 4051* #2413: C++, fix crash on duplicate declarations 4052* #2394: Sphinx crashes when html_last_updated_fmt is invalid 4053* #2408: dummy builder not available in Makefile and make.bat 4054* #2412: hyperlink targets are broken in LaTeX builder 4055* figure directive crashes if non paragraph item is given as caption 4056* #2418: time formats no longer allowed in today_fmt 4057* #2395: Sphinx crashes if unicode character in image filename 4058* #2396: "too many values to unpack" in genindex-single 4059* #2405: numref link in PDF jumps to the wrong location 4060* #2414: missing number in PDF hyperlinks to code listings 4061* #2440: wrong import for gmtime. Thanks to Uwe L. Korn. 4062 4063 4064Release 1.4 (released Mar 28, 2016) 4065=================================== 4066 4067Incompatible changes 4068-------------------- 4069* Drop ``PorterStemmer`` package support. Use ``PyStemmer`` instead of 4070 ``PorterStemmer`` to accelerate stemming. 4071* sphinx_rtd_theme has become optional. Please install it manually. 4072 Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich. 4073* #2231: Use DUrole instead of DUspan for custom roles in LaTeX writer. It 4074 enables to take title of roles as an argument of custom macros. 4075* #2022: 'Thumbs.db' and '.DS_Store' are added to `exclude_patterns` default 4076 values in conf.py that will be provided on sphinx-quickstart. 4077* #2027, #2208: The ``html_title`` accepts string values only. And The None 4078 value cannot be accepted. 4079* ``sphinx.ext.graphviz``: show graph image in inline by default 4080* #2060, #2224: The ``manpage`` role now generate ``sphinx.addnodes.manpage`` 4081 node instead of ``sphinx.addnodes.literal_emphasis`` node. 4082* #2022: :confval:`html_extra_path` also copies dotfiles in the extra directory, 4083 and refers to :confval:`exclude_patterns` to exclude extra files and 4084 directories. 4085* #2300: enhance autoclass:: to use the docstring of __new__ if __init__ 4086 method's is missing of empty 4087* #2251: Previously, under glossary directives, multiple terms for one 4088 definition are converted into single ``term`` node and the each terms in the 4089 term node are separated by ``termsep`` node. In new implementation, each terms 4090 are converted into individual ``term`` nodes and ``termsep`` node is removed. 4091 By this change, output layout of every builders are changed a bit. 4092* The default highlight language is now Python 3. This means that source code 4093 is highlighted as Python 3 (which is mostly a superset of Python 2), and no 4094 parsing is attempted to distinguish valid code. To get the old behavior back, 4095 add ``highlight_language = "python"`` to conf.py. 4096* `Locale Date Markup Language 4097 <https://unicode.org/reports/tr35/tr35-dates.html#Date_Format_Patterns>`_ like 4098 ``"MMMM dd, YYYY"`` is default format for `today_fmt` and 4099 `html_last_updated_fmt`. However strftime format like ``"%B %d, %Y"`` is also 4100 supported for backward compatibility until Sphinx-1.5. Later format will be 4101 disabled from Sphinx-1.5. 4102* #2327: ``latex_use_parts`` is deprecated now. Use `latex_toplevel_sectioning` 4103 instead. 4104* #2337: Use ``\url{URL}`` macro instead of ``\href{URL}{URL}`` in LaTeX writer. 4105* #1498: manpage writer: don't make whole of item in definition list bold if it 4106 includes strong node. 4107* #582: Remove hint message from quick search box for html output. 4108* #2378: Sphinx now bundles newfloat.sty 4109 4110Features added 4111-------------- 4112* #2092: add todo directive support in napoleon package. 4113* #1962: when adding directives, roles or nodes from an extension, warn if such 4114 an element is already present (built-in or added by another extension). 4115* #1909: Add "doc" references to Intersphinx inventories. 4116* C++ type alias support (e.g., ``.. type:: T = int``). 4117* C++ template support for classes, functions, type aliases, and variables 4118 (#1729, #1314). 4119* C++, added new scope management directives ``namespace-push`` and 4120 ``namespace-pop``. 4121* #1970: Keyboard shortcuts to navigate Next and Previous topics 4122* Intersphinx: Added support for fetching Intersphinx inventories with URLs 4123 using HTTP basic auth. 4124* C++, added support for template parameter in function info field lists. 4125* C++, added support for pointers to member (function). 4126* #2113: Allow ``:class:`` option to code-block directive. 4127* #2192: Imgmath (pngmath with svg support). 4128* #2200: Support XeTeX and LuaTeX for the LaTeX builder. 4129* #1906: Use xcolor over color for \fcolorbox where available for LaTeX output. 4130* #2216: Texinputs makefile improvements. 4131* #2170: Support for Chinese language search index. 4132* #2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages 4133* #1030: Make page reference names for latex_show_pagerefs translatable 4134* #2162: Add Sphinx.add_source_parser() to add source_suffix and source_parsers 4135 from extension 4136* #2207: Add sphinx.parsers.Parser class; a base class for new parsers 4137* #656: Add ``graphviz_dot`` option to graphviz directives to switch the ``dot`` 4138 command 4139* #1939: Added the ``dummy`` builder: syntax check without output. 4140* #2230: Add ``math_number_all`` option to number all displayed math in math 4141 extensions 4142* #2235: ``needs_sphinx`` supports micro version comparison 4143* #2282: Add "language" attribute to html tag in the "basic" theme 4144* #1779: Add EPUB 3 builder 4145* #1751: Add :confval:`todo_link_only` to avoid file path and line indication on 4146 :rst:dir:`todolist`. Thanks to Francesco Montesano. 4147* #2199: Use ``imagesize`` package to obtain size of images. 4148* #1099: Add configurable retries to the linkcheck builder. Thanks to Alex 4149 Gaynor. Also don't check anchors starting with ``!``. 4150* #2300: enhance autoclass:: to use the docstring of __new__ if __init__ 4151 method's is missing of empty 4152* #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for numfig 4153 feature 4154* #1286, #2099: Add ``sphinx.ext.autosectionlabel`` extension to allow reference 4155 sections using its title. Thanks to Tadhg O'Higgins. 4156* #1854: Allow to choose Janome for Japanese splitter. 4157* #1853: support custom text splitter on html search with ``language='ja'``. 4158* #2320: classifier of glossary terms can be used for index entries grouping key 4159 The classifier also be used for translation. See also 4160 :ref:`glossary-directive`. 4161* #2308: Define ``\tablecontinued`` macro to redefine the style of continued 4162 label for longtables. 4163* Select an image by similarity if multiple images are globbed by 4164 ``.. image:: filename.*`` 4165* #1921: Support figure substitutions by :confval:`language` and 4166 :confval:`figure_language_filename` 4167* #2245: Add ``latex_elements["passoptionstopackages"]`` option to call 4168 PassOptionsToPackages in early stage of preambles. 4169* #2340: Math extension: support alignment of multiple equations for MathJax. 4170* #2338: Define ``\titleref`` macro to redefine the style of ``title-reference`` 4171 roles. 4172* Define ``\menuselection`` and ``\accelerator`` macros to redefine the style of 4173 `menuselection` roles. 4174* Define ``\crossref`` macro to redefine the style of references 4175* #2301: Texts in the classic html theme should be hyphenated. 4176* #2355: Define ``\termref`` macro to redefine the style of ``term`` roles. 4177* Add :confval:`suppress_warnings` to suppress arbitrary warning message 4178 (experimental) 4179* #2229: Fix no warning is given for unknown options 4180* #2327: Add `latex_toplevel_sectioning` to switch the top level sectioning of 4181 LaTeX document. 4182 4183Bugs fixed 4184---------- 4185* #1913: C++, fix assert bug for enumerators in next-to-global and global scope. 4186* C++, fix parsing of 'signed char' and 'unsigned char' as types. 4187* C++, add missing support for 'friend' functions. 4188* C++, add missing support for virtual base classes (thanks to Rapptz). 4189* C++, add support for final classes. 4190* C++, fix parsing of types prefixed with 'enum'. 4191* #2023: Dutch search support uses Danish stemming info. 4192* C++, add support for user-defined literals. 4193* #1804: Now html output wraps overflowed long-line-text in the sidebar. Thanks 4194 to Hassen ben tanfous. 4195* #2183: Fix porterstemmer causes ``make json`` to fail. 4196* #1899: Ensure list is sent to OptParse. 4197* #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx package 4198 option). 4199* #2165, #2218: Remove faulty and non-need conditional from sphinx.sty. 4200* Fix broken LaTeX code is generated if unknown language is given 4201* #1944: Fix rst_prolog breaks file-wide metadata 4202* #2074: make gettext should use canonical relative paths for .pot. Thanks to 4203 anatoly techtonik. 4204* #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError 4205* #2251: Line breaks in .rst files are transferred to .pot files in a wrong way. 4206* #794: Fix date formatting in latex output is not localized 4207* Remove ``image/gif`` from supported_image_types of LaTeX writer (#2272) 4208* Fix ValueError is raised if LANGUAGE is empty string 4209* Fix unpack warning is shown when the directives generated from 4210 ``Sphinx.add_crossref_type`` is used 4211* The default highlight language is now ``default``. This means that source 4212 code is highlighted as Python 3 (which is mostly a superset of Python 2) if 4213 possible. To get the old behavior back, add ``highlight_language = "python"`` 4214 to conf.py. 4215* #2329: Refresh environment forcedly if source directory has changed. 4216* #2331: Fix code-blocks are filled by block in dvi; remove ``xcdraw`` option 4217 from xcolor package 4218* Fix the confval type checker emits warnings if unicode is given to confvals 4219 which expects string value 4220* #2360: Fix numref in LaTeX output is broken 4221* #2361: Fix additional paragraphs inside the "compound" directive are indented 4222* #2364: Fix KeyError 'rootSymbol' on Sphinx upgrade from older version. 4223* #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer. 4224* #2368: Ignore emacs lock files like ``.#foo.rst`` by default. 4225* #2262: literal_block and its caption has been separated by pagebreak in LaTeX 4226 output. 4227* #2319: Fix table counter is overridden by code-block's in LaTeX. Thanks to 4228 jfbu. 4229* Fix unpack warning if combined with 3rd party domain extensions. 4230* #1153: Fix figures in sidebar causes latex build error. 4231* #2358: Fix user-preamble could not override the tocdepth definition. 4232* #2358: Reduce tocdepth if ``part`` or ``chapter`` is used for top_sectionlevel 4233* #2351: Fix footnote spacing 4234* #2363: Fix ``toctree()`` in templates generates broken links in 4235 SingleHTMLBuilder. 4236* #2366: Fix empty hyperref is generated on toctree in HTML builder. 4237 4238Documentation 4239------------- 4240 4241* #1757: Fix for usage of :confval:`html_last_updated_fmt`. Thanks to Ralf 4242 Hemmecke. 4243 4244 4245Release 1.3.6 (released Feb 29, 2016) 4246===================================== 4247 4248Features added 4249-------------- 4250 4251* #1873, #1876, #2278: Add ``page_source_suffix`` html context variable. This 4252 should be introduced with :confval:`source_parsers` feature. Thanks for Eric 4253 Holscher. 4254 4255 4256Bugs fixed 4257---------- 4258 4259* #2265: Fix babel is used in spite of disabling it on ``latex_elements`` 4260* #2295: Avoid mutating dictionary errors while enumerating members in autodoc 4261 with Python 3 4262* #2291: Fix pdflatex "Counter too large" error from footnotes inside tables of 4263 contents 4264* #2292: Fix some footnotes disappear from LaTeX output 4265* #2287: ``sphinx.transforms.Locale`` always uses rst parser. Sphinx i18n 4266 feature should support parsers that specified source_parsers. 4267* #2290: Fix ``sphinx.ext.mathbase`` use of amsfonts may break user choice of 4268 math fonts 4269* #2324: Print a hint how to increase the recursion limit when it is hit. 4270* #1565, #2229: Revert new warning; the new warning will be triggered from 4271 version 1.4 on. 4272* #2329: Refresh environment forcedly if source directory has changed. 4273* #2019: Fix the domain objects in search result are not escaped 4274 4275Release 1.3.5 (released Jan 24, 2016) 4276===================================== 4277 4278Bugs fixed 4279---------- 4280 4281* Fix line numbers was not shown on warnings in LaTeX and texinfo builders 4282* Fix filenames were not shown on warnings of citations 4283* Fix line numbers was not shown on warnings in LaTeX and texinfo builders 4284* Fix line numbers was not shown on warnings of indices 4285* #2026: Fix LaTeX builder raises error if parsed-literal includes links 4286* #2243: Ignore strange docstring types for classes, do not crash 4287* #2247: Fix #2205 breaks make html for definition list with classifiers 4288 that contains regular-expression like string 4289* #1565: Sphinx will now emit a warning that highlighting was skipped if the 4290 syntax is incorrect for `code-block`, `literalinclude` and so on. 4291* #2211: Fix paragraphs in table cell doesn't work in Latex output 4292* #2253: ``:pyobject:`` option of ``literalinclude`` directive can't detect 4293 indented body block when the block starts with blank or comment lines. 4294* Fix TOC is not shown when no ``:maxdepth:`` for toctrees (ref: #771) 4295* Fix warning message for ``:numref:`` if target is in orphaned doc (ref: #2244) 4296 4297Release 1.3.4 (released Jan 12, 2016) 4298===================================== 4299 4300Bugs fixed 4301---------- 4302 4303* #2134: Fix figure caption with reference causes latex build error 4304* #2094: Fix rubric with reference not working in Latex 4305* #2147: Fix literalinclude code in latex does not break in pages 4306* #1833: Fix email addresses is showed again if latex_show_urls is not None 4307* #2176: sphinx.ext.graphviz: use <object> instead of <img> to embed svg 4308* #967: Fix SVG inheritance diagram is not hyperlinked (clickable) 4309* #1237: Fix footnotes not working in definition list in LaTeX 4310* #2168: Fix raw directive does not work for text writer 4311* #2171: Fix cannot linkcheck url with unicode 4312* #2182: LaTeX: support image file names with more than 1 dots 4313* #2189: Fix previous sibling link for first file in subdirectory uses last 4314 file, not intended previous from root toctree 4315* #2003: Fix decode error under python2 (only) when ``make linkcheck`` is run 4316* #2186: Fix LaTeX output of \mathbb in math 4317* #1480, #2188: LaTeX: Support math in section titles 4318* #2071: Fix same footnote in more than two section titles => LaTeX/PDF Bug 4319* #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains non-ascii 4320 characters 4321* #2193: Fix shutil.SameFileError if source directory and destination directory 4322 are same 4323* #2178: Fix unparsable C++ cross-reference when referencing a function with 4324 :cpp:any: 4325* #2206: Fix Sphinx latex doc build failed due to a footnotes 4326* #2201: Fix wrong table caption for tables with over 30 rows 4327* #2213: Set <blockquote> in the classic theme to fit with <p> 4328* #1815: Fix linkcheck does not raise an exception if warniserror set to true 4329 and link is broken 4330* #2197: Fix slightly cryptic error message for missing index.rst file 4331* #1894: Unlisted phony targets in quickstart Makefile 4332* #2125: Fix unifies behavior of collapsed fields (``GroupedField`` and 4333 ``TypedField``) 4334* #1408: Check latex_logo validity before copying 4335* #771: Fix latex output doesn't set tocdepth 4336* #1820: On Windows, console coloring is broken with colorama version 0.3.3. 4337 Now sphinx use colorama>=0.3.5 to avoid this problem. 4338* #2072: Fix footnotes in chapter-titles do not appear in PDF output 4339* #1580: Fix paragraphs in longtable don't work in Latex output 4340* #1366: Fix centered image not centered in latex 4341* #1860: Fix man page using ``:samp:`` with braces - font doesn't reset 4342* #1610: Sphinx crashes in Japanese indexing in some systems 4343* Fix Sphinx crashes if mecab initialization failed 4344* #2160: Fix broken TOC of PDFs if section includes an image 4345* #2172: Fix dysfunctional admonition ``\py@lightbox`` in sphinx.sty. Thanks to 4346 jfbu. 4347* #2198,#2205: ``make gettext`` generate broken msgid for definition lists. 4348* #2062: Escape characters in doctests are treated incorrectly with Python 2. 4349* #2225: Fix if the option does not begin with dash, linking is not performed 4350* #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath, mathjax) 4351* #1601, #2220: 'any' role breaks extended domains behavior. Affected extensions 4352 doesn't support resolve_any_xref and resolve_xref returns problematic node 4353 instead of None. sphinxcontrib-httpdomain is one of them. 4354* #2229: Fix no warning is given for unknown options 4355 4356Release 1.3.3 (released Dec 2, 2015) 4357==================================== 4358 4359Bugs fixed 4360---------- 4361 4362* #2177: Fix parallel hangs 4363* #2012: Fix exception occurred if ``numfig_format`` is invalid 4364* #2142: Provide non-minified JS code in ``sphinx/search/non-minified-js/*.js`` 4365 for source distribution on PyPI. 4366* #2148: Error while building devhelp target with non-ASCII document. 4367 4368 4369Release 1.3.2 (released Nov 29, 2015) 4370===================================== 4371 4372Features added 4373-------------- 4374 4375* #1935: Make "numfig_format" overridable in latex_elements. 4376 4377Bugs fixed 4378---------- 4379 4380* #1976: Avoid "2.0" version of Babel because it doesn't work with Windows 4381 environment. 4382* Add a "default.css" stylesheet (which imports "classic.css") for compatibility 4383* #1788: graphviz extension raises exception when caption option is present. 4384* #1789: ``:pyobject:`` option of ``literalinclude`` directive includes 4385 following lines after class definitions 4386* #1790: ``literalinclude`` strips empty lines at the head and tail 4387* #1802: load plugin themes automatically when theme.conf use it as 'inherit'. 4388 Thanks to Takayuki Hirai. 4389* #1794: custom theme extended from alabaster or sphinx_rtd_theme can't find 4390 base theme. 4391* #1834: compatibility for docutils-0.13: handle_io_errors keyword argument for 4392 docutils.io.FileInput cause TypeError. 4393* #1823: '.' as <module_path> for sphinx-apidoc cause an unfriendly error. Now 4394 '.' is converted to absolute path automatically. 4395* Fix a crash when setting up extensions which do not support metadata. 4396* #1784: Provide non-minified JS code in ``sphinx/search/non-minified-js/*.js`` 4397* #1822, #1892: Fix regression for #1061. autosummary can't generate doc for 4398 imported members since sphinx-1.3b3. Thanks to Eric Larson. 4399* #1793, #1819: "see also" misses a linebreak in text output. Thanks to Takayuki 4400 Hirai. 4401* #1780, #1866: "make text" shows "class" keyword twice. Thanks to Takayuki 4402 Hirai. 4403* #1871: Fix for LaTeX output of tables with one column and multirows. 4404* Work around the lack of the HTMLParserError exception in Python 3.5. 4405* #1949: Use ``safe_getattr`` in the coverage builder to avoid aborting with 4406 descriptors that have custom behavior. 4407* #1915: Do not generate smart quotes in doc field type annotations. 4408* #1796: On py3, automated .mo building caused UnicodeDecodeError. 4409* #1923: Use babel features only if the babel latex element is nonempty. 4410* #1942: Fix a KeyError in websupport. 4411* #1903: Fix strange id generation for glossary terms. 4412* ``make text`` will crush if a definition list item has more than 1 classifiers 4413 as: ``term : classifier1 : classifier2``. 4414* #1855: make gettext generates broken po file for definition lists with 4415 classifier. 4416* #1869: Fix problems when dealing with files containing non-ASCII characters. 4417 Thanks to Marvin Schmidt. 4418* #1798: Fix building LaTeX with references in titles. 4419* #1725: On py2 environment, doctest with using non-ASCII characters causes 4420 ``'ascii' codec can't decode byte`` exception. 4421* #1540: Fix RuntimeError with circular referenced toctree 4422* #1983: i18n translation feature breaks references which uses section name. 4423* #1990: Use caption of toctree to title of \tableofcontents in LaTeX 4424* #1987: Fix ampersand is ignored in ``:menuselection:`` and ``:guilabel:`` 4425 on LaTeX builder 4426* #1994: More supporting non-standard parser (like recommonmark parser) for 4427 Translation and WebSupport feature. Now node.rawsource is fall backed to 4428 node.astext() during docutils transforming. 4429* #1989: "make blahblah" on Windows indicate help messages for sphinx-build 4430 every time. It was caused by wrong make.bat that generated by 4431 Sphinx-1.3.0/1.3.1. 4432* On Py2 environment, conf.py that is generated by sphinx-quickstart should have 4433 u prefixed config value for 'version' and 'release'. 4434* #2102: On Windows + Py3, using ``|today|`` and non-ASCII date format will 4435 raise UnicodeEncodeError. 4436* #1974: UnboundLocalError: local variable 'domain' referenced before assignment 4437 when using `any` role and `sphinx.ext.intersphinx` in same time. 4438* #2121: multiple words search doesn't find pages when words across on the page 4439 title and the page content. 4440* #1884, #1885: plug-in html themes cannot inherit another plug-in theme. Thanks 4441 to Suzumizaki. 4442* #1818: `sphinx.ext.todo` directive generates broken html class attribute as 4443 'admonition-' when :confval:`language` is specified with non-ASCII linguistic 4444 area like 'ru' or 'ja'. To fix this, now ``todo`` directive can use 4445 ``:class:`` option. 4446* #2140: Fix footnotes in table has broken in LaTeX 4447* #2127: MecabBinder for html searching feature doesn't work with Python 3. 4448 Thanks to Tomoko Uchida. 4449 4450 4451Release 1.3.1 (released Mar 17, 2015) 4452===================================== 4453 4454Bugs fixed 4455---------- 4456 4457* #1769: allows generating quickstart files/dirs for destination dir that 4458 doesn't overwrite existent files/dirs. Thanks to WAKAYAMA shirou. 4459* #1773: sphinx-quickstart doesn't accept non-ASCII character as a option 4460 argument. 4461* #1766: the message "least Python 2.6 to run" is at best misleading. 4462* #1772: cross reference in docstrings like ``:param .write:`` breaks building. 4463* #1770, #1774: ``literalinclude`` with empty file occurs exception. Thanks to 4464 Takayuki Hirai. 4465* #1777: Sphinx 1.3 can't load extra theme. Thanks to tell-k. 4466* #1776: ``source_suffix = ['.rst']`` cause unfriendly error on prior version. 4467* #1771: automated .mo building doesn't work properly. 4468* #1783: Autodoc: Python2 Allow unicode string in __all__. 4469 Thanks to Jens Hedegaard Nielsen. 4470* #1781: Setting `html_domain_indices` to a list raises a type check warnings. 4471 4472 4473Release 1.3 (released Mar 10, 2015) 4474=================================== 4475 4476Incompatible changes 4477-------------------- 4478 4479* Roles ``ref``, ``term`` and ``menusel`` now don't generate :durole:`emphasis` 4480 nodes anymore. If you want to keep italic style, adapt your stylesheet. 4481* Role ``numref`` uses ``%s`` as special character to indicate position of 4482 figure numbers instead ``#`` symbol. 4483 4484Features added 4485-------------- 4486 4487* Add convenience directives and roles to the C++ domain: 4488 directive ``cpp:var`` as alias for ``cpp:member``, role ``:cpp:var`` as alias 4489 for ``:cpp:member``, and role `any` for cross-reference to any C++ 4490 declaraction. #1577, #1744 4491* The :confval:`source_suffix` config value can now be a list of multiple 4492 suffixes. 4493* Add the ability to specify source parsers by source suffix with the 4494 :confval:`source_parsers` config value. 4495* #1675: A new builder, AppleHelpBuilder, has been added that builds Apple 4496 Help Books. 4497 4498Bugs fixed 4499---------- 4500 4501* 1.3b3 change breaks a previous gettext output that contains duplicated 4502 msgid such as "foo bar" and "version changes in 1.3: foo bar". 4503* #1745: latex builder cause maximum recursion depth exceeded when a 4504 footnote has a footnote mark itself. 4505* #1748: SyntaxError in sphinx/ext/ifconfig.py with Python 2.6. 4506* #1658, #1750: No link created (and warning given) if option does not 4507 begin with -, / or +. Thanks to Takayuki Hirai. 4508* #1753: C++, added missing support for more complex declarations. 4509* #1700: Add ``:caption:`` option for :rst:dir:`toctree`. 4510* #1742: ``:name:`` option is provided for :rst:dir:`toctree`, 4511 :rst:dir:`code-block` and :rst:dir:`literalinclude` directives. 4512* #1756: Incorrect section titles in search that was introduced from 1.3b3. 4513* #1746: C++, fixed name lookup procedure, and added missing lookups in 4514 declarations. 4515* #1765: C++, fix old id generation to use fully qualified names. 4516 4517Documentation 4518------------- 4519 4520* #1651: Add ``vartype`` field description for python domain. 4521 4522 4523Release 1.3b3 (released Feb 24, 2015) 4524===================================== 4525 4526Incompatible changes 4527-------------------- 4528 4529* Dependency requirement updates: docutils 0.11, Pygments 2.0 4530* The ``gettext_enables`` config value has been renamed to 4531 `gettext_additional_targets`. 4532* #1735: Use https://docs.python.org/ instead of ``http`` protocol. 4533 It was used for `sphinx.ext.intersphinx` and some documentation. 4534 4535Features added 4536-------------- 4537 4538* #1346: Add new default theme; 4539 4540 * Add 'alabaster' theme. 4541 * Add 'sphinx_rtd_theme' theme. 4542 * The 'default' html theme has been renamed to 'classic'. 'default' is still 4543 available, however it will emit notice a recommendation that using new 4544 'alabaster' theme. 4545 4546* Added ``highlight_options`` configuration value. 4547* The ``language`` config value is now available in the HTML templates. 4548* The ``env-updated`` event can now return a value, which is interpreted 4549 as an iterable of additional docnames that need to be rewritten. 4550* #772: Support for scoped and unscoped enums in C++. Enumerators in unscoped 4551 enums are injected into the parent scope in addition to the enum scope. 4552* Add ``todo_include_todos`` config option to quickstart conf file, handled as 4553 described in documentation. 4554* HTML breadcrumb items tag has class "nav-item" and "nav-item-N" (like 4555 nav-item-0, 1, 2...). 4556* New option `sphinx-quickstart --use-make-mode` for generating Makefile that 4557 use sphinx-build make-mode. 4558* #1235: i18n: several node can be translated if it is set to 4559 `gettext_additional_targets` in conf.py. Supported nodes are: 4560 4561 - 'literal-block' 4562 - 'doctest-block' 4563 - 'raw' 4564 - 'image' 4565 4566* #1227: Add `html_scaled_image_link` config option to conf.py, to control 4567 scaled image link. 4568 4569Bugs fixed 4570---------- 4571 4572* LaTeX writer now generates correct markup for cells spanning multiple rows. 4573* #1674: Do not crash if a module's ``__all__`` is not a list of strings. 4574* #1629: Use VerbatimBorderColor to add frame to code-block in LaTeX 4575* On windows, make-mode didn't work on Win32 platform if sphinx was invoked as 4576 ``python sphinx-build.py``. 4577* #1687: linkcheck now treats 401 Unauthorized responses as "working". 4578* #1690: toctrees with ``glob`` option now can also contain entries for single 4579 documents with explicit title. 4580* #1591: html search results for C++ elements now has correct interpage links. 4581* bizstyle theme: nested long title pages make long breadcrumb that breaks page 4582 layout. 4583* bizstyle theme: all breadcrumb items become 'Top' on some mobile browser 4584 (iPhone5s safari). 4585* #1722: restore ``toctree()`` template function behavior that was changed at 4586 1.3b1. 4587* #1732: i18n: localized table caption raises exception. 4588* #1718: ``:numref:`` does not work with capital letters in the label 4589* #1630: resolve CSS conflicts, ``div.container`` css target for literal block 4590 wrapper now renamed to ``div.literal-block-wrapper``. 4591* ``sphinx.util.pycompat`` has been restored in its backwards-compatibility; 4592 slated for removal in Sphinx 1.4. 4593* #1719: LaTeX writer does not respect ``numref_format`` option in captions 4594 4595 4596Release 1.3b2 (released Dec 5, 2014) 4597==================================== 4598 4599Incompatible changes 4600-------------------- 4601 4602* update bundled ez_setup.py for setuptools-7.0 that requires Python 2.6 or 4603 later. 4604 4605Features added 4606-------------- 4607 4608* #1597: Added possibility to return a new template name from 4609 `html-page-context`. 4610* PR#314, #1150: Configuration values are now checked for their type. A 4611 warning is raised if the configured and the default value do not have the 4612 same type and do not share a common non-trivial base class. 4613 4614Bugs fixed 4615---------- 4616 4617* PR#311: sphinx-quickstart does not work on python 3.4. 4618* Fix :confval:`autodoc_docstring_signature` not working with signatures 4619 in class docstrings. 4620* Rebuilding cause crash unexpectedly when source files were added. 4621* #1607: Fix a crash when building latexpdf with "howto" class 4622* #1251: Fix again. Sections which depth are lower than :tocdepth: should not 4623 be shown on localtoc sidebar. 4624* make-mode didn't work on Win32 platform if sphinx was installed by wheel 4625 package. 4626 4627 4628Release 1.3b1 (released Oct 10, 2014) 4629===================================== 4630 4631Incompatible changes 4632-------------------- 4633 4634* Dropped support for Python 2.5, 3.1 and 3.2. 4635* Dropped support for docutils versions up to 0.9. 4636* Removed the ``sphinx.ext.oldcmarkup`` extension. 4637* The deprecated config values ``exclude_trees``, ``exclude_dirnames`` and 4638 ``unused_docs`` have been removed. 4639* A new node, ``sphinx.addnodes.literal_strong``, has been added, for text that 4640 should appear literally (i.e. no smart quotes) in strong font. Custom writers 4641 will have to be adapted to handle this node. 4642* PR#269, #1476: replace ``<tt>`` tag by ``<code>``. User customized stylesheets 4643 should be updated If the css contain some styles for ``tt>`` tag. 4644 Thanks to Takeshi Komiya. 4645* #1543: `templates_path` is automatically added to 4646 `exclude_patterns` to avoid reading autosummary rst templates in the 4647 templates directory. 4648* Custom domains should implement the new `Domain.resolve_any_xref` 4649 method to make the `any` role work properly. 4650* gettext builder: gettext doesn't emit uuid information to generated pot files 4651 by default. Please set ``True`` to `gettext_uuid` to emit uuid information. 4652 Additionally, if the ``python-levenshtein`` 3rd-party package is installed, 4653 it will improve the calculation time. 4654* gettext builder: disable extracting/apply 'index' node by default. Please set 4655 'index' to ``gettext_enables`` to enable extracting index entries. 4656* PR#307: Add frame to code-block in LaTeX. Thanks to Takeshi Komiya. 4657 4658Features added 4659-------------- 4660 4661* Add support for Python 3.4. 4662* Add support for docutils 0.12 4663* Added ``sphinx.ext.napoleon`` extension for NumPy and Google style docstring 4664 support. 4665* Added support for parallel reading (parsing) of source files with the 4666 `sphinx-build -j` option. Third-party extensions will need to be checked for 4667 compatibility and may need to be adapted if they store information in the 4668 build environment object. See `env-merge-info`. 4669* Added the `any` role that can be used to find a cross-reference of 4670 *any* type in *any* domain. Custom domains should implement the new 4671 `Domain.resolve_any_xref` method to make this work properly. 4672* Exception logs now contain the last 10 messages emitted by Sphinx. 4673* Added support for extension versions (a string returned by ``setup()``, these 4674 can be shown in the traceback log files). Version requirements for extensions 4675 can be specified in projects using the new `needs_extensions` config 4676 value. 4677* Changing the default role within a document with the :dudir:`default-role` 4678 directive is now supported. 4679* PR#214: Added stemming support for 14 languages, so that the built-in document 4680 search can now handle these. Thanks to Shibukawa Yoshiki. 4681* PR#296, PR#303, #76: numfig feature: Assign numbers to figures, tables and 4682 code-blocks. This feature is configured with `numfig`, `numfig_secnum_depth` 4683 and `numfig_format`. Also `numref` role is available. Thanks to Takeshi 4684 Komiya. 4685* PR#202: Allow "." and "~" prefixed references in ``:param:`` doc fields 4686 for Python. 4687* PR#184: Add `autodoc_mock_imports`, allowing to mock imports of 4688 external modules that need not be present when autodocumenting. 4689* #925: Allow list-typed config values to be provided on the command line, 4690 like ``-D key=val1,val2``. 4691* #668: Allow line numbering of `code-block` and `literalinclude` directives 4692 to start at an arbitrary line number, with a new ``lineno-start`` option. 4693* PR#172, PR#266: The `code-block` and `literalinclude` 4694 directives now can have a ``caption`` option that shows a filename before the 4695 code in the output. Thanks to Nasimul Haque, Takeshi Komiya. 4696* Prompt for the document language in sphinx-quickstart. 4697* PR#217: Added config values to suppress UUID and location information in 4698 generated gettext catalogs. 4699* PR#236, #1456: apidoc: Add a -M option to put module documentation before 4700 submodule documentation. Thanks to Wes Turner and Luc Saffre. 4701* #1434: Provide non-minified JS files for jquery.js and underscore.js to 4702 clarify the source of the minified files. 4703* PR#252, #1291: Windows color console support. Thanks to meu31. 4704* PR#255: When generating latex references, also insert latex target/anchor 4705 for the ids defined on the node. Thanks to Olivier Heurtier. 4706* PR#229: Allow registration of other translators. Thanks to Russell Sim. 4707* Add app.set_translator() API to register or override a Docutils translator 4708 class like ``html_translator_class``. 4709* PR#267, #1134: add 'diff' parameter to literalinclude. Thanks to Richard Wall 4710 and WAKAYAMA shirou. 4711* PR#272: Added 'bizstyle' theme. Thanks to Shoji KUMAGAI. 4712* Automatically compile ``*.mo`` files from ``*.po`` files when 4713 `gettext_auto_build` is True (default) and ``*.po`` is newer than 4714 ``*.mo`` file. 4715* #623: `sphinx.ext.viewcode` supports imported function/class aliases. 4716* PR#275: `sphinx.ext.intersphinx` supports multiple target for the 4717 inventory. Thanks to Brigitta Sipocz. 4718* PR#261: Added the `env-before-read-docs` event that can be connected to modify 4719 the order of documents before they are read by the environment. 4720* #1284: Program options documented with :rst:dir:`option` can now start with 4721 ``+``. 4722* PR#291: The caption of :rst:dir:`code-block` is recognized as a title of ref 4723 target. Thanks to Takeshi Komiya. 4724* PR#298: Add new API: :meth:`~sphinx.application.Sphinx.add_latex_package`. 4725 Thanks to Takeshi Komiya. 4726* #1344: add ``gettext_enables`` to enable extracting 'index' to gettext 4727 catalog output / applying translation catalog to generated documentation. 4728* PR#301, #1583: Allow the line numbering of the directive `literalinclude` to 4729 match that of the included file, using a new ``lineno-match`` option. Thanks 4730 to Jeppe Pihl. 4731* PR#299: add various options to sphinx-quickstart. Quiet mode option 4732 ``--quiet`` will skips wizard mode. Thanks to WAKAYAMA shirou. 4733* #1623: Return types specified with ``:rtype:`` are now turned into links if 4734 possible. 4735 4736Bugs fixed 4737---------- 4738 4739* #1438: Updated jQuery version from 1.8.3 to 1.11.1. 4740* #1568: Fix a crash when a "centered" directive contains a reference. 4741* Now sphinx.ext.autodoc works with python-2.5 again. 4742* #1563: :meth:`~sphinx.application.Sphinx.add_search_language` raises 4743 AssertionError for correct type of argument. Thanks to rikoman. 4744* #1174: Fix smart quotes being applied inside roles like :rst:role:`program` or 4745 `makevar`. 4746* PR#235: comment db schema of websupport lacked a length of the node_id field. 4747 Thanks to solos. 4748* #1466,PR#241: Fix failure of the cpp domain parser to parse C+11 4749 "variadic templates" declarations. Thanks to Victor Zverovich. 4750* #1459,PR#244: Fix default mathjax js path point to ``http://`` that cause 4751 mixed-content error on HTTPS server. Thanks to sbrandtb and robo9k. 4752* PR#157: autodoc remove spurious signatures from @property decorated 4753 attributes. Thanks to David Ham. 4754* PR#159: Add coverage targets to quickstart generated Makefile and make.bat. 4755 Thanks to Matthias Troffaes. 4756* #1251: When specifying toctree :numbered: option and :tocdepth: metadata, 4757 sub section number that is larger depth than ``:tocdepth:`` is shrunk. 4758* PR#260: Encode underscore in citation labels for latex export. Thanks to 4759 Lennart Fricke. 4760* PR#264: Fix could not resolve xref for figure node with :name: option. 4761 Thanks to Takeshi Komiya. 4762* PR#265: Fix could not capture caption of graphviz node by xref. Thanks to 4763 Takeshi Komiya. 4764* PR#263, #1013, #1103: Rewrite of C++ domain. Thanks to Jakob Lykke Andersen. 4765 4766 * Hyperlinks to all found nested names and template arguments (#1103). 4767 * Support for function types everywhere, e.g., in 4768 std::function<bool(int, int)> (#1013). 4769 * Support for virtual functions. 4770 * Changed interpretation of function arguments to following standard 4771 prototype declarations, i.e., void f(arg) means that arg is the type of the 4772 argument, instead of it being the name. 4773 * Updated tests. 4774 * Updated documentation with elaborate description of what declarations are 4775 supported and how the namespace declarations influence declaration and 4776 cross-reference lookup. 4777 * Index names may be different now. Elements are indexed by their fully 4778 qualified name. It should be rather easy to change this behaviour and 4779 potentially index by namespaces/classes as well. 4780 4781* PR#258, #939: Add dedent option for `code-block` and 4782 `literalinclude`. Thanks to Zafar Siddiqui. 4783* PR#268: Fix numbering section does not work at singlehtml mode. It still 4784 ad-hoc fix because there is a issue that section IDs are conflicted. 4785 Thanks to Takeshi Komiya. 4786* PR#273, #1536: Fix RuntimeError with numbered circular toctree. Thanks to 4787 Takeshi Komiya. 4788* PR#274: Set its URL as a default title value if URL appears in toctree. 4789 Thanks to Takeshi Komiya. 4790* PR#276, #1381: `rfc` and `pep` roles support custom link 4791 text. Thanks to Takeshi Komiya. 4792* PR#277, #1513: highlights for function pointers in argument list of 4793 `c:function`. Thanks to Takeshi Komiya. 4794* PR#278: Fix section entries were shown twice if toctree has been put under 4795 only directive. Thanks to Takeshi Komiya. 4796* #1547: pgen2 tokenizer doesn't recognize ``...`` literal (Ellipsis for py3). 4797* PR#294: On LaTeX builder, wrap float environment on writing literal_block 4798 to avoid separation of caption and body. Thanks to Takeshi Komiya. 4799* PR#295, #1520: ``make.bat latexpdf`` mechanism to ``cd`` back to the current 4800 directory. Thanks to Peter Suter. 4801* PR#297, #1571: Add imgpath property to all builders. It make easier to 4802 develop builder extensions. Thanks to Takeshi Komiya. 4803* #1584: Point to master doc in HTML "top" link. 4804* #1585: Autosummary of modules broken in Sphinx-1.2.3. 4805* #1610: Sphinx cause AttributeError when MeCab search option is enabled and 4806 python-mecab is not installed. 4807* #1674: Do not crash if a module's ``__all__`` is not a list of strings. 4808* #1673: Fix crashes with :confval:`nitpick_ignore` and ``:doc:`` references. 4809* #1686: ifconfig directive doesn't care about default config values. 4810* #1642: Fix only one search result appearing in Chrome. 4811 4812Documentation 4813------------- 4814 4815* Add clarification about the syntax of tags. (:file:`doc/markup/misc.rst`) 4816 4817 4818Release 1.2.3 (released Sep 1, 2014) 4819==================================== 4820 4821Features added 4822-------------- 4823 4824* #1518: ``sphinx-apidoc`` command now has a ``--version`` option to show 4825 version information and exit 4826* New locales: Hebrew, European Portuguese, Vietnamese. 4827 4828Bugs fixed 4829---------- 4830 4831* #636: Keep straight single quotes in literal blocks in the LaTeX build. 4832* #1419: Generated i18n sphinx.js files are missing message catalog entries 4833 from '.js_t' and '.html'. The issue was introduced from Sphinx-1.1 4834* #1363: Fix i18n: missing python domain's cross-references with currentmodule 4835 directive or currentclass directive. 4836* #1444: autosummary does not create the description from attributes docstring. 4837* #1457: In python3 environment, make linkcheck cause "Can't convert 'bytes' 4838 object to str implicitly" error when link target url has a hash part. 4839 Thanks to Jorge_C. 4840* #1467: Exception on Python3 if nonexistent method is specified by automethod 4841* #1441: autosummary can't handle nested classes correctly. 4842* #1499: With non-callable ``setup`` in a conf.py, now sphinx-build emits 4843 a user-friendly error message. 4844* #1502: In autodoc, fix display of parameter defaults containing backslashes. 4845* #1226: autodoc, autosummary: importing setup.py by automodule will invoke 4846 setup process and execute ``sys.exit()``. Now sphinx avoids SystemExit 4847 exception and emits warnings without unexpected termination. 4848* #1503: py:function directive generate incorrectly signature when specifying 4849 a default parameter with an empty list ``[]``. Thanks to Geert Jansen. 4850* #1508: Non-ASCII filename raise exception on make singlehtml, latex, man, 4851 texinfo and changes. 4852* #1531: On Python3 environment, docutils.conf with 'source_link=true' in the 4853 general section cause type error. 4854* PR#270, #1533: Non-ASCII docstring cause UnicodeDecodeError when uses with 4855 inheritance-diagram directive. Thanks to WAKAYAMA shirou. 4856* PR#281, PR#282, #1509: TODO extension not compatible with websupport. Thanks 4857 to Takeshi Komiya. 4858* #1477: gettext does not extract nodes.line in a table or list. 4859* #1544: ``make text`` generates wrong table when it has empty table cells. 4860* #1522: Footnotes from table get displayed twice in LaTeX. This problem has 4861 been appeared from Sphinx-1.2.1 by #949. 4862* #508: Sphinx every time exit with zero when is invoked from setup.py command. 4863 ex. ``python setup.py build_sphinx -b doctest`` return zero even if doctest 4864 failed. 4865 4866Release 1.2.2 (released Mar 2, 2014) 4867==================================== 4868 4869Bugs fixed 4870---------- 4871 4872* PR#211: When checking for existence of the `html_logo` file, check 4873 the full relative path and not the basename. 4874* PR#212: Fix traceback with autodoc and ``__init__`` methods without docstring. 4875* PR#213: Fix a missing import in the setup command. 4876* #1357: Option names documented by :rst:dir:`option` are now again allowed to 4877 not start with a dash or slash, and referencing them will work correctly. 4878* #1358: Fix handling of image paths outside of the source directory when using 4879 the "wildcard" style reference. 4880* #1374: Fix for autosummary generating overly-long summaries if first line 4881 doesn't end with a period. 4882* #1383: Fix Python 2.5 compatibility of sphinx-apidoc. 4883* #1391: Actually prevent using "pngmath" and "mathjax" extensions at the same 4884 time in sphinx-quickstart. 4885* #1386: Fix bug preventing more than one theme being added by the entry point 4886 mechanism. 4887* #1370: Ignore "toctree" nodes in text writer, instead of raising. 4888* #1364: Fix 'make gettext' fails when the '.. todolist::' directive is present. 4889* #1367: Fix a change of PR#96 that break sphinx.util.docfields.Field.make_field 4890 interface/behavior for ``item`` argument usage. 4891 4892Documentation 4893------------- 4894 4895* Extended the :ref:`documentation about building extensions <dev-extensions>`. 4896 4897 4898Release 1.2.1 (released Jan 19, 2014) 4899===================================== 4900 4901Bugs fixed 4902---------- 4903 4904* #1335: Fix autosummary template overloading with exclamation prefix like 4905 ``{% extends "!autosummary/class.rst" %}`` cause infinite recursive function 4906 call. This was caused by PR#181. 4907* #1337: Fix autodoc with ``autoclass_content="both"`` uses useless 4908 ``object.__init__`` docstring when class does not have ``__init__``. 4909 This was caused by a change for #1138. 4910* #1340: Can't search alphabetical words on the HTML quick search generated 4911 with language='ja'. 4912* #1319: Do not crash if the `html_logo` file does not exist. 4913* #603: Do not use the HTML-ized title for building the search index (that 4914 resulted in "literal" being found on every page with a literal in the 4915 title). 4916* #751: Allow production lists longer than a page in LaTeX by using longtable. 4917* #764: Always look for stopwords lowercased in JS search. 4918* #814: autodoc: Guard against strange type objects that don't have 4919 ``__bases__``. 4920* #932: autodoc: Do not crash if ``__doc__`` is not a string. 4921* #933: Do not crash if an :rst:role:`option` value is malformed (contains 4922 spaces but no option name). 4923* #908: On Python 3, handle error messages from LaTeX correctly in the pngmath 4924 extension. 4925* #943: In autosummary, recognize "first sentences" to pull from the docstring 4926 if they contain uppercase letters. 4927* #923: Take the entire LaTeX document into account when caching 4928 pngmath-generated images. This rebuilds them correctly when 4929 ``pngmath_latex_preamble`` changes. 4930* #901: Emit a warning when using docutils' new "math" markup without a Sphinx 4931 math extension active. 4932* #845: In code blocks, when the selected lexer fails, display line numbers 4933 nevertheless if configured. 4934* #929: Support parsed-literal blocks in LaTeX output correctly. 4935* #949: Update the tabulary.sty packed with Sphinx. 4936* #1050: Add anonymous labels into ``objects.inv`` to be referenced via 4937 :mod:`~sphinx.ext.intersphinx`. 4938* #1095: Fix print-media stylesheet being included always in the "scrolls" 4939 theme. 4940* #1085: Fix current classname not getting set if class description has 4941 ``:noindex:`` set. 4942* #1181: Report option errors in autodoc directives more gracefully. 4943* #1155: Fix autodocumenting C-defined methods as attributes in Python 3. 4944* #1233: Allow finding both Python classes and exceptions with the "class" and 4945 "exc" roles in intersphinx. 4946* #1198: Allow "image" for the "figwidth" option of the :dudir:`figure` 4947 directive as documented by docutils. 4948* #1152: Fix pycode parsing errors of Python 3 code by including two grammar 4949 versions for Python 2 and 3, and loading the appropriate version for the 4950 running Python version. 4951* #1017: Be helpful and tell the user when the argument to :rst:dir:`option` 4952 does not match the required format. 4953* #1345: Fix two bugs with `nitpick_ignore`; now you don't have to 4954 remove the store environment for changes to have effect. 4955* #1072: In the JS search, fix issues searching for upper-cased words by 4956 lowercasing words before stemming. 4957* #1299: Make behavior of the :rst:dir:`math` directive more consistent and 4958 avoid producing empty environments in LaTeX output. 4959* #1308: Strip HTML tags from the content of "raw" nodes before feeding it 4960 to the search indexer. 4961* #1249: Fix duplicate LaTeX page numbering for manual documents. 4962* #1292: In the linkchecker, retry HEAD requests when denied by HTTP 405. 4963 Also make the redirect code apparent and tweak the output a bit to be 4964 more obvious. 4965* #1285: Avoid name clashes between C domain objects and section titles. 4966* #848: Always take the newest code in incremental rebuilds with the 4967 :mod:`sphinx.ext.viewcode` extension. 4968* #979, #1266: Fix exclude handling in ``sphinx-apidoc``. 4969* #1302: Fix regression in :mod:`sphinx.ext.inheritance_diagram` when 4970 documenting classes that can't be pickled. 4971* #1316: Remove hard-coded ``font-face`` resources from epub theme. 4972* #1329: Fix traceback with empty translation msgstr in .po files. 4973* #1300: Fix references not working in translated documents in some instances. 4974* #1283: Fix a bug in the detection of changed files that would try to access 4975 doctrees of deleted documents. 4976* #1330: Fix `exclude_patterns` behavior with subdirectories in the 4977 `html_static_path`. 4978* #1323: Fix emitting empty ``<ul>`` tags in the HTML writer, which is not 4979 valid HTML. 4980* #1147: Don't emit a sidebar search box in the "singlehtml" builder. 4981 4982Documentation 4983------------- 4984 4985* #1325: Added a "Intersphinx" tutorial section. (:file:`doc/tutorial.rst`) 4986 4987 4988Release 1.2 (released Dec 10, 2013) 4989=================================== 4990 4991Features added 4992-------------- 4993 4994* Added ``sphinx.version_info`` tuple for programmatic checking of the Sphinx 4995 version. 4996 4997Incompatible changes 4998-------------------- 4999 5000* Removed the ``sphinx.ext.refcounting`` extension -- it is very specific to 5001 CPython and has no place in the main distribution. 5002 5003Bugs fixed 5004---------- 5005 5006* Restore ``versionmodified`` CSS class for versionadded/changed and deprecated 5007 directives. 5008 5009* PR#181: Fix ``html_theme_path = ['.']`` is a trigger of rebuild all documents 5010 always (This change keeps the current "theme changes cause a rebuild" 5011 feature). 5012 5013* #1296: Fix invalid charset in HTML help generated HTML files for default 5014 locale. 5015 5016* PR#190: Fix gettext does not extract figure caption and rubric title inside 5017 other blocks. Thanks to Michael Schlenker. 5018 5019* PR#176: Make sure setup_command test can always import Sphinx. Thanks to 5020 Dmitry Shachnev. 5021 5022* #1311: Fix test_linkcode.test_html fails with C locale and Python 3. 5023 5024* #1269: Fix ResourceWarnings with Python 3.2 or later. 5025 5026* #1138: Fix: When ``autodoc_docstring_signature = True`` and 5027 ``autoclass_content = 'init'`` or ``'both'``, __init__ line should be 5028 removed from class documentation. 5029 5030 5031Release 1.2 beta3 (released Oct 3, 2013) 5032======================================== 5033 5034Features added 5035-------------- 5036 5037* The Sphinx error log files will now include a list of the loaded extensions 5038 for help in debugging. 5039 5040Incompatible changes 5041-------------------- 5042 5043* PR#154: Remove "sphinx" prefix from LaTeX class name except 'sphinxmanual' 5044 and 'sphinxhowto'. Now you can use your custom document class without 5045 'sphinx' prefix. Thanks to Erik B. 5046 5047Bugs fixed 5048---------- 5049 5050* #1265: Fix i18n: crash when translating a section name that is pointed to from 5051 a named target. 5052* A wrong condition broke the search feature on first page that is usually 5053 index.rst. This issue was introduced in 1.2b1. 5054* #703: When Sphinx can't decode filenames with non-ASCII characters, Sphinx now 5055 catches UnicodeError and will continue if possible instead of raising the 5056 exception. 5057 5058 5059Release 1.2 beta2 (released Sep 17, 2013) 5060========================================= 5061 5062Features added 5063-------------- 5064 5065* ``apidoc`` now ignores "_private" modules by default, and has an option ``-P`` 5066 to include them. 5067* ``apidoc`` now has an option to not generate headings for packages and 5068 modules, for the case that the module docstring already includes a reST 5069 heading. 5070* PR#161: ``apidoc`` can now write each module to a standalone page instead of 5071 combining all modules in a package on one page. 5072* Builders: rebuild i18n target document when catalog updated. 5073* Support docutils.conf 'writers' and 'html4css1 writer' section in the HTML 5074 writer. The latex, manpage and texinfo writers also support their respective 5075 'writers' sections. 5076* The new `html_extra_path` config value allows to specify directories 5077 with files that should be copied directly to the HTML output directory. 5078* Autodoc directives for module data and attributes now support an 5079 ``annotation`` option, so that the default display of the data/attribute 5080 value can be overridden. 5081* PR#136: Autodoc directives now support an ``imported-members`` option to 5082 include members imported from different modules. 5083* New locales: Macedonian, Sinhala, Indonesian. 5084* Theme package collection by using setuptools plugin mechanism. 5085 5086Incompatible changes 5087-------------------- 5088 5089* PR#144, #1182: Force timezone offset to LocalTimeZone on POT-Creation-Date 5090 that was generated by gettext builder. Thanks to masklinn and Jakub Wilk. 5091 5092Bugs fixed 5093---------- 5094 5095* PR#132: Updated jQuery version to 1.8.3. 5096* PR#141, #982: Avoid crash when writing PNG file using Python 3. Thanks to 5097 Marcin Wojdyr. 5098* PR#145: In parallel builds, sphinx drops second document file to write. 5099 Thanks to tychoish. 5100* PR#151: Some styling updates to tables in LaTeX. 5101* PR#153: The "extensions" config value can now be overridden. 5102* PR#155: Added support for some C++11 function qualifiers. 5103* Fix: 'make gettext' caused UnicodeDecodeError when templates contain utf-8 5104 encoded strings. 5105* #828: use inspect.getfullargspec() to be able to document functions with 5106 keyword-only arguments on Python 3. 5107* #1090: Fix i18n: multiple cross references (term, ref, doc) in the same line 5108 return the same link. 5109* #1157: Combination of 'globaltoc.html' and hidden toctree caused exception. 5110* #1159: fix wrong generation of objects inventory for Python modules, and 5111 add a workaround in intersphinx to fix handling of affected inventories. 5112* #1160: Citation target missing caused an AssertionError. 5113* #1162, PR#139: singlehtml builder didn't copy images to _images/. 5114* #1173: Adjust setup.py dependencies because Jinja2 2.7 discontinued 5115 compatibility with Python < 3.3 and Python < 2.6. Thanks to Alexander Dupuy. 5116* #1185: Don't crash when a Python module has a wrong or no encoding declared, 5117 and non-ASCII characters are included. 5118* #1188: sphinx-quickstart raises UnicodeEncodeError if "Project version" 5119 includes non-ASCII characters. 5120* #1189: "Title underline is too short" WARNING is given when using fullwidth 5121 characters to "Project name" on quickstart. 5122* #1190: Output TeX/texinfo/man filename has no basename (only extension) 5123 when using non-ASCII characters in the "Project name" on quickstart. 5124* #1192: Fix escaping problem for hyperlinks in the manpage writer. 5125* #1193: Fix i18n: multiple link references in the same line return the same 5126 link. 5127* #1176: Fix i18n: footnote reference number missing for auto numbered named 5128 footnote and auto symbol footnote. 5129* PR#146,#1172: Fix ZeroDivisionError in parallel builds. Thanks to tychoish. 5130* #1204: Fix wrong generation of links to local intersphinx targets. 5131* #1206: Fix i18n: gettext did not translate admonition directive's title. 5132* #1232: Sphinx generated broken ePub files on Windows. 5133* #1259: Guard the debug output call when emitting events; to prevent the 5134 repr() implementation of arbitrary objects causing build failures. 5135* #1142: Fix NFC/NFD normalizing problem of rst filename on Mac OS X. 5136* #1234: Ignoring the string consists only of white-space characters. 5137 5138 5139Release 1.2 beta1 (released Mar 31, 2013) 5140========================================= 5141 5142Incompatible changes 5143-------------------- 5144 5145* Removed ``sphinx.util.compat.directive_dwim()`` and 5146 ``sphinx.roles.xfileref_role()`` which were deprecated since version 1.0. 5147* PR#122: the files given in `latex_additional_files` now override TeX 5148 files included by Sphinx, such as ``sphinx.sty``. 5149* PR#124: the node generated by `versionadded`, 5150 `versionchanged` and `deprecated` directives now includes 5151 all added markup (such as "New in version X") as child nodes, and no 5152 additional text must be generated by writers. 5153* PR#99: the :rst:dir:`seealso` directive now generates admonition nodes instead 5154 of the custom ``seealso`` node. 5155 5156Features added 5157-------------- 5158 5159* Markup 5160 5161 - The :rst:dir:`toctree` directive and the ``toctree()`` template function now 5162 have an ``includehidden`` option that includes hidden toctree entries (bugs 5163 #790 and #1047). A bug in the ``maxdepth`` option for the ``toctree()`` 5164 template function has been fixed (bug #1046). 5165 - PR#99: Strip down seealso directives to normal admonitions. This removes 5166 their unusual CSS classes (admonition-see-also), inconsistent LaTeX 5167 admonition title ("See Also" instead of "See also"), and spurious 5168 indentation in the text builder. 5169 5170* HTML builder 5171 5172 - #783: Create a link to full size image if it is scaled with width or height. 5173 - #1067: Improve the ordering of the JavaScript search results: matches in 5174 titles come before matches in full text, and object results are better 5175 categorized. Also implement a pluggable search scorer. 5176 - #1053: The "rightsidebar" and "collapsiblesidebar" HTML theme options now 5177 work together. 5178 - Update to jQuery 1.7.1 and Underscore.js 1.3.1. 5179 5180* Texinfo builder 5181 5182 - An "Index" node is no longer added when there are no entries. 5183 - "deffn" categories are no longer capitalized if they contain capital 5184 letters. 5185 - ``desc_annotation`` nodes are now rendered. 5186 - ``strong`` and ``emphasis`` nodes are now formatted like 5187 ``literal``\s. The reason for this is because the standard Texinfo markup 5188 (``*strong*`` and ``_emphasis_``) resulted in confusing output due to the 5189 common usage of using these constructs for documenting parameter names. 5190 - Field lists formatting has been tweaked to better display 5191 "Info field lists". 5192 - ``system_message`` and ``problematic`` nodes are now formatted in a similar 5193 fashion as done by the text builder. 5194 - "en-dash" and "em-dash" conversion of hyphens is no longer performed in 5195 option directive signatures. 5196 - ``@ref`` is now used instead of ``@pxref`` for cross-references which 5197 prevents the word "see" from being added before the link (does not affect 5198 the Info output). 5199 - The ``@finalout`` command has been added for better TeX output. 5200 - ``transition`` nodes are now formatted using underscores ("_") instead of 5201 asterisks ("*"). 5202 - The default value for the ``paragraphindent`` has been changed from 2 to 0 5203 meaning that paragraphs are no longer indented by default. 5204 - #1110: A new configuration value `texinfo_no_detailmenu` has been 5205 added for controlling whether a ``@detailmenu`` is added in the "Top" 5206 node's menu. 5207 - Detailed menus are no longer created except for the "Top" node. 5208 - Fixed an issue where duplicate domain indices would result in invalid 5209 output. 5210 5211* LaTeX builder: 5212 5213 - PR#115: Add ``'transition'`` item in `latex_elements` for 5214 customizing how transitions are displayed. Thanks to Jeff Klukas. 5215 - PR#114: The LaTeX writer now includes the "cmap" package by default. The 5216 ``'cmappkg'`` item in `latex_elements` can be used to control this. 5217 Thanks to Dmitry Shachnev. 5218 - The ``'fontpkg'`` item in `latex_elements` now defaults to ``''`` 5219 when the :confval:`language` uses the Cyrillic script. Suggested by Dmitry 5220 Shachnev. 5221 - The `latex_documents`, `texinfo_documents`, and 5222 `man_pages` configuration values will be set to default values based 5223 on the :confval:`master_doc` if not explicitly set in :file:`conf.py`. 5224 Previously, if these values were not set, no output would be generated by 5225 their respective builders. 5226 5227* Internationalization: 5228 5229 - Add i18n capabilities for custom templates. For example: The Sphinx 5230 reference documentation in doc directory provides a ``sphinx.pot`` file with 5231 message strings from ``doc/_templates/*.html`` when using ``make gettext``. 5232 5233 - PR#61,#703: Add support for non-ASCII filename handling. 5234 5235* Other builders: 5236 5237 - Added the Docutils-native XML and pseudo-XML builders. See 5238 :class:`XMLBuilder` and :class:`PseudoXMLBuilder`. 5239 - PR#45: The linkcheck builder now checks ``#anchor``\ s for existence. 5240 - PR#123, #1106: Add `epub_use_index` configuration value. If 5241 provided, it will be used instead of `html_use_index` for epub 5242 builder. 5243 - PR#126: Add `epub_tocscope` configuration value. The setting 5244 controls the generation of the epub toc. The user can now also include 5245 hidden toc entries. 5246 - PR#112: Add `epub_show_urls` configuration value. 5247 5248* Extensions: 5249 5250 - PR#52: ``special_members`` flag to autodoc now behaves like ``members``. 5251 - PR#47: Added :mod:`sphinx.ext.linkcode` extension. 5252 - PR#25: In inheritance diagrams, the first line of the class docstring 5253 is now the tooltip for the class. 5254 5255* Command-line interfaces: 5256 5257 - PR#75: Added ``--follow-links`` option to sphinx-apidoc. 5258 - #869: sphinx-build now has the option ``-T`` for printing the full 5259 traceback after an unhandled exception. 5260 - sphinx-build now supports the standard ``--help`` and ``--version`` options. 5261 - sphinx-build now provides more specific error messages when called with 5262 invalid options or arguments. 5263 - sphinx-build now has a verbose option ``-v`` which can be repeated for 5264 greater effect. A single occurrence provides a slightly more verbose output 5265 than normal. Two or more occurrences of this option provides more detailed 5266 output which may be useful for debugging. 5267 5268* Locales: 5269 5270 - PR#74: Fix some Russian translation. 5271 - PR#54: Added Norwegian bokmaal translation. 5272 - PR#35: Added Slovak translation. 5273 - PR#28: Added Hungarian translation. 5274 - #1113: Add Hebrew locale. 5275 - #1097: Add Basque locale. 5276 - #1037: Fix typos in Polish translation. Thanks to Jakub Wilk. 5277 - #1012: Update Estonian translation. 5278 5279* Optimizations: 5280 5281 - Speed up building the search index by caching the results of the word 5282 stemming routines. Saves about 20 seconds when building the Python 5283 documentation. 5284 - PR#108: Add experimental support for parallel building with a new 5285 :option:`sphinx-build -j` option. 5286 5287Documentation 5288------------- 5289 5290* PR#88: Added the "Sphinx Developer's Guide" (:file:`doc/devguide.rst`) 5291 which outlines the basic development process of the Sphinx project. 5292* Added a detailed "Installing Sphinx" document (:file:`doc/install.rst`). 5293 5294Bugs fixed 5295---------- 5296 5297* PR#124: Fix paragraphs in versionmodified are ignored when it has no 5298 dangling paragraphs. Fix wrong html output (nested ``<p>`` tag). Fix 5299 versionmodified is not translatable. Thanks to Nozomu Kaneko. 5300* PR#111: Respect add_autodoc_attrgetter() even when inherited-members is set. 5301 Thanks to A. Jesse Jiryu Davis. 5302* PR#97: Fix footnote handling in translated documents. 5303* Fix text writer not handling visit_legend for figure directive contents. 5304* Fix text builder not respecting wide/fullwidth characters: title underline 5305 width, table layout width and text wrap width. 5306* Fix leading space in LaTeX table header cells. 5307* #1132: Fix LaTeX table output for multi-row cells in the first column. 5308* #1128: Fix Unicode errors when trying to format time strings with a 5309 non-standard locale. 5310* #1127: Fix traceback when autodoc tries to tokenize a non-Python file. 5311* #1126: Fix double-hyphen to en-dash conversion in wrong places such as 5312 command-line option names in LaTeX. 5313* #1123: Allow whitespaces in filenames given to `literalinclude`. 5314* #1120: Added improvements about i18n for themes "basic", "haiku" and 5315 "scrolls" that Sphinx built-in. Thanks to Leonardo J. Caballero G. 5316* #1118: Updated Spanish translation. Thanks to Leonardo J. Caballero G. 5317* #1117: Handle .pyx files in sphinx-apidoc. 5318* #1112: Avoid duplicate download files when referenced from documents in 5319 different ways (absolute/relative). 5320* #1111: Fix failure to find uppercase words in search when 5321 `html_search_language` is 'ja'. Thanks to Tomo Saito. 5322* #1108: The text writer now correctly numbers enumerated lists with 5323 non-default start values (based on patch by Ewan Edwards). 5324* #1102: Support multi-context "with" statements in autodoc. 5325* #1090: Fix gettext not extracting glossary terms. 5326* #1074: Add environment version info to the generated search index to avoid 5327 compatibility issues with old builds. 5328* #1070: Avoid un-pickling issues when running Python 3 and the saved 5329 environment was created under Python 2. 5330* #1069: Fixed error caused when autodoc would try to format signatures of 5331 "partial" functions without keyword arguments (patch by Artur Gaspar). 5332* #1062: sphinx.ext.autodoc use __init__ method signature for class signature. 5333* #1055: Fix web support with relative path to source directory. 5334* #1043: Fix sphinx-quickstart asking again for yes/no questions because 5335 ``input()`` returns values with an extra '\r' on Python 3.2.0 + 5336 Windows. Thanks to Régis Décamps. 5337* #1041: Fix failure of the cpp domain parser to parse a const type with a 5338 modifier. 5339* #1038: Fix failure of the cpp domain parser to parse C+11 "static constexpr" 5340 declarations. Thanks to Jakub Wilk. 5341* #1029: Fix intersphinx_mapping values not being stable if the mapping has 5342 plural key/value set with Python 3.3. 5343* #1028: Fix line block output in the text builder. 5344* #1024: Improve Makefile/make.bat error message if Sphinx is not found. Thanks 5345 to Anatoly Techtonik. 5346* #1018: Fix "container" directive handling in the text builder. 5347* #1015: Stop overriding jQuery contains() in the JavaScript. 5348* #1010: Make pngmath images transparent by default; IE7+ should handle it. 5349* #1008: Fix test failures with Python 3.3. 5350* #995: Fix table-of-contents and page numbering for the LaTeX "howto" class. 5351* #976: Fix gettext does not extract index entries. 5352* PR#72: #975: Fix gettext not extracting definition terms before docutils 0.10. 5353* #961: Fix LaTeX output for triple quotes in code snippets. 5354* #958: Do not preserve ``environment.pickle`` after a failed build. 5355* #955: Fix i18n transformation. 5356* #940: Fix gettext does not extract figure caption. 5357* #920: Fix PIL packaging issue that allowed to import ``Image`` without PIL 5358 namespace. Thanks to Marc Schlaich. 5359* #723: Fix the search function on local files in WebKit based browsers. 5360* #440: Fix coarse timestamp resolution in some filesystem generating a wrong 5361 list of outdated files. 5362 5363 5364Release 1.1.3 (Mar 10, 2012) 5365============================ 5366 5367* PR#40: Fix ``safe_repr`` function to decode bytestrings with non-ASCII 5368 characters correctly. 5369 5370* PR#37: Allow configuring sphinx-apidoc via ``SPHINX_APIDOC_OPTIONS``. 5371 5372* PR#34: Restore Python 2.4 compatibility. 5373 5374* PR#36: Make the "bibliography to TOC" fix in LaTeX output specific to 5375 the document class. 5376 5377* #695: When the highlight language "python" is specified explicitly, 5378 do not try to parse the code to recognize non-Python snippets. 5379 5380* #859: Fix exception under certain circumstances when not finding 5381 appropriate objects to link to. 5382 5383* #860: Do not crash when encountering invalid doctest examples, just 5384 emit a warning. 5385 5386* #864: Fix crash with some settings of `modindex_common_prefix`. 5387 5388* #862: Fix handling of ``-D`` and ``-A`` options on Python 3. 5389 5390* #851: Recognize and warn about circular toctrees, instead of running 5391 into recursion errors. 5392 5393* #853: Restore compatibility with docutils trunk. 5394 5395* #852: Fix HtmlHelp index entry links again. 5396 5397* #854: Fix inheritance_diagram raising attribute errors on builtins. 5398 5399* #832: Fix crashes when putting comments or lone terms in a glossary. 5400 5401* #834, #818: Fix HTML help language/encoding mapping for all Sphinx 5402 supported languages. 5403 5404* #844: Fix crashes when dealing with Unicode output in doctest extension. 5405 5406* #831: Provide ``--project`` flag in setup_command as advertised. 5407 5408* #875: Fix reading config files under Python 3. 5409 5410* #876: Fix quickstart test under Python 3. 5411 5412* #870: Fix spurious KeyErrors when removing documents. 5413 5414* #892: Fix single-HTML builder misbehaving with the master document in a 5415 subdirectory. 5416 5417* #873: Fix assertion errors with empty ``only`` directives. 5418 5419* #816: Fix encoding issues in the Qt help builder. 5420 5421 5422Release 1.1.2 (Nov 1, 2011) -- 1.1.1 is a silly version number anyway! 5423====================================================================== 5424 5425* #809: Include custom fixers in the source distribution. 5426 5427 5428Release 1.1.1 (Nov 1, 2011) 5429=========================== 5430 5431* #791: Fix QtHelp, DevHelp and HtmlHelp index entry links. 5432 5433* #792: Include "sphinx-apidoc" in the source distribution. 5434 5435* #797: Don't crash on a misformatted glossary. 5436 5437* #801: Make intersphinx work properly without SSL support. 5438 5439* #805: Make the ``Sphinx.add_index_to_domain`` method work correctly. 5440 5441* #780: Fix Python 2.5 compatibility. 5442 5443 5444Release 1.1 (Oct 9, 2011) 5445========================= 5446 5447Incompatible changes 5448-------------------- 5449 5450* The `py:module` directive doesn't output its ``platform`` option 5451 value anymore. (It was the only thing that the directive did output, and 5452 therefore quite inconsistent.) 5453 5454* Removed support for old dependency versions; requirements are now: 5455 5456 - Pygments >= 1.2 5457 - Docutils >= 0.7 5458 - Jinja2 >= 2.3 5459 5460Features added 5461-------------- 5462 5463* Added Python 3.x support. 5464 5465* New builders and subsystems: 5466 5467 - Added a Texinfo builder. 5468 - Added i18n support for content, a ``gettext`` builder and related 5469 utilities. 5470 - Added the ``websupport`` library and builder. 5471 - #98: Added a ``sphinx-apidoc`` script that autogenerates a hierarchy 5472 of source files containing autodoc directives to document modules 5473 and packages. 5474 - #273: Add an API for adding full-text search support for languages 5475 other than English. Add support for Japanese. 5476 5477* Markup: 5478 5479 - #138: Added an :rst:role:`index` role, to make inline index entries. 5480 - #454: Added more index markup capabilities: marking see/seealso entries, 5481 and main entries for a given key. 5482 - #460: Allowed limiting the depth of section numbers for HTML using the 5483 :rst:dir:`toctree`\'s ``numbered`` option. 5484 - #586: Implemented improved :rst:dir:`glossary` markup which allows 5485 multiple terms per definition. 5486 - #478: Added `py:decorator` directive to describe decorators. 5487 - C++ domain now supports array definitions. 5488 - C++ domain now supports doc fields (``:param x:`` inside directives). 5489 - Section headings in :rst:dir:`only` directives are now correctly 5490 handled. 5491 - Added ``emphasize-lines`` option to source code directives. 5492 - #678: C++ domain now supports superclasses. 5493 5494* HTML builder: 5495 5496 - Added ``pyramid`` theme. 5497 - #559: `html_add_permalinks` is now a string giving the 5498 text to display in permalinks. 5499 - #259: HTML table rows now have even/odd CSS classes to enable 5500 "Zebra styling". 5501 - #554: Add theme option ``sidebarwidth`` to the basic theme. 5502 5503* Other builders: 5504 5505 - #516: Added new value of the `latex_show_urls` option to 5506 show the URLs in footnotes. 5507 - #209: Added `text_newlines` and `text_sectionchars` 5508 config values. 5509 - Added `man_show_urls` config value. 5510 - #472: linkcheck builder: Check links in parallel, use HTTP HEAD 5511 requests and allow configuring the timeout. New config values: 5512 `linkcheck_timeout` and `linkcheck_workers`. 5513 - #521: Added `linkcheck_ignore` config value. 5514 - #28: Support row/colspans in tables in the LaTeX builder. 5515 5516* Configuration and extensibility: 5517 5518 - #537: Added `nitpick_ignore`. 5519 - #306: Added :event:`env-get-outdated` event. 5520 - :meth:`.Application.add_stylesheet` now accepts full URIs. 5521 5522* Autodoc: 5523 5524 - #564: Add `autodoc_docstring_signature`. When enabled (the 5525 default), autodoc retrieves the signature from the first line of the 5526 docstring, if it is found there. 5527 - #176: Provide ``private-members`` option for autodoc directives. 5528 - #520: Provide ``special-members`` option for autodoc directives. 5529 - #431: Doc comments for attributes can now be given on the same line 5530 as the assignment. 5531 - #437: autodoc now shows values of class data attributes. 5532 - autodoc now supports documenting the signatures of 5533 ``functools.partial`` objects. 5534 5535* Other extensions: 5536 5537 - Added the :mod:`sphinx.ext.mathjax` extension. 5538 - #443: Allow referencing external graphviz files. 5539 - Added ``inline`` option to graphviz directives, and fixed the 5540 default (block-style) in LaTeX output. 5541 - #590: Added ``caption`` option to graphviz directives. 5542 - #553: Added `testcleanup` blocks in the doctest extension. 5543 - #594: `trim_doctest_flags` now also removes ``<BLANKLINE>`` 5544 indicators. 5545 - #367: Added automatic exclusion of hidden members in inheritance 5546 diagrams, and an option to selectively enable it. 5547 - Added ``pngmath_add_tooltips``. 5548 - The math extension displaymath directives now support ``name`` in 5549 addition to ``label`` for giving the equation label, for compatibility 5550 with Docutils. 5551 5552* New locales: 5553 5554 - #221: Added Swedish locale. 5555 - #526: Added Iranian locale. 5556 - #694: Added Latvian locale. 5557 - Added Nepali locale. 5558 - #714: Added Korean locale. 5559 - #766: Added Estonian locale. 5560 5561* Bugs fixed: 5562 5563 - #778: Fix "hide search matches" link on pages linked by search. 5564 - Fix the source positions referenced by the "viewcode" extension. 5565 5566 5567Release 1.0.8 (Sep 23, 2011) 5568============================ 5569 5570* #627: Fix tracebacks for AttributeErrors in autosummary generation. 5571 5572* Fix the ``abbr`` role when the abbreviation has newlines in it. 5573 5574* #727: Fix the links to search results with custom object types. 5575 5576* #648: Fix line numbers reported in warnings about undefined 5577 references. 5578 5579* #696, #666: Fix C++ array definitions and template arguments 5580 that are not type names. 5581 5582* #633: Allow footnotes in section headers in LaTeX output. 5583 5584* #616: Allow keywords to be linked via intersphinx. 5585 5586* #613: Allow Unicode characters in production list token names. 5587 5588* #720: Add dummy visitors for graphviz nodes for text and man. 5589 5590* #704: Fix image file duplication bug. 5591 5592* #677: Fix parsing of multiple signatures in C++ domain. 5593 5594* #637: Ignore Emacs lock files when looking for source files. 5595 5596* #544: Allow .pyw extension for importable modules in autodoc. 5597 5598* #700: Use ``$(MAKE)`` in quickstart-generated Makefiles. 5599 5600* #734: Make sidebar search box width consistent in browsers. 5601 5602* #644: Fix spacing of centered figures in HTML output. 5603 5604* #767: Safely encode SphinxError messages when printing them to 5605 sys.stderr. 5606 5607* #611: Fix LaTeX output error with a document with no sections but 5608 a link target. 5609 5610* Correctly treat built-in method descriptors as methods in autodoc. 5611 5612* #706: Stop monkeypatching the Python textwrap module. 5613 5614* #657: viewcode now works correctly with source files that have 5615 non-ASCII encoding. 5616 5617* #669: Respect the ``noindex`` flag option in py:module directives. 5618 5619* #675: Fix IndexErrors when including nonexisting lines with 5620 `literalinclude`. 5621 5622* #676: Respect custom function/method parameter separator strings. 5623 5624* #682: Fix JS incompatibility with jQuery >= 1.5. 5625 5626* #693: Fix double encoding done when writing HTMLHelp .hhk files. 5627 5628* #647: Do not apply SmartyPants in parsed-literal blocks. 5629 5630* C++ domain now supports array definitions. 5631 5632 5633Release 1.0.7 (Jan 15, 2011) 5634============================ 5635 5636* #347: Fix wrong generation of directives of static methods in 5637 autosummary. 5638 5639* #599: Import PIL as ``from PIL import Image``. 5640 5641* #558: Fix longtables with captions in LaTeX output. 5642 5643* Make token references work as hyperlinks again in LaTeX output. 5644 5645* #572: Show warnings by default when reference labels cannot be 5646 found. 5647 5648* #536: Include line number when complaining about missing reference 5649 targets in nitpicky mode. 5650 5651* #590: Fix inline display of graphviz diagrams in LaTeX output. 5652 5653* #589: Build using app.build() in setup command. 5654 5655* Fix a bug in the inheritance diagram exception that caused base 5656 classes to be skipped if one of them is a builtin. 5657 5658* Fix general index links for C++ domain objects. 5659 5660* #332: Make admonition boundaries in LaTeX output visible. 5661 5662* #573: Fix KeyErrors occurring on rebuild after removing a file. 5663 5664* Fix a traceback when removing files with globbed toctrees. 5665 5666* If an autodoc object cannot be imported, always re-read the 5667 document containing the directive on next build. 5668 5669* If an autodoc object cannot be imported, show the full traceback 5670 of the import error. 5671 5672* Fix a bug where the removal of download files and images wasn't 5673 noticed. 5674 5675* #571: Implement ``~`` cross-reference prefix for the C domain. 5676 5677* Fix regression of LaTeX output with the fix of #556. 5678 5679* #568: Fix lookup of class attribute documentation on descriptors 5680 so that comment documentation now works. 5681 5682* Fix traceback with ``only`` directives preceded by targets. 5683 5684* Fix tracebacks occurring for duplicate C++ domain objects. 5685 5686* Fix JavaScript domain links to objects with ``$`` in their name. 5687 5688 5689Release 1.0.6 (Jan 04, 2011) 5690============================ 5691 5692* #581: Fix traceback in Python domain for empty cross-reference 5693 targets. 5694 5695* #283: Fix literal block display issues on Chrome browsers. 5696 5697* #383, #148: Support sorting a limited range of accented characters 5698 in the general index and the glossary. 5699 5700* #570: Try decoding ``-D`` and ``-A`` command-line arguments with 5701 the locale's preferred encoding. 5702 5703* #528: Observe `locale_dirs` when looking for the JS 5704 translations file. 5705 5706* #574: Add special code for better support of Japanese documents 5707 in the LaTeX builder. 5708 5709* Regression of #77: If there is only one parameter given with 5710 ``:param:`` markup, the bullet list is now suppressed again. 5711 5712* #556: Fix missing paragraph breaks in LaTeX output in certain 5713 situations. 5714 5715* #567: Emit the ``autodoc-process-docstring`` event even for objects 5716 without a docstring so that it can add content. 5717 5718* #565: In the LaTeX builder, not only literal blocks require different 5719 table handling, but also quite a few other list-like block elements. 5720 5721* #515: Fix tracebacks in the viewcode extension for Python objects 5722 that do not have a valid signature. 5723 5724* Fix strange reports of line numbers for warnings generated from 5725 autodoc-included docstrings, due to different behavior depending 5726 on docutils version. 5727 5728* Several fixes to the C++ domain. 5729 5730 5731Release 1.0.5 (Nov 12, 2010) 5732============================ 5733 5734* #557: Add CSS styles required by docutils 0.7 for aligned images 5735 and figures. 5736 5737* In the Makefile generated by LaTeX output, do not delete pdf files 5738 on clean; they might be required images. 5739 5740* #535: Fix LaTeX output generated for line blocks. 5741 5742* #544: Allow ``.pyw`` as a source file extension. 5743 5744 5745Release 1.0.4 (Sep 17, 2010) 5746============================ 5747 5748* #524: Open intersphinx inventories in binary mode on Windows, 5749 since version 2 contains zlib-compressed data. 5750 5751* #513: Allow giving non-local URIs for JavaScript files, e.g. 5752 in the JSMath extension. 5753 5754* #512: Fix traceback when ``intersphinx_mapping`` is empty. 5755 5756 5757Release 1.0.3 (Aug 23, 2010) 5758============================ 5759 5760* #495: Fix internal vs. external link distinction for links coming 5761 from a docutils table-of-contents. 5762 5763* #494: Fix the ``maxdepth`` option for the ``toctree()`` template 5764 callable when used with ``collapse=True``. 5765 5766* #507: Fix crash parsing Python argument lists containing brackets 5767 in string literals. 5768 5769* #501: Fix regression when building LaTeX docs with figures that 5770 don't have captions. 5771 5772* #510: Fix inheritance diagrams for classes that are not picklable. 5773 5774* #497: Introduce separate background color for the sidebar collapse 5775 button, making it easier to see. 5776 5777* #502, #503, #496: Fix small layout bugs in several builtin themes. 5778 5779 5780Release 1.0.2 (Aug 14, 2010) 5781============================ 5782 5783* #490: Fix cross-references to objects of types added by the 5784 :func:`~.Sphinx.add_object_type` API function. 5785 5786* Fix handling of doc field types for different directive types. 5787 5788* Allow breaking long signatures, continuing with backlash-escaped 5789 newlines. 5790 5791* Fix unwanted styling of C domain references (because of a namespace 5792 clash with Pygments styles). 5793 5794* Allow references to PEPs and RFCs with explicit anchors. 5795 5796* #471: Fix LaTeX references to figures. 5797 5798* #482: When doing a non-exact search, match only the given type 5799 of object. 5800 5801* #481: Apply non-exact search for Python reference targets with 5802 ``.name`` for modules too. 5803 5804* #484: Fix crash when duplicating a parameter in an info field list. 5805 5806* #487: Fix setting the default role to one provided by the 5807 ``oldcmarkup`` extension. 5808 5809* #488: Fix crash when json-py is installed, which provides a 5810 ``json`` module but is incompatible to simplejson. 5811 5812* #480: Fix handling of target naming in intersphinx. 5813 5814* #486: Fix removal of ``!`` for all cross-reference roles. 5815 5816 5817Release 1.0.1 (Jul 27, 2010) 5818============================ 5819 5820* #470: Fix generated target names for reST domain objects; they 5821 are not in the same namespace. 5822 5823* #266: Add Bengali language. 5824 5825* #473: Fix a bug in parsing JavaScript object names. 5826 5827* #474: Fix building with SingleHTMLBuilder when there is no toctree. 5828 5829* Fix display names for objects linked to by intersphinx with 5830 explicit targets. 5831 5832* Fix building with the JSON builder. 5833 5834* Fix hyperrefs in object descriptions for LaTeX. 5835 5836 5837Release 1.0 (Jul 23, 2010) 5838========================== 5839 5840Incompatible changes 5841-------------------- 5842 5843* Support for domains has been added. A domain is a collection of 5844 directives and roles that all describe objects belonging together, 5845 e.g. elements of a programming language. A few builtin domains are 5846 provided: 5847 5848 - Python 5849 - C 5850 - C++ 5851 - JavaScript 5852 - reStructuredText 5853 5854* The old markup for defining and linking to C directives is now 5855 deprecated. It will not work anymore in future versions without 5856 activating the :mod:`~sphinx.ext.oldcmarkup` extension; in Sphinx 5857 1.0, it is activated by default. 5858 5859* Removed support for old dependency versions; requirements are now: 5860 5861 - docutils >= 0.5 5862 - Jinja2 >= 2.2 5863 5864* Removed deprecated elements: 5865 5866 - ``exclude_dirs`` config value 5867 - ``sphinx.builder`` module 5868 5869Features added 5870-------------- 5871 5872* General: 5873 5874 - Added a "nitpicky" mode that emits warnings for all missing 5875 references. It is activated by the :option:`sphinx-build -n` command-line 5876 switch or the :confval:`nitpicky` config value. 5877 - Added ``latexpdf`` target in quickstart Makefile. 5878 5879* Markup: 5880 5881 - The `menuselection` and `guilabel` roles now 5882 support ampersand accelerators. 5883 - New more compact doc field syntax is now recognized: ``:param type 5884 name: description``. 5885 - Added ``tab-width`` option to `literalinclude` directive. 5886 - Added ``titlesonly`` option to :rst:dir:`toctree` directive. 5887 - Added the ``prepend`` and ``append`` options to the 5888 `literalinclude` directive. 5889 - #284: All docinfo metadata is now put into the document metadata, not 5890 just the author. 5891 - The `ref` role can now also reference tables by caption. 5892 - The :dudir:`include` directive now supports absolute paths, which 5893 are interpreted as relative to the source directory. 5894 - In the Python domain, references like ``:func:`.name``` now look for 5895 matching names with any prefix if no direct match is found. 5896 5897* Configuration: 5898 5899 - Added `rst_prolog` config value. 5900 - Added `html_secnumber_suffix` config value to control 5901 section numbering format. 5902 - Added `html_compact_lists` config value to control 5903 docutils' compact lists feature. 5904 - The `html_sidebars` config value can now contain patterns 5905 as keys, and the values can be lists that explicitly select which 5906 sidebar templates should be rendered. That means that the builtin 5907 sidebar contents can be included only selectively. 5908 - `html_static_path` can now contain single file entries. 5909 - The new universal config value `exclude_patterns` makes the 5910 old ``unused_docs``, ``exclude_trees`` and 5911 ``exclude_dirnames`` obsolete. 5912 - Added `html_output_encoding` config value. 5913 - Added the `latex_docclass` config value and made the 5914 "twoside" documentclass option overridable by "oneside". 5915 - Added the `trim_doctest_flags` config value, which is true 5916 by default. 5917 - Added `html_show_copyright` config value. 5918 - Added `latex_show_pagerefs` and `latex_show_urls` 5919 config values. 5920 - The behavior of `html_file_suffix` changed slightly: the 5921 empty string now means "no suffix" instead of "default suffix", use 5922 ``None`` for "default suffix". 5923 5924* New builders: 5925 5926 - Added a builder for the Epub format. 5927 - Added a builder for manual pages. 5928 - Added a single-file HTML builder. 5929 5930* HTML output: 5931 5932 - Inline roles now get a CSS class with their name, allowing styles to 5933 customize their appearance. Domain-specific roles get two classes, 5934 ``domain`` and ``domain-rolename``. 5935 - References now get the class ``internal`` if they are internal to 5936 the whole project, as opposed to internal to the current page. 5937 - External references can be styled differently with the new 5938 ``externalrefs`` theme option for the default theme. 5939 - In the default theme, the sidebar can experimentally now be made 5940 collapsible using the new ``collapsiblesidebar`` theme option. 5941 - #129: Toctrees are now wrapped in a ``div`` tag with class 5942 ``toctree-wrapper`` in HTML output. 5943 - The :data:`toctree` callable in templates now has a ``maxdepth`` 5944 keyword argument to control the depth of the generated tree. 5945 - The :data:`toctree` callable in templates now accepts a 5946 ``titles_only`` keyword argument. 5947 - Added ``htmltitle`` block in layout template. 5948 - In the JavaScript search, allow searching for object names including 5949 the module name, like ``sys.argv``. 5950 - Added new theme ``haiku``, inspired by the Haiku OS user guide. 5951 - Added new theme ``nature``. 5952 - Added new theme ``agogo``, created by Andi Albrecht. 5953 - Added new theme ``scrolls``, created by Armin Ronacher. 5954 - #193: Added a ``visitedlinkcolor`` theme option to the default 5955 theme. 5956 - #322: Improved responsiveness of the search page by loading the 5957 search index asynchronously. 5958 5959* Extension API: 5960 5961 - Added :event:`html-collect-pages`. 5962 - Added `needs_sphinx` config value and 5963 :meth:`~sphinx.application.Sphinx.require_sphinx` application API 5964 method. 5965 - #200: Added :meth:`~sphinx.application.Sphinx.add_stylesheet` 5966 application API method. 5967 5968* Extensions: 5969 5970 - Added the :mod:`~sphinx.ext.viewcode` extension. 5971 - Added the :mod:`~sphinx.ext.extlinks` extension. 5972 - Added support for source ordering of members in autodoc, with 5973 ``autodoc_member_order = 'bysource'``. 5974 - Added `autodoc_default_flags` config value, which can be 5975 used to select default flags for all autodoc directives. 5976 - Added a way for intersphinx to refer to named labels in other 5977 projects, and to specify the project you want to link to. 5978 - #280: Autodoc can now document instance attributes assigned in 5979 ``__init__`` methods. 5980 - Many improvements and fixes to the :mod:`~sphinx.ext.autosummary` 5981 extension, thanks to Pauli Virtanen. 5982 - #309: The :mod:`~sphinx.ext.graphviz` extension can now output SVG 5983 instead of PNG images, controlled by the 5984 `graphviz_output_format` config value. 5985 - Added ``alt`` option to :rst:dir:`graphviz` extension directives. 5986 - Added ``exclude`` argument to :func:`.autodoc.between`. 5987 5988* Translations: 5989 5990 - Added Croatian translation, thanks to Bojan Mihelač. 5991 - Added Turkish translation, thanks to Firat Ozgul. 5992 - Added Catalan translation, thanks to Pau Fernández. 5993 - Added simplified Chinese translation. 5994 - Added Danish translation, thanks to Hjorth Larsen. 5995 - Added Lithuanian translation, thanks to Dalius Dobravolskas. 5996 5997* Bugs fixed: 5998 5999 - #445: Fix links to result pages when using the search function 6000 of HTML built with the ``dirhtml`` builder. 6001 - #444: In templates, properly re-escape values treated with the 6002 "striptags" Jinja filter. 6003 6004 6005Previous versions 6006================= 6007 6008The changelog for versions before 1.0 can be found in the file ``CHANGES.old`` 6009in the source distribution or `at GitHub 6010<https://github.com/sphinx-doc/sphinx/raw/master/CHANGES.old>`__. 6011