sphinx/doc/changes/1.5.rst

==========
Sphinx 1.5
==========


Release 1.5.6 (released May 15, 2017)
=====================================

Bugs fixed
----------

* #3614: Sphinx crashes with requests-2.5.0
* #3618: autodoc crashes with tupled arguments
* #3664: No space after the bullet in items of a latex list produced by Sphinx
* #3657: EPUB builder crashes if a document starting with genindex exists
* #3588: No compact (p tag) html output in the i18n document build even when
  :confval:`html_compact_lists` is ``True``.
* #3685: AttributeError when using 3rd party domains
* #3702: LaTeX writer styles figure legends with a hard-coded ``\small``
* #3708: LaTeX writer allows irc scheme
* #3717: Stop enforcing that favicon's must be .ico
* #3731, #3732: Protect isenumclass predicate against non-class arguments
* #3320: Warning about reference target not being found for container types
* Misspelled ARCHIVEPREFIX in Makefile for latex build repertory

Release 1.5.5 (released Apr 03, 2017)
=====================================

Bugs fixed
----------

* #3597: python domain raises UnboundLocalError if invalid name given
* #3599: Move to new MathJax CDN

Release 1.5.4 (released Apr 02, 2017)
=====================================

Features added
--------------

* #3470: Make genindex support all kinds of letters, not only Latin ones

Bugs fixed
----------

* #3445: setting ``'inputenc'`` key to ``\\usepackage[utf8x]{inputenc}`` leads
  to failed PDF build
* EPUB file has duplicated ``nav.xhtml`` link in ``content.opf``
  except first time build
* #3488: objects.inv has broken when ``release`` or ``version`` contain
  return code
* #2073, #3443, #3490: gettext builder that writes pot files unless the content
  are same without creation date. Thanks to Yoshiki Shibukawa.
* #3487: intersphinx: failed to refer options
* #3496: latex longtable's last column may be much wider than its contents
* #3507: wrong quotes in latex output for productionlist directive
* #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of links
  rendered as code
* #2665, #2607: Link names in C++ docfields, and make it possible for other
  domains.
* #3542: C++, fix parsing error of non-type template argument with template.
* #3065, #3520: python domain fails to recognize nested class
* #3575: Problems with pdflatex in a Turkish document built with Sphinx has
  reappeared (refs #2997, #2397)
* #3577: Fix intersphinx debug tool
* A LaTeX command such as ``\\large`` inserted in the title items of
  :confval:`latex_documents` causes failed PDF build (refs #3551, #3567)

Release 1.5.3 (released Feb 26, 2017)
=====================================

Features added
--------------

* Support requests-2.0.0 (experimental) (refs: #3367)
* (latex) PDF page margin dimensions may be customized (refs: #3387)
* ``literalinclude`` directive allows combination of ``:pyobject:`` and
  ``:lines:`` options (refs: #3416)
* #3400: make-mode doesn't use subprocess on building docs

Bugs fixed
----------

* #3370: the caption of code-block is not picked up for translation
* LaTeX: :confval:`release` is not escaped (refs: #3362)
* #3364: sphinx-quickstart prompts overflow on Console with 80 chars width
* since 1.5, PDF's TOC and bookmarks lack an entry for general Index
  (refs: #3383)
* #3392: ``'releasename'`` in :confval:`latex_elements` is not working
* #3356: Page layout for Japanese ``'manual'`` docclass has a shorter text area
* #3394: When ``'pointsize'`` is not ``10pt``, Japanese ``'manual'`` document
  gets wrong PDF page dimensions
* #3399: quickstart: conf.py was not overwritten by template
* #3366: option directive does not allow punctuations
* #3410: return code in :confval:`release` breaks html search
* #3427: autodoc: memory addresses are not stripped on Windows
* #3428: xetex build tests fail due to fontspec v2.6 defining ``\strong``
* #3349: Result of ``IndexBuilder.load()`` is broken
* #3450: &nbsp is appeared in EPUB docs
* #3418: Search button is misaligned in nature and pyramid theme
* #3421: Could not translate a caption of tables
* #3552: linkcheck raises UnboundLocalError

Release 1.5.2 (released Jan 22, 2017)
=====================================

Incompatible changes
--------------------

* Dependency requirement updates: requests 2.4.0 or above (refs: #3268, #3310)

Features added
--------------

* #3241: emit latex warning if buggy titlesec (ref #3210)
* #3194: Refer the $MAKE environment variable to determine ``make`` command
* Emit warning for nested numbered toctrees (refs: #3142)
* #978: ``intersphinx_mapping`` also allows a list as a parameter
* #3340: (LaTeX) long lines in :dudir:`parsed-literal` are wrapped like in
  :rst:dir:`code-block`, inline math and footnotes are fully functional.

Bugs fixed
----------

* #3246: xapian search adapter crashes
* #3253: In Py2 environment, building another locale with a non-captioned
  toctree produces ``None`` captions
* #185: References to section title including raw node has broken
* #3255: In Py3.4 environment, autodoc doesn't support documentation for
  attributes of Enum class correctly.
* #3261: ``latex_use_parts`` makes Sphinx crash
* The warning type ``misc.highlighting_failure`` does not work
* #3294: ``add_latex_package()`` make crashes non-LaTeX builders
* The caption of table are rendered as invalid HTML (refs: #3287)
* #3268: Sphinx crashes with requests package from Debian jessie
* #3284: Sphinx crashes on parallel build with an extension which raises
  unserializable exception
* #3315: Bibliography crashes on latex build with docclass 'memoir'
* #3328: Could not refer rubric implicitly
* #3329: emit warnings if po file is invalid and can't read it. Also writing mo
* #3337: Ugly rendering of definition list term's classifier
* #3335: gettext does not extract field_name of a field in a field_list
* #2952: C++, fix refs to operator() functions.
* Fix Unicode super- and subscript digits in :rst:dir:`code-block` and
  parsed-literal LaTeX output (ref #3342)
* LaTeX writer: leave ``"`` character inside parsed-literal as is (ref #3341)
* #3234: intersphinx failed for encoded inventories
* #3158: too much space after captions in PDF output
* #3317: An URL in parsed-literal contents gets wrongly rendered in PDF if
  with hyphen
* LaTeX crash if the filename of an image inserted in parsed-literal
  via a substitution contains an hyphen (ref #3340)
* LaTeX rendering of inserted footnotes in parsed-literal is wrong (ref #3340)
* Inline math in parsed-literal is not rendered well by LaTeX (ref #3340)
* #3308: Parsed-literals don't wrap very long lines with pdf builder (ref #3340)
* #3295: Could not import extension sphinx.builders.linkcheck
* #3285: autosummary: asterisks are escaped twice
* LaTeX, pass dvipdfm option to geometry package for Japanese documents (ref
  #3363)
* Fix parselinenos() could not parse left half open range (cf. "-4")


Release 1.5.1 (released Dec 13, 2016)
=====================================

Features added
--------------

* #3214: Allow to suppress "unknown mimetype" warnings from epub builder using
  :confval:`suppress_warnings`.

Bugs fixed
----------

* #3195: Can not build in parallel
* #3198: AttributeError is raised when toctree has 'self'
* #3211: Remove untranslated Sphinx locale catalogs (it was covered by
  untranslated it_IT)
* #3212: HTML Builders crashes with Docutils 0.13
* #3207: more latex problems with references inside parsed-literal directive
  (``\DUrole``)
* #3205: sphinx.util.requests crashes with old pyOpenSSL (< 0.14)
* #3220: KeyError when having a duplicate citation
* #3200: LaTeX: xref inside desc_name not allowed
* #3228: ``build_sphinx`` command crashes when missing dependency
* #2469: Ignore updates of catalog files for gettext builder. Thanks to
  Hiroshi Ohkubo.
* #3183: Randomized jump box order in generated index page.

Release 1.5 (released Dec 5, 2016)
==================================

Incompatible changes
--------------------

1.5a1

* latex, package fancybox is not any longer a dependency of sphinx.sty
* Use ``'locales'`` as a default value of ``locale_dirs``
* latex, package ifthen is not any longer a dependency of sphinx.sty
* latex, style file does not modify fancyvrb's Verbatim (also available as
  OriginalVerbatim) but uses sphinxVerbatim for name of custom wrapper.
* latex, package newfloat is not used (and not included) anymore (ref #2660;
  it was used since 1.3.4 and shipped with Sphinx since 1.4).
* latex, literal blocks in tables do not use OriginalVerbatim but
  sphinxVerbatimintable which handles captions and wraps lines (ref #2704).
* latex, replace ``pt`` by TeX equivalent ``bp`` if found in ``width`` or
  ``height`` attribute of an image.
* latex, if ``width`` or ``height`` attribute of an image is given with no unit,
  use ``px`` rather than ignore it.
* latex: Separate stylesheets of pygments to independent .sty file
* #2454: The filename of sourcelink is now changed.  The value of
  ``html_sourcelink_suffix`` will be appended to the original filename (like
  ``index.rst.txt``).
* ``sphinx.util.copy_static_entry()`` is now deprecated.
  Use ``sphinx.util.fileutil.copy_asset()`` instead.
* ``sphinx.util.osutil.filecopy()`` skips copying if the file has not been
  changed (ref: #2510, #2753)
* Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped
  because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634, #2773)
* QtHelpBuilder doesn't generate search page (ref: #2352)
* QtHelpBuilder uses ``nonav`` theme instead of default one
  to improve readability.
* latex: To provide good default settings to Japanese documents, Sphinx uses
  ``jreport`` and ``jsbook`` as docclass if :confval:`language` is
  ``ja``.
* ``sphinx-quickstart`` now allows a project version is empty
* Fix :download: role on epub/qthelp builder. They ignore the role because they
  don't support it.
* ``sphinx.ext.viewcode`` doesn't work on epub building by default.
  ``viewcode_enable_epub`` option
* ``sphinx.ext.viewcode`` disabled on singlehtml builder.
* Use make-mode of ``sphinx-quickstart`` by default.  To disable this, use
  ``-M`` option
* Fix ``genindex.html``, Sphinx's document template, link address to itself to
  satisfy xhtml standard.
* Use epub3 builder by default.  And the old epub builder is renamed to epub2.
* Fix ``epub`` and ``epub3`` builders that contained links to ``genindex`` even
  if ``epub_use_index = False``.
* ``html_translator_class`` is now deprecated.
  Use :meth:`~sphinx.application.Sphinx.set_translator` API instead.
* Drop python 2.6 and 3.3 support
* Drop epub3 builder's ``epub3_page_progression_direction`` option (use
  ``epub3_writing_mode``).
* #2877: Rename ``latex_elements['footer']`` to
  ``latex_elements['atendofbody']``

1.5a2

* #2983: Rename ``epub3_description`` and ``epub3_contributor`` to
  ``epub_description`` and ``epub_contributor``.
* Remove themes/basic/defindex.html; no longer used
* Sphinx does not ship anymore (but still uses) LaTeX style file ``fncychap``
* #2435: Slim down quickstarted conf.py
* The ``sphinx.sty`` latex package does not load itself "hyperref", as this
  is done later in the preamble of the latex output via ``'hyperref'`` key.
* Sphinx does not ship anymore a custom modified LaTeX style file ``tabulary``.
  The non-modified package is used.
* #3057: By default, footnote marks in latex PDF output are not preceded by a
  space anymore, ``\sphinxBeforeFootnote`` allows user customization if needed.
* LaTeX target requires that option ``hyperfootnotes`` of package ``hyperref``
  be left unchanged to its default (i.e. ``true``) (refs: #3022)

1.5 final

* #2986: ``themes/basic/defindex.html`` is now deprecated
* Emit warnings that will be deprecated in Sphinx 1.6 by default.
  Users can change the behavior by setting the environment variable
  PYTHONWARNINGS. Please refer :ref:`when-deprecation-warnings-are-displayed`.
* #2454: new JavaScript variable ``SOURCELINK_SUFFIX`` is added

Deprecated
----------

These features are removed in Sphinx 1.6:

* LDML format support in i18n feature
* ``sphinx.addnodes.termsep``
* Some functions and classes in ``sphinx.util.pycompat``:
  ``zip_longest``, ``product``, ``all``, ``any``, ``next``, ``open``,
  ``class_types``, ``base_exception``, ``relpath``, ``StringIO``, ``BytesIO``.
  Please use the standard library version instead;

If any deprecation warning like ``RemovedInSphinxXXXWarning`` are displayed,
please refer :ref:`when-deprecation-warnings-are-displayed`.

Features added
--------------

1.5a1

* #2951: Add ``--implicit-namespaces`` PEP-0420 support to apidoc.
* Add ``:caption:`` option for sphinx.ext.inheritance_diagram.
* #2471: Add config variable for default doctest flags.
* Convert linkcheck builder to requests for better encoding handling
* #2463, #2516: Add keywords of "meta" directive to search index
* ``:maxdepth:`` option of toctree affects ``secnumdepth`` (ref: #2547)
* #2575: Now ``sphinx.ext.graphviz`` allows ``:align:`` option
* Show warnings if unknown key is specified to ``latex_elements``
* Show warnings if no domains match with ``primary_domain`` (ref: #2001)
* C++, show warnings when the kind of role is misleading for the kind
  of target it refers to (e.g., using the ``class`` role for a function).
* latex, writer abstracts more of text styling into customizable macros, e.g.
  the ``visit_emphasis`` will output ``\sphinxstyleemphasis`` rather than
  ``\emph`` (which may be in use elsewhere or in an added LaTeX package). See
  list at end of ``sphinx.sty`` (ref: #2686)
* latex, public names for environments and parameters used by note, warning,
  and other admonition types, allowing full customizability from the
  ``'preamble'`` key or an input file (ref: feature request #2674, #2685)
* latex, better computes column widths of some tables (as a result, there will
  be slight changes as tables now correctly fill the line width; ref: #2708)
* latex, sphinxVerbatim environment is more easily customizable (ref: #2704).
  In addition to already existing VerbatimColor and VerbatimBorderColor:

  - two lengths ``\sphinxverbatimsep`` and ``\sphinxverbatimborder``,
  - booleans ``\ifsphinxverbatimwithframe`` and ``\ifsphinxverbatimwrapslines``.

* latex, captions for literal blocks inside tables are handled, and long code
  lines wrapped to fit table cell (ref: #2704)
* #2597: Show warning messages as darkred
* latex, allow image dimensions using px unit (default is 96px=1in)
* Show warnings if invalid dimension units found
* #2650: Add ``--pdb`` option to setup.py command
* latex, make the use of ``\small`` for code listings customizable (ref #2721)
* #2663: Add ``--warning-is-error`` option to setup.py command
* Show warnings if deprecated latex options are used
* Add sphinx.config.ENUM to check the config values is in candidates
* math: Add hyperlink marker to each equations in HTML output
* Add new theme ``nonav`` that doesn't include any navigation links.
  This is for any help generator like qthelp.
* #2680: ``sphinx.ext.todo`` now emits warnings if ``todo_emit_warnings`` enabled.
  Also, it emits an additional event named ``todo-defined`` to handle the TODO
  entries in 3rd party extensions.
* Python domain signature parser now uses the xref mixin for 'exceptions',
  allowing exception classes to be autolinked.
* #2513: Add ``latex_engine`` to switch the LaTeX engine by conf.py
* #2682: C++, basic support for attributes (C++11 style and GNU style).
  The new configuration variables 'cpp_id_attributes' and 'cpp_paren_attributes'
  can be used to introduce custom attributes.
* #1958: C++, add configuration variable 'cpp_index_common_prefix' for removing
  prefixes from the index text of C++ objects.
* C++, added concept directive. Thanks to mickk-on-cpp.
* C++, added support for template introduction syntax. Thanks to mickk-on-cpp.
* #2725: latex builder: allow to use user-defined template file (experimental)
* apidoc now avoids invalidating cached files by not writing to files whose
  content doesn't change. This can lead to significant performance wins if
  apidoc is run frequently.
* #2851: ``sphinx.ext.math`` emits missing-reference event if equation not found
* #1210: ``eqref`` role now supports cross reference
* #2892: Added ``-a`` (``--append-syspath``) option to ``sphinx-apidoc``
* #1604: epub3 builder: Obey font-related CSS when viewing in iBooks.
* #646: ``option`` directive support '.' character as a part of options
* Add document about kindlegen and fix document structure for it.
* #2474: Add ``intersphinx_timeout`` option to ``sphinx.ext.intersphinx``
* #2926: EPUB3 builder supports vertical mode (``epub3_writing_mode`` option)
* #2695: ``build_sphinx`` subcommand for setuptools handles exceptions as same
  as ``sphinx-build`` does
* #326: ``numref`` role can also refer sections
* #2916: ``numref`` role can also refer caption as an its linktext

1.5a2

* #3008: ``linkcheck`` builder ignores self-signed certificate URL
* #3020: new ``'geometry'`` key to ``latex_elements`` whose default uses
  LaTeX style file ``geometry.sty`` to set page layout
* #2843: Add :start-at: and :end-at: options to literalinclude directive
* #2527: Add ``:reversed:`` option to toctree directive
* Add ``-t`` and ``-d`` option to ``sphinx-quickstart`` to support templating
  generated Sphinx project.
* #3028: Add ``{path}`` and ``{basename}`` to the format of
  ``figure_language_filename``
* new ``'hyperref'`` key in the ``latex_elements`` dictionary (ref #3030)
* #3022: Allow code-blocks in footnotes for LaTeX PDF output

1.5b1

* #2513: A better default settings for XeLaTeX
* #3096: ``'maxlistdepth'`` key to work around LaTeX list limitations
* #3060: autodoc supports documentation for attributes of Enum class. Now
  autodoc render just the value of Enum attributes instead of Enum attribute
  representation.
* Add ``--extensions`` to ``sphinx-quickstart`` to support enable arbitrary
  extensions from command line (ref: #2904)
* #3104, #3122: ``'sphinxsetup'`` for key=value styling of Sphinx LaTeX
* #3071: Autodoc: Allow mocked module decorators to pass-through functions
  unchanged
* #2495: linkcheck: Allow skipping anchor checking using
  :confval:`linkcheck_anchors_ignore`
* #3083: let Unicode no-break space act like LaTeX ``~`` (fixed #3019)
* #3116: allow word wrap in PDF output for inline literals (ref #3110)
* #930: sphinx-apidoc allow wildcards for excluding paths. Thanks to Nick
  Coghlan.
* #3121: add ``inlineliteralwraps`` option to control if inline literal
  word-wraps in latex

1.5 final

* #3095: Add :confval:`tls_verify` and :confval:`tls_cacerts` to support
  self-signed HTTPS servers in linkcheck and intersphinx
* #2215: make.bat generated by sphinx-quickstart can be called from another dir.
  Thanks to Timotheus Kampik.
* #3185: Add new warning type ``misc.highlighting_failure``

Bugs fixed
----------

1.5a1

* #2707: (latex) the column width is badly computed for tabular
* #2799: Sphinx installs roles and directives automatically on importing sphinx
  module.  Now Sphinx installs them on running application.
* ``sphinx.ext.autodoc`` crashes if target code imports * from mock modules
  by ``autodoc_mock_imports``.
* #1953: ``Sphinx.add_node`` does not add handlers the translator installed by
  ``html_translator_class``
* #1797: text builder inserts blank line on top
* #2894: quickstart main() doesn't use argv argument
* #2874: gettext builder could not extract all text under the ``only``
  directives
* #2485: autosummary crashes with multiple source_suffix values
* #1734: Could not translate the caption of toctree directive
* Could not translate the content of meta directive (ref: #1734)
* #2550: external links are opened in help viewer
* #2687: Running Sphinx multiple times produces 'already registered' warnings

1.5a2

* #2810: Problems with pdflatex in an Italian document
* Use ``latex_elements.papersize`` to specify papersize of LaTeX in Makefile
* #2988: linkcheck: retry with GET request if denied HEAD request
* #2990: linkcheck raises "Can't convert 'bytes' object to str implicitly" error
  if linkcheck_anchors enabled
* #3004: Invalid link types "top" and "up" are used
* #3009: Bad rendering of parsed-literals in LaTeX since Sphinx 1.4.4
* #3000: ``option`` directive generates invalid HTML anchors
* #2984: Invalid HTML has been generated if ``html_split_index`` enabled
* #2986: themes/basic/defindex.html should be changed for html5 friendly
* #2987: Invalid HTML has been generated if multiple IDs are assigned to a list
* #2891: HTML search does not provide all the results
* #1986: Title in PDF Output
* #147: Problem with latex chapter style
* #3018: LaTeX problem with page layout dimensions and chapter titles
* Fix an issue with ``\pysigline`` in LaTeX style file (ref #3023)
* #3038: ``sphinx.ext.math*`` raises TypeError if labels are duplicated
* #3031: incompatibility with LaTeX package ``tocloft``
* #3003: literal blocks in footnotes are not supported by Latex
* #3047: spacing before footnote in pdf output is not coherent and allows breaks
* #3045: HTML search index creator should ignore "raw" content if now html
* #3039: English stemmer returns wrong word if the word is capitalized
* Fix make-mode Makefile template (ref #3056, #2936)

1.5b1

* #2432: Fix unwanted * between varargs and keyword only args. Thanks to Alex
  Grönholm.
* #3062: Failed to build PDF using 1.5a2 (undefined ``\hypersetup`` for
  Japanese documents since PR#3030)
* Better rendering of multiline signatures in html.
* #777: LaTeX output "too deeply nested" (ref #3096)
* Let LaTeX image inclusion obey ``scale`` before textwidth fit (ref #2865,
  #3059)
* #3019: LaTeX fails on description of C function with arguments (ref #3083)
* fix latex inline literals where ``< > -`` gobbled a space

1.5 final

* #3069: Even if ``'babel'`` key is set to empty string, LaTeX output contains
  one ``\addto\captions...``
* #3123: user ``'babel'`` key setting is not obeyed anymore
* #3155: Fix JavaScript for ``html_sourcelink_suffix`` fails with IE and Opera
* #3085: keep current directory after breaking build documentation. Thanks to
  Timotheus Kampik.
* #3181: pLaTeX crashes with a section contains endash
* #3180: latex: add stretch/shrink between successive singleline or
  multipleline cpp signatures (ref #3072)
* #3128: globing images does not support .svgz file
* #3015: fix a broken test on Windows.
* #1843: Fix documentation of descriptor classes that have a custom metaclass.
  Thanks to Erik Bray.
* #3190: util.split_docinfo fails to parse multi-line field bodies
* #3024, #3037: In Python3, application.Sphinx._log crushed when the log message
  cannot be encoded into console encoding.

Testing
-------

* To simplify, Sphinx uses external mock package even if ``unittest.mock`` exists.