diff options
Diffstat (limited to '')
| -rw-r--r-- | CHANGES.rst (renamed from CHANGES) | 730 |
1 files changed, 505 insertions, 225 deletions
@@ -1,3 +1,279 @@ +Release 7.3.7 (released Apr 19, 2024) +===================================== + +Bugs fixed +---------- + +* #12299: Defer loading themes defined via entry points until + their explicit use by the user or a child theme. + Patch by Adam Turner. +* #12305: Return the default value for ``theme.get_config()`` with + an unsupported theme configuration section. + Patch by Adam Turner. + +Release 7.3.6 (released Apr 17, 2024) +===================================== + +Bugs fixed +---------- + +* #12295: Re-export all AST types in the C and C++ domains. + Patch by Adam Turner. +* #12295: Re-export various objects from ``sphinx.domains.python._annotations`` + in ``sphinx.domains.python``. + Patch by Jacob Chesslo and Adam Turner. + +Release 7.3.5 (released Apr 17, 2024) +===================================== + +Bugs fixed +---------- + +* #12295: Re-export various objects from ``sphinx.domains.python._object`` + in ``sphinx.domains.python``. + Patch by Jacob Chesslo and Adam Turner. + +Release 7.3.4 (released Apr 17, 2024) +===================================== + +Bugs fixed +---------- + +* Handle cases when ``Any`` is not an instance of ``type``. + Patch by Adam Turner. + +Release 7.3.3 (released Apr 17, 2024) +===================================== + +Bugs fixed +---------- + +* #12290: Fix a false-positive warning when setting a configuration value + with ``Any`` as the valid type to a type other than the value's default. + Patch by Adam Turner. + +Release 7.3.2 (released Apr 17, 2024) +===================================== + +Bugs fixed +---------- + +* Preload all themes defined via entry points. + Patch by Adam Turner. +* Fix a bad interaction between the ``'Furo'`` theme and the new-style for + configuration values. + Patch by Adam Turner. + +Release 7.3.1 (released Apr 17, 2024) +===================================== + +Dependencies +------------ + +* Require ``tomli`` on Python 3.10 and earlier. + Patch by Adam Turner. + +Release 7.3.0 (released Apr 16, 2024) +===================================== + +Dependencies +------------ + +* #11858: Increase the minimum supported version of Alabaster to 0.7.14. + Patch by Adam Turner. +* #11411: Support `Docutils 0.21`_. Patch by Adam Turner. + + .. _Docutils 0.21: https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-21-2024-04-09 +* #12012: Use ``types-docutils`` instead of ``docutils-stubs``. + +Deprecated +---------- + +* #11693: Support for old-style :file:`Makefile` and :file:`make.bat` output + in :program:`sphinx-quickstart`, and the associated options :option:`!-M`, + :option:`!-m`, :option:`!--no-use-make-mode`, and :option:`!--use-make-mode`. +* #11285: Direct access to :attr:`!sphinx.testing.util.SphinxTestApp._status` + or :attr:`!sphinx.testing.util.SphinxTestApp._warning` is deprecated. Use + the public properties :attr:`!sphinx.testing.util.SphinxTestApp.status` + and :attr:`!sphinx.testing.util.SphinxTestApp.warning` instead. + Patch by Bénédikt Tran. +* tests: :func:`!sphinx.testing.util.strip_escseq` is deprecated in favour of + :func:`!sphinx.util.console.strip_colors`. + Patch by Bénédikt Tran. + +Features added +-------------- + +* #12265: Support theme configuration via ``theme.toml``. +* #11701: HTML Search: Adopt the new `\<search\>`_ element. + Patch by Bénédikt Tran. + + .. _`\<search\>`: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/search +* #11776: Add long option names to ``sphinx-build``. + Patch by Hugo van Kemenade, Adam Turner, Bénédikt Tran, and Ezio Melotti. +* Organise the ``sphinx-build`` options into groups. + Patch by Adam Turner. +* #11855: Defer computation of configuration values. + Patch by Adam Turner. +* Add ``:no-search:`` as an alias of the ``:nosearch:`` metadata field. + Patch by Adam Turner. +* #11803: autodoc: Use an overriden ``__repr__()`` function in an enum, + if defined. Patch by Shengyu Zhang. +* #11825: Allow custom targets in the manpage role. + Patch by Nicolas Peugnet. +* #11892: Improved performance when resolving cross references in the C++ domain. + Patch by Rouslan Korneychuk. +* #11905: Add a :rst:dir:`versionremoved` directive. + Patch by Hugo van Kemenade, Adam Turner, and C.A.M. Gerlach. +* #11981: Improve rendering of signatures using ``slice`` syntax, + e.g., ``def foo(arg: np.float64[:,:]) -> None: ...``. +* The manpage builder now adds `OSC 8`_ anchors to hyperlinks, using + the `groff`_ device control command. + + .. _OSC 8: https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda + .. _groff: https://lists.gnu.org/archive/html/groff/2021-10/msg00000.html +* #11015: Change the text of the :rst:dir:`versionadded` directive from + ``New in [...]`` to ``Added in [...]``. + Patch by Bénédikt Tran. +* #12131: Added :confval:`show_warning_types` configuration option. + Patch by Chris Sewell. +* #12193: Improve ``external`` warnings for unknown roles. + In particular, suggest related role names if an object type is mistakenly used. + Patch by Chris Sewell. +* Add public type alias :class:`sphinx.util.typing.ExtensionMetadata`. + This can be used by extension developers + to annotate the return type of their ``setup`` function. + Patch by Chris Sewell. + +Bugs fixed +---------- + +* #11668: Raise a useful error when ``theme.conf`` is missing. + Patch by Vinay Sajip. +* #11622: Ensure that the order of keys in ``searchindex.js`` is deterministic. + Patch by Pietro Albini. +* #11617: ANSI control sequences are stripped from the output when writing to + a warnings file with :option:`-w <sphinx-build -w>`. + Patch by Bénédikt Tran. +* #11666: Skip all hidden directories in ``CatalogRepository.pofiles``. + Patch by Aryaz Eghbali. +* #9686: html builder: Fix MathJax lazy loading when equations appear in titles. + Patch by Bénédikt Tran. +* #11483: singlehtml builder: Fix MathJax lazy loading when the index does not + contain any math equations. + Patch by Bénédikt Tran. +* #11697: HTML Search: add 'noindex' meta robots tag. + Patch by James Addison. +* #11678: Fix a possible ``ZeroDivisionError`` in ``sphinx.ext.coverage``. + Patch by Stephen Finucane. +* #11756: LaTeX: build error with recent TeXLive due to missing ``substitutefont`` + package (triggered if using ``fontenc`` with ``T2A`` option and document + language is not a Cyrillic one). + Patch by Jean-François B. +* #11675: Fix rendering of progression bars in environments that do not support + ANSI control sequences. + Patch by Bénédikt Tran. +* #11861: Whitelist more types with an incorrect ``__module__`` attribute. + Patch by Adam Turner. +* #11715: Apply ``tls_verify`` and ``tls_cacerts`` config to + ``ImageDownloader``. + Patch by Nick Touran. +* Allow hyphens in group names for :rst:dir:`productionlist` cross-references. + Patch by Adam Turner. +* #11433: Added the :confval:`linkcheck_allow_unauthorized` configuration option. + Set this option to ``False`` to report HTTP 401 (unauthorized) server + responses as broken. + Patch by James Addison. +* #11868: linkcheck: added a distinct ``timeout`` reporting status code. + This can be enabled by setting :confval:`linkcheck_report_timeouts_as_broken` + to ``False``. + Patch by James Addison. +* #11869: Refresh the documentation for the ``linkcheck_timeout`` setting. + Patch by James Addison. +* #11874: Configure a default 30-second value for ``linkcheck_timeout``. + Patch by James Addison. +* #11886: Print the Jinja2 template path chain in ``TemplateNotFound`` exceptions. + Patch by Colin Marquardt. +* #11598: Do not use query components in URLs for assets in EPUB rendering. + Patch by David Runge. +* #11904: Support unary subtraction when parsing annotations. + Patch by James Addison. +* #11925: Blacklist the ``sphinxprettysearchresults`` extension; the functionality + it provides was merged into Sphinx v2.0.0. + Patch by James Addison. +* #11917: Fix rendering of annotated inherited members for Python 3.9. + Patch by Janet Carson. +* #11935: C Domain: Fix namespace-pop context. + Patch by Frank Dana. +* #11923: Avoid zombie processes when parallel builds fail. + Patch by Felix von Drigalski. +* #11353: Support enumeration classes inheriting from mixin or data types. + Patch by Bénédikt Tran. +* #11962: Fix target resolution when using ``:paramtype:`` fields. + Patch by Bénédikt Tran. +* #11944: Use anchor in search preview. + Patch by Will Lachance. +* #12008: Fix case-sensitive lookup of ``std:label`` names in intersphinx inventory. + Patch by Michael Goerz. +* #11958: HTML Search: Fix partial matches overwriting full matches. + Patch by William Lachance. +* #11959: Fix multiple term matching when word appears in both title and document. + Patch by Will Lachance. +* #11474: Fix doctrees caching causing files not be rebuilt in some cases, + e.g., when :confval:`numfig` is ``True``. + Patch by Bénédikt Tran. +* #11278: autodoc: Fix rendering of :class:`functools.singledispatchmethod` + combined with :func:`@classmethod <classmethod>`. + Patch by Bénédikt Tran. +* #11894: Do not add checksums to css files if building using the htmlhelp builder. + Patch by reduerK akiM. +* #12052: Remove ``<script>`` and ``<style>`` tags from the content of search result + summary snippets. + Patch by James Addison. +* #11578: HTML Search: Order non-main index entries after other results. + Patch by Brad King. +* #12147: autosummary: Fix a bug whereby the wrong file extension + may be used, + when multiple suffixes are specified in :confval:`source_suffix`. + Patch by Sutou Kouhei. +* #10786: improve the error message when a file to be copied (e.g., an asset) + is removed during Sphinx execution. + Patch by Bénédikt Tran. +* #12040: HTML Search: Ensure that document titles that are partially-matched by + the user search query are included in search results. + Patch by James Addison. +* #11970: singlehtml builder: make target URIs to be same-document references in + the sense of :rfc:`RFC 3986, §4.4 <3986#section-4.4>`, e.g., ``index.html#foo`` + becomes ``#foo``. Patch by Eric Norige. +* #12271: Partially revert Docutils' r9562__ to fix EPUB files. + Patch by Adam Turner. + + __ https://sourceforge.net/p/docutils/code/9562/ +* #12253: Escape reserved path characters in the remote images post-transform + download cache. + Patch by James Addison and Adam Turner. + +Testing +------- + +* Reorganise tests into directories. + Patch by Adam Turner. +* Clean up global state in ``SphinxTestApp``. + Patch by Adam Turner. +* #11285: :func:`!pytest.mark.sphinx` and :class:`!sphinx.testing.util.SphinxTestApp` + accept *warningiserror*, *keep_going* and *verbosity* as keyword arguments. + Patch by Bénédikt Tran. +* #11285: :class:`!sphinx.testing.util.SphinxTestApp` *status* and *warning* + arguments are checked to be :class:`io.StringIO` objects (the public API + incorrectly assumed this without checking it). + Patch by Bénédikt Tran. +* Report the result of ``test_run_epubcheck`` as ``skipped`` instead of + ``success`` when either Java or ``epubcheck`` are not available. +* Use dynamic allocation of unused port numbers for the test HTTP(S) servers. + As a side-effect, this removes the need for test server lockfiles, + meaning that any remaining ``tests/test-server.lock`` files can safely be + deleted. + Release 7.2.6 (released Sep 13, 2023) ===================================== @@ -89,7 +365,8 @@ Bugs fixed ---------- * Restored the the :py:class:`str` interface of the asset classes - (``_CascadingStyleSheet`` and ``_JavaScript``), which several extensions relied upon. + (``_CascadingStyleSheet`` and ``_JavaScript``), + which several extensions relied upon. This will be removed in Sphinx 9. * Restored calls to ``Builder.add_{css,js}_file()``, which several extensions relied upon. @@ -649,8 +926,9 @@ Release 5.3.0 (released Oct 16, 2022) * #10759: LaTeX: add :confval:`latex_table_style` and support the ``'booktabs'``, ``'borderless'``, and ``'colorrows'`` styles. (thanks to Stefan Wiehler for initial pull requests #6666, #6671) -* #10840: One can cross-reference including an option value like ``:option:`--module=foobar```, - ``:option:`--module[=foobar]``` or ``:option:`--module foobar```. +* #10840: One can cross-reference including an option value like + ``:option:`--module=foobar```, ``:option:`--module[=foobar]```, + or ``:option:`--module foobar```. Patch by Martin Liska. * #10881: autosectionlabel: Record the generated section label to the debug log. * #10268: Correctly URI-escape image filenames. @@ -804,8 +1082,8 @@ Bugs fixed * #8686: LaTeX: Text can fall out of code-block at end of page and leave artifact on next page * #10633: LaTeX: user injected ``\color`` commands in topic or admonition boxes may - cause color leaks in PDF due to upstream `framed.sty <https://ctan.org/pkg/framed>`_ - bug + cause color leaks in PDF due to upstream `framed.sty + <https://ctan.org/pkg/framed>`_ bug * #10638: LaTeX: framed coloured boxes in highlighted code (e.g. highlighted diffs using Pygments style ``'manni'``) inherit thickness of code-block frame * #10647: LaTeX: Only one ``\label`` is generated for ``desc_signature`` node @@ -1173,7 +1451,7 @@ Bugs fixed * #9844: autodoc: Failed to process a function wrapped with functools.partial if :confval:`autodoc_preserve_defaults` enabled * #9872: html: Class namespace collision between autodoc signatures and - docutils-0.17 + Docutils 0.17 * #9868: imgmath: Crashed if the dvisvgm command failed to convert equation * #9864: mathjax: Failed to render equations via MathJax v2. The loading method of MathJax is back to "async" method again @@ -1192,7 +1470,7 @@ Incompatible changes * #9649: ``searchindex.js``: the embedded data has changed format to allow objects with the same name in different domains. * #9672: The rendering of Python domain declarations is implemented - with more docutils nodes to allow better CSS styling. + with more Docutils nodes to allow better CSS styling. It may break existing styling. * #9672: the signature of ``domains.python.PyObject.get_signature_prefix`` has changed to @@ -1201,7 +1479,7 @@ Incompatible changes ``get_display_prefix`` which now returns a list of nodes instead of a plain string. * #9695: The rendering of Javascript domain declarations is implemented - with more docutils nodes to allow better CSS styling. + with more Docutils nodes to allow better CSS styling. It may break existing styling. * #9450: mathjax: Load MathJax via "defer" strategy @@ -1407,7 +1685,7 @@ Features added * #3257: autosummary: Support instance attributes for classes * #9358: html: Add "heading" role to the toctree items * #9225: html: Add span tag to the return typehint of method/function -* #9129: html search: Show search summaries when html_copy_source = False +* #9129: html search: Show search summaries when ``html_copy_source = False`` * #9307: html search: Prevent corrections and completions in search field * #9120: html theme: Eliminate prompt characters of code-block from copyable text @@ -1548,12 +1826,12 @@ Dependencies 4.0.0b1 * Drop python 3.5 support -* Drop docutils 0.12 and 0.13 support +* Drop Docutils 0.12 and 0.13 support * LaTeX: add ``tex-gyre`` font dependency 4.0.0b2 -* Support docutils-0.17. Please notice it changes the output of HTML builder. +* Support Docutils 0.17. Please notice it changes the output of HTML builder. Some themes do not support it, and you need to update your custom CSS to upgrade it. @@ -1585,7 +1863,7 @@ Incompatible changes * html theme: Move a script tag for documentation_options.js in basic/layout.html to ``script_files`` variable * html theme: Move CSS tags in basic/layout.html to ``css_files`` variable -* #8915: html theme: Emit a warning for sphinx_rtd_theme-0.2.4 or older +* #8915: html theme: Emit a warning for ``sphinx_rtd_theme`` 0.2.4 or older * #8508: LaTeX: uplatex becomes a default setting of latex_engine for Japanese documents * #5977: py domain: ``:var:``, ``:cvar:`` and ``:ivar:`` fields do not create @@ -1679,9 +1957,10 @@ Bugs fixed * #8415: autodoc: a TypeVar imported from other module is not resolved (in Python 3.7 or above) * #8992: autodoc: Failed to resolve types.TracebackType type annotation -* #8905: html: html_add_permalinks=None and html_add_permalinks="" are ignored +* #8905: html: ``html_add_permalinks=None`` and ``html_add_permalinks=""`` + are ignored * #8380: html search: Paragraphs in search results are not identified as ``<p>`` -* #8915: html theme: The translation of sphinx_rtd_theme does not work +* #8915: html theme: The translation of ``sphinx_rtd_theme`` does not work * #8342: Emit a warning if a unknown domain is given for directive or role (ex. ``:unknown:doc:``) * #7241: LaTeX: No wrapping for ``cpp:enumerator`` @@ -1727,14 +2006,14 @@ Release 3.5.4 (released Apr 11, 2021) Dependencies ------------ -* #9071: Restrict docutils to 0.16 +* #9071: Restrict Docutils to 0.16 Bugs fixed ---------- * #9078: autodoc: Async staticmethods and classmethods are considered as non async coroutine-functions with Python3.10 -* #8870, #9001, #9051: html theme: The style are not applied with docutils-0.17 +* #8870, #9001, #9051: html theme: The style are not applied with Docutils 0.17 - toctree captions - The content of ``sidebar`` directive @@ -1869,7 +2148,7 @@ Bugs fixed * #741: autodoc: inherited-members doesn't work for instance attributes on super class * #8592: autodoc: ``:meta public:`` does not effect to variables -* #8594: autodoc: empty __all__ attribute is ignored +* #8594: autodoc: empty ``__all__`` attribute is ignored * #8315: autodoc: Failed to resolve struct.Struct type annotation * #8652: autodoc: All variable comments in the module are ignored if the module contains invalid type comments @@ -1920,9 +2199,9 @@ Bugs fixed * #8214: LaTeX: The :rst:role:`index` role and the glossary generate duplicate entries in the LaTeX index (if both used for same term) * #8735: LaTeX: wrong internal links in pdf to captioned code-blocks when - :confval:`numfig` is not True + :confval:`numfig` is not ``True`` * #8442: LaTeX: some indexed terms are ignored when using xelatex engine - (or pdflatex and :confval:`latex_use_xindy` set to True) with memoir class + (or pdflatex and :confval:`latex_use_xindy` set to ``True``) with memoir class * #8750: LaTeX: URLs as footnotes fail to show in PDF if originating from inside function type signatures * #8780: LaTeX: long words in narrow columns may not be hyphenated @@ -2015,8 +2294,8 @@ Features added * #8219: autodoc: Parameters for generic class are not shown when super class is a generic class and show-inheritance option is given (in Python 3.7 or above) * autodoc: Add ``Documenter.config`` as a shortcut to access the config object -* autodoc: Add Optional[t] to annotation of function and method if a default - value equal to None is set. +* autodoc: Add ``Optional[t]`` to annotation of function and method if a default + value equal to ``None`` is set. * #8209: autodoc: Add ``:no-value:`` option to :rst:dir:`autoattribute` and :rst:dir:`autodata` directive to suppress the default value of the variable * #8460: autodoc: Support custom types defined by typing.NewType @@ -2127,8 +2406,8 @@ Bugs fixed * #8085: i18n: Add support for having single text domain * #6640: i18n: Failed to override system message translation -* #8143: autodoc: AttributeError is raised when False value is passed to - autodoc_default_options +* #8143: autodoc: ``AttributeError`` is raised when ``False`` value is passed to + :confval:`autodoc_default_options` * #8103: autodoc: functools.cached_property is not considered as a property * #8190: autodoc: parsing error is raised if some extension replaces docstring by string not ending with blank lines @@ -2229,7 +2508,7 @@ Features added * #7690: napoleon: parse type strings and make them hyperlinks as possible. The conversion rule can be updated via :confval:`napoleon_type_aliases` * #8049: napoleon: Create a hyperlink for each the type of parameter when - :confval:`napoleon_use_param` is False + :confval:`napoleon_use_param` is ``False`` * C, added :rst:dir:`c:alias` directive for inserting copies of existing declarations. * #7745: html: inventory is broken if the docname contains a space @@ -2485,7 +2764,7 @@ Bugs fixed * #7676: autodoc: wrong value for :member-order: option is ignored silently * #7676: autodoc: member-order="bysource" does not work for C module * #3673: autodoc: member-order="bysource" does not work for a module having - __all__ + ``__all__`` * #7668: autodoc: wrong retann value is passed to a handler of autodoc-process-signature * #7711: autodoc: fails with ValueError when processing numpy objects @@ -2494,7 +2773,7 @@ Bugs fixed * #7661: autosummary: autosummary directive emits warnings twices if failed to import the target module * #7685: autosummary: The template variable "members" contains imported members - even if :confval:`autossummary_imported_members` is False + even if :confval:`autossummary_imported_members` is ``False`` * #7671: autosummary: The location of import failure warning is missing * #7535: sphinx-autogen: crashes when custom template uses inheritance * #7536: sphinx-autogen: crashes when template uses i18n feature @@ -2507,7 +2786,7 @@ Bugs fixed * #7581: napoleon: bad parsing of inline code in attribute docstrings * #7628: imgconverter: runs imagemagick once unnecessary for builders not supporting images -* #7610: incorrectly renders consecutive backslashes for docutils-0.16 +* #7610: incorrectly renders consecutive backslashes for Docutils 0.16 * #7646: handle errors on event handlers * #4187: LaTeX: EN DASH disappears from PDF bookmarks in Japanese documents * #7701: LaTeX: Anonymous indirect hyperlink target causes duplicated labels @@ -2568,7 +2847,7 @@ Bugs fixed * #7479: autodoc: Sphinx builds has been slower since 3.0.0 on mocking * C++, fix spacing issue in east-const declarations. * #7414: LaTeX: Xindy language options were incorrect -* sphinx crashes with ImportError on python3.5.1 +* Sphinx crashes with ImportError on python3.5.1 Release 3.0.1 (released Apr 11, 2020) ===================================== @@ -2766,7 +3045,7 @@ Bugs fixed 3.0.0 final -* #7364: autosummary: crashed when :confval:`autosummary_generate` is False +* #7364: autosummary: crashed when :confval:`autosummary_generate` is ``False`` * #7370: autosummary: raises UnboundLocalError when unknown module given * #7367: C++, alternate operator spellings are now supported. * C, alternate operator spellings are now supported. @@ -2792,7 +3071,7 @@ Release 2.4.5 (released Nov 18, 2021) Dependencies ------------ -* #9807: Restrict docutils to 0.17.x or older +* #9807: Restrict Docutils to 0.17.x or older Release 2.4.4 (released Mar 05, 2020) ===================================== @@ -3043,7 +3322,7 @@ Bugs fixed * #6890: LaTeX: even with smartquotes off, PDF output transforms straight quotes and consecutive hyphens into curly quotes and dashes * #6876: LaTeX: multi-line display of authors on title page has ragged edges -* #6887: Sphinx crashes with docutils-0.16b0 +* #6887: Sphinx crashes with Docutils 0.16b0 * #6920: sphinx-build: A console message is wrongly highlighted * #6900: sphinx-build: ``-D`` option does not considers ``0`` and ``1`` as a boolean value @@ -3145,7 +3424,7 @@ Bugs fixed * #6545: doctest comments not getting trimmed since Sphinx 1.8.0 * #6561: glossary: Wrong hyperlinks are generated for non alphanumeric terms * #6620: i18n: classifiers of definition list are not translated with - docutils-0.15 + Docutils 0.15 * #6474: ``DocFieldTransformer`` raises AttributeError when given directive is not a subclass of ObjectDescription @@ -3305,7 +3584,7 @@ Bugs fixed * #6331: man: invalid output when doctest follows rubric * #6351: "Hyperlink target is not referenced" message is shown even if referenced -* #6165: autodoc: ``tab_width`` setting of docutils has been ignored +* #6165: autodoc: ``tab_width`` setting of Docutils has been ignored * #6347: autodoc: crashes with a plain Tuple on Python 3.6 and 3.5 * #6311: autosummary: autosummary table gets confused by complex type hints * #6350: autosummary: confused by an argument having some kind of default value @@ -3382,7 +3661,7 @@ Incompatible changes 2.0.0b1 * Drop python 2.7 and 3.4 support -* Drop docutils 0.11 support +* Drop Docutils 0.11 support * Drop features and APIs deprecated in 1.7.x * The default setting for :confval:`master_doc` is changed to ``'index'`` which has been longly used as default of sphinx-quickstart. @@ -3414,7 +3693,7 @@ Incompatible changes * quickstart: Simplify generated ``conf.py`` * #4148: quickstart: some questions are removed. They are still able to specify via command line options -* websupport: unbundled from sphinx core. Please use sphinxcontrib-websupport +* websupport: unbundled from Sphinx core. Please use sphinxcontrib-websupport * C++, the visibility of base classes is now always rendered as present in the input. That is, ``private`` is now shown, where it was ellided before. * LaTeX: graphics inclusion of oversized images rescales to not exceed @@ -3636,7 +3915,7 @@ Release 1.8.6 (released Nov 18, 2021) Dependencies ------------ -* #9807: Restrict docutils to 0.17.x or older +* #9807: Restrict Docutils to 0.17.x or older Release 1.8.5 (released Mar 10, 2019) ===================================== @@ -4157,7 +4436,7 @@ Bugs fixed * #5037: LaTeX ``\sphinxupquote{}`` breaks in Russian * sphinx.testing uses deprecated pytest API; ``Node.get_marker(name)`` * #5016: crashed when recommonmark.AutoStrictify is enabled -* #5022: latex: crashed with docutils package provided by Debian/Ubuntu +* #5022: latex: crashed with Docutils package provided by Debian/Ubuntu * #5009: latex: a label for table is vanished if table does not have a caption * #5048: crashed with numbered toctree * #2410: C, render empty argument lists for macros. @@ -4182,7 +4461,7 @@ Bugs fixed * #5143: autodoc: crashed on inspecting dict like object which does not support sorting * #5139: autodoc: Enum argument missing if it shares value with another -* #4946: py domain: rtype field could not handle "None" as a type +* #4946: py domain: rtype field could not handle "``None``" as a type * #5176: LaTeX: indexing of terms containing ``@``, ``!``, or ``"`` fails * #5161: html: crashes if copying static files are failed * #5167: autodoc: Fix formatting type annotations for tuples with more than two @@ -4213,7 +4492,7 @@ Bugs fixed LaTeX engine crashed * #4978: latex: shorthandoff is not set up for Brazil locale * #4928: i18n: Ignore dot-directories like .git/ in LC_MESSAGES/ -* #4946: py domain: type field could not handle "None" as a type +* #4946: py domain: type field could not handle "``None``" as a type * #4979: latex: Incorrect escaping of curly braces in index entries * #4956: autodoc: Failed to extract document from a subclass of the class on mocked module @@ -4356,7 +4635,7 @@ Incompatible changes * #4274: sphinx-build returns 2 as an exit code on argument error * #4389: output directory will be created after loading extensions * autodoc does not generate warnings messages to the generated document even if - :confval:`keep_warnings` is True. They are only emitted to stderr. + :confval:`keep_warnings` is ``True``. They are only emitted to stderr. * shebang line is removed from generated conf.py * #2557: autodoc: :confval:`autodoc_mock_imports` only mocks specified modules with their descendants. It does not mock their ancestors. If you want to @@ -4516,7 +4795,7 @@ Bugs fixed * #4493: recommonmark raises AttributeError if AutoStructify enabled * #4209: intersphinx: In link title, "v" should be optional if target has no version -* #4230: slowdown in writing pages with sphinx 1.6 +* #4230: slowdown in writing pages with Sphinx 1.6 * #4522: epub: document is not rebuilt even if config changed 1.7.0b3 @@ -4538,7 +4817,7 @@ Testing 1.7.0b1 -* Add support for docutils 0.14 +* Add support for Docutils 0.14 * Add tests for the ``sphinx.ext.inheritance_diagram`` extension. Release 1.6.7 (released Feb 04, 2018) @@ -4619,7 +4898,7 @@ Bugs fixed * #4085: Failed PDF build from image in parsed-literal using ``:align:`` option * #4100: Remove debug print from autodoc extension -* #3987: Changing theme from alabaster causes HTML build to fail +* #3987: Changing theme from ``alabaster`` causes HTML build to fail * #4096: C++, don't crash when using the wrong role type. Thanks to mitya57. * #4070, #4111: crashes when the warning message contains format strings (again) * #4108: Search word highlighting breaks SVG images @@ -4667,7 +4946,7 @@ Bugs fixed * #4067: Return non-zero exit status when make subprocess fails * #4055: graphviz: the :align: option does not work for SVG output * #4055: graphviz: the :align: center option does not work for latex output -* #4051: ``warn()`` function for HTML theme outputs 'None' string +* #4051: ``warn()`` function for HTML theme outputs '``None``' string Release 1.6.3 (released Jul 02, 2017) ===================================== @@ -4680,8 +4959,8 @@ Features added Bugs fixed ---------- -* #3821: Failed to import sphinx.util.compat with docutils-0.14rc1 -* #3829: sphinx-quickstart template is incomplete regarding use of alabaster +* #3821: Failed to import sphinx.util.compat with Docutils 0.14rc1 +* #3829: sphinx-quickstart template is incomplete regarding use of ``alabaster`` * #3772: 'str object' has no attribute 'filename' * Emit wrong warnings if citation label includes hyphens (refs: #3565) * #3858: Some warnings are not colored when using --color option @@ -4689,7 +4968,7 @@ Bugs fixed * #3835: sphinx.ext.imgmath fails to convert SVG images if project directory name contains spaces * #3850: Fix color handling in make mode's help command -* #3865: use of self.env.warn in sphinx extension fails +* #3865: use of self.env.warn in Sphinx extension fails * #3824: production lists apply smart quotes transform since Sphinx 1.6.1 * latex: fix ``\sphinxbfcode`` swallows initial space of argument * #3878: Quotes in auto-documented class attributes should be straight quotes @@ -4872,7 +5151,7 @@ Features added * latex: merged cells in LaTeX tables allow code-blocks, lists, blockquotes... as do normal cells (refs: #3435) * HTML builder uses experimental HTML5 writer if - ``html_experimental_html5_writer`` is True and docutils 0.13 or later is + ``html_experimental_html5_writer`` is ``True`` and Docutils 0.13 or later is installed. * LaTeX macros to customize space before and after tables in PDF output (refs #3504) @@ -4901,8 +5180,8 @@ Features added * ``LATEXMKOPTS`` variable for the Makefile in ``$BUILDDIR/latex`` to pass options to ``latexmk`` when executing ``make latexpdf`` (refs #3695, #3720) -* Add a new event `env-check-consistency` to check consistency to extensions -* Add `Domain.check_consistency()` to check consistency +* Add a new event ``env-check-consistency`` to check consistency to extensions +* Add ``Domain.check_consistency()`` to check consistency Bugs fixed ---------- @@ -4935,7 +5214,7 @@ Bugs fixed 1.6b3 * #3588: No compact (p tag) html output in the i18n document build even when - :confval:`html_compact_lists` is True. + :confval:`html_compact_lists` is ``True``. * The ``make latexpdf`` from 1.6b1 (for GNU/Linux and Mac OS, using ``latexmk``) aborted earlier in case of LaTeX errors than was the case with 1.5 series, due to hard-coded usage of ``--halt-on-error`` option (refs #3695) @@ -5031,7 +5310,7 @@ Bugs fixed * #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. + :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 @@ -5077,7 +5356,7 @@ Bugs fixed 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 +* #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 @@ -5132,7 +5411,7 @@ 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 +* #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. @@ -5145,7 +5424,7 @@ Bugs fixed * #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 +* #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) @@ -5191,9 +5470,9 @@ 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 +* #3211: Remove untranslated Sphinx locale catalogs (it was covered by untranslated it_IT) -* #3212: HTML Builders crashes with docutils-0.13 +* #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) @@ -5213,7 +5492,7 @@ 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` +* 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. @@ -5227,7 +5506,7 @@ Incompatible changes 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 + ``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. @@ -5313,10 +5592,10 @@ Features added * #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) +* 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). + 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 @@ -5345,12 +5624,12 @@ Features added * 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 +* #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 +* #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. @@ -5372,8 +5651,8 @@ Features added * #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 +* #326: ``numref`` role can also refer sections +* #2916: ``numref`` role can also refer caption as an its linktext 1.5a2 @@ -5383,7 +5662,7 @@ Features added * #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. + 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) @@ -5426,8 +5705,8 @@ Bugs fixed * #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`. +* ``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 @@ -5450,7 +5729,7 @@ Bugs fixed * #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 +* #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 @@ -5484,7 +5763,7 @@ Bugs fixed * #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 +* #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 @@ -5501,7 +5780,7 @@ Bugs fixed Testing ------- -* To simplify, sphinx uses external mock package even if unittest.mock exists. +* To simplify, Sphinx uses external mock package even if ``unittest.mock`` exists. Release 1.4.9 (released Nov 23, 2016) @@ -5555,9 +5834,9 @@ Bugs fixed * Could not reference equations if ``:nowrap:`` option specified * #2873: code-block overflow in latex (due to commas) * #1060, #2056: sphinx.ext.intersphinx: broken links are generated if relative - paths are used in `intersphinx_mapping` + paths are used in ``intersphinx_mapping`` * #2931: code-block directive with same :caption: causes warning of duplicate - target. Now `code-block` and `literalinclude` does not define hyperlink + target. Now ``code-block`` and ``literalinclude`` does not define hyperlink target using its caption automatically. * #2962: latex: missing label of longtable * #2968: autodoc: show-inheritance option breaks docstrings @@ -5590,7 +5869,7 @@ Bugs fixed * #2833: Fix formatting instance annotations in ext.autodoc. * #1911: ``-D`` option of ``sphinx-build`` does not override the ``extensions`` variable -* #2789: `sphinx.ext.intersphinx` generates wrong hyperlinks if the inventory is +* #2789: ``sphinx.ext.intersphinx`` generates wrong hyperlinks if the inventory is given * parsing errors for caption of code-blocks are displayed in document (ref: #2845) @@ -5614,8 +5893,9 @@ Incompatible changes Features added -------------- -* new config option :confval:`!latex_keep_old_macro_names`, defaults to True. If False, - lets macros (for text styling) be defined only with ``\sphinx``-prefixed names +* new config option :confval:`!latex_keep_old_macro_names`, defaults to ``True``. + If ``False``, lets macros (for text styling) be defined + only with ``\sphinx``-prefixed names * latex writer allows user customization of "shadowed" boxes (topics), via three length variables. * woff-format web font files now supported by the epub builder. @@ -5627,11 +5907,11 @@ Bugs fixed * #2676: (latex) Error with verbatim text in captions since Sphinx 1.4.4 * #2629: memoir class crashes LaTeX. Fixed by ``latex_keep_old_macro_names=False`` (ref 2675) -* #2684: `sphinx.ext.intersphinx` crashes with six-1.4.1 +* #2684: ``sphinx.ext.intersphinx`` crashes with six-1.4.1 * #2679: ``float`` package needed for ``'figure_align': 'H'`` latex option * #2671: image directive may lead to inconsistent spacing in pdf * #2705: ``toctree`` generates empty bullet_list if ``:titlesonly:`` specified -* #2479: `sphinx.ext.viewcode` uses python2 highlighter by default +* #2479: ``sphinx.ext.viewcode`` uses python2 highlighter by default * #2700: HtmlHelp builder has hard coded index.html * latex, since 1.4.4 inline literal text is followed by spurious space * #2722: C++, fix id generation for var/member declarations to include @@ -5640,13 +5920,13 @@ Bugs fixed indentation (fixed together with #2671) * #2733: since Sphinx 1.4.4 ``make latexpdf`` generates lots of hyperref warnings -* #2731: `sphinx.ext.autodoc` does not access propertymethods which raises any +* #2731: ``sphinx.ext.autodoc`` does not access propertymethods which raises any exceptions * #2666: C++, properly look up nested names involving constructors. * #2579: Could not refer a label including both spaces and colons via - `sphinx.ext.intersphinx` + ``sphinx.ext.intersphinx`` * #2718: Sphinx crashes if the document file is not readable -* #2699: hyperlinks in help HTMLs are broken if `html_file_suffix` is set +* #2699: hyperlinks in help HTMLs are broken if ``html_file_suffix`` is set * #2723: extra spaces in latex pdf output from multirow cell * #2735: latexpdf ``Underfull \hbox (badness 10000)`` warnings from title page * #2667: latex crashes if resized images appeared in section title @@ -5669,7 +5949,7 @@ Bugs fixed * Let LaTeX use straight quotes also in inline code (ref #2627) * #2351: latex crashes if enumerated lists are placed on footnotes * #2646: latex crashes if math contains twice empty lines -* #2480: `sphinx.ext.autodoc`: memory addresses were shown +* #2480: ``sphinx.ext.autodoc``: memory addresses were shown * latex: allow code-blocks appearing inside lists and quotes at maximal nesting depth (ref #777, #2624, #2651) * #2635: Latex code directives produce inconsistent frames based on viewing @@ -5696,7 +5976,7 @@ Bugs fixed * #2614: Some tables in PDF output will end up shifted if user sets non zero \parindent in preamble * #2602: URL redirection breaks the hyperlinks generated by - `sphinx.ext.intersphinx` + ``sphinx.ext.intersphinx`` * #2613: Show warnings if merged extensions are loaded * #2619: make sure amstext LaTeX package always loaded (ref: d657225, 488ee52, 9d82cad and #2615) @@ -5773,20 +6053,20 @@ Bugs fixed * #2521: generated Makefile causes BSD make crashed if sphinx-build not found * #2470: ``typing`` backport package causes autodoc errors with python 2.7 * ``sphinx.ext.intersphinx`` crashes if non-string value is used for key of - `intersphinx_mapping` -* #2518: `intersphinx_mapping` disallows non alphanumeric keys + ``intersphinx_mapping`` +* #2518: ``intersphinx_mapping`` disallows non alphanumeric keys * #2558: unpack error on devhelp builder * #2561: Info builder crashes when a footnote contains a link * #2565: The descriptions of objects generated by ``sphinx.ext.autosummary`` overflow lines at LaTeX writer * Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551) -* #2445: `rst_prolog` and `rst_epilog` affect to non reST sources +* #2445: ``rst_prolog`` and ``rst_epilog`` affect to non reST sources * #2576: ``sphinx.ext.imgmath`` crashes if subprocess raises error * #2577: ``sphinx.ext.imgmath``: Invalid argument are passed to dvisvgm * #2556: Xapian search does not work with Python 3 * #2581: The search doesn't work if language="es" (Spanish) * #2382: Adjust spacing after abbreviations on figure numbers in LaTeX writer -* #2383: The generated footnote by `latex_show_urls` overflows lines +* #2383: The generated footnote by ``latex_show_urls`` overflows lines * #2497, #2552: The label of search button does not fit for the button itself @@ -5796,7 +6076,7 @@ Release 1.4.1 (released Apr 12, 2016) Incompatible changes -------------------- -* The default format of `today_fmt` and `html_last_updated_fmt` is back to +* The default format of ``today_fmt`` and ``html_last_updated_fmt`` is back to strftime format again. Locale Date Markup Language is also supported for backward compatibility until Sphinx 1.5. @@ -5835,13 +6115,13 @@ Incompatible changes -------------------- * Drop ``PorterStemmer`` package support. Use ``PyStemmer`` instead of ``PorterStemmer`` to accelerate stemming. -* sphinx_rtd_theme has become optional. Please install it manually. +* ``sphinx_rtd_theme`` has become optional. Please install it manually. Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich. * #2231: Use DUrole instead of DUspan for custom roles in LaTeX writer. It enables to take title of roles as an argument of custom macros. -* #2022: 'Thumbs.db' and '.DS_Store' are added to `exclude_patterns` default +* #2022: 'Thumbs.db' and '.DS_Store' are added to ``exclude_patterns`` default values in conf.py that will be provided on sphinx-quickstart. -* #2027, #2208: The ``html_title`` accepts string values only. And The None +* #2027, #2208: The ``html_title`` accepts string values only. And the ``None`` value cannot be accepted. * ``sphinx.ext.graphviz``: show graph image in inline by default * #2060, #2224: The ``manpage`` role now generate ``sphinx.addnodes.manpage`` @@ -5862,11 +6142,11 @@ Incompatible changes add ``highlight_language = "python"`` to conf.py. * `Locale Date Markup Language <https://unicode.org/reports/tr35/tr35-dates.html#Date_Format_Patterns>`_ like - ``"MMMM dd, YYYY"`` is default format for `today_fmt` and - `html_last_updated_fmt`. However strftime format like ``"%B %d, %Y"`` is also + ``"MMMM dd, YYYY"`` is default format for ``today_fmt`` and + ``html_last_updated_fmt``. However strftime format like ``"%B %d, %Y"`` is also supported for backward compatibility until Sphinx 1.5. Later format will be disabled from Sphinx 1.5. -* #2327: ``latex_use_parts`` is deprecated now. Use `latex_toplevel_sectioning` +* #2327: ``latex_use_parts`` is deprecated now. Use ``latex_toplevel_sectioning`` instead. * #2337: Use ``\url{URL}`` macro instead of ``\href{URL}{URL}`` in LaTeX writer. * #1498: manpage writer: don't make whole of item in definition list bold if it @@ -5937,14 +6217,14 @@ Features added * #2338: Define ``\titleref`` macro to redefine the style of ``title-reference`` roles. * Define ``\menuselection`` and ``\accelerator`` macros to redefine the style of - `menuselection` roles. + ``menuselection`` roles. * Define ``\crossref`` macro to redefine the style of references * #2301: Texts in the classic html theme should be hyphenated. * #2355: Define ``\termref`` macro to redefine the style of ``term`` roles. * Add :confval:`suppress_warnings` to suppress arbitrary warning message (experimental) * #2229: Fix no warning is given for unknown options -* #2327: Add `latex_toplevel_sectioning` to switch the top level sectioning of +* #2327: Add ``latex_toplevel_sectioning`` to switch the top level sectioning of LaTeX document. Bugs fixed @@ -6054,7 +6334,7 @@ Bugs fixed * #2247: Fix #2205 breaks make html for definition list with classifiers that contains regular-expression like string * #1565: Sphinx will now emit a warning that highlighting was skipped if the - syntax is incorrect for `code-block`, `literalinclude` and so on. + syntax is incorrect for ``code-block``, ``literalinclude`` and so on. * #2211: Fix paragraphs in table cell doesn't work in Latex output * #2253: ``:pyobject:`` option of ``literalinclude`` directive can't detect indented body block when the block starts with blank or comment lines. @@ -6070,7 +6350,7 @@ Bugs fixed * #2134: Fix figure caption with reference causes latex build error * #2094: Fix rubric with reference not working in Latex * #2147: Fix literalinclude code in latex does not break in pages -* #1833: Fix email addresses is showed again if latex_show_urls is not None +* #1833: Fix email addresses is showed again if latex_show_urls is not ``None`` * #2176: sphinx.ext.graphviz: use <object> instead of <img> to embed svg * #967: Fix SVG inheritance diagram is not hyperlinked (clickable) * #1237: Fix footnotes not working in definition list in LaTeX @@ -6088,7 +6368,7 @@ Bugs fixed * #2193: Fix shutil.SameFileError if source directory and destination directory are same * #2178: Fix unparsable C++ cross-reference when referencing a function with - :cpp:any: + ``:cpp:any:`` * #2206: Fix Sphinx latex doc build failed due to a footnotes * #2201: Fix wrong table caption for tables with over 30 rows * #2213: Set <blockquote> in the classic theme to fit with <p> @@ -6101,7 +6381,7 @@ Bugs fixed * #1408: Check latex_logo validity before copying * #771: Fix latex output doesn't set tocdepth * #1820: On Windows, console coloring is broken with colorama version 0.3.3. - Now sphinx use colorama>=0.3.5 to avoid this problem. + Now Sphinx use colorama>=0.3.5 to avoid this problem. * #2072: Fix footnotes in chapter-titles do not appear in PDF output * #1580: Fix paragraphs in longtable don't work in Latex output * #1366: Fix centered image not centered in latex @@ -6117,7 +6397,7 @@ Bugs fixed * #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath, mathjax) * #1601, #2220: 'any' role breaks extended domains behavior. Affected extensions doesn't support resolve_any_xref and resolve_xref returns problematic node - instead of None. sphinxcontrib-httpdomain is one of them. + instead of ``None``. sphinxcontrib-httpdomain is one of them. * #2229: Fix no warning is given for unknown options Release 1.3.3 (released Dec 2, 2015) @@ -6153,9 +6433,9 @@ Bugs fixed * #1790: ``literalinclude`` strips empty lines at the head and tail * #1802: load plugin themes automatically when theme.conf use it as 'inherit'. Thanks to Takayuki Hirai. -* #1794: custom theme extended from alabaster or sphinx_rtd_theme can't find - base theme. -* #1834: compatibility for docutils-0.13: handle_io_errors keyword argument for +* #1794: custom theme extended from ``alabaster`` or ``sphinx_rtd_theme`` + can't find base theme. +* #1834: compatibility for Docutils 0.13: handle_io_errors keyword argument for docutils.io.FileInput cause TypeError. * #1823: '.' as <module_path> for sphinx-apidoc cause an unfriendly error. Now '.' is converted to absolute path automatically. @@ -6192,7 +6472,7 @@ Bugs fixed on LaTeX builder * #1994: More supporting non-standard parser (like recommonmark parser) for Translation and WebSupport feature. Now node.rawsource is fall backed to - node.astext() during docutils transforming. + node.astext() during Docutils transforming. * #1989: "make blahblah" on Windows indicate help messages for sphinx-build every time. It was caused by wrong make.bat that generated by Sphinx 1.3.0/1.3.1. @@ -6201,12 +6481,12 @@ Bugs fixed * #2102: On Windows + Py3, using ``|today|`` and non-ASCII date format will raise UnicodeEncodeError. * #1974: UnboundLocalError: local variable 'domain' referenced before assignment - when using `any` role and `sphinx.ext.intersphinx` in same time. + when using ``any`` role and ``sphinx.ext.intersphinx`` in same time. * #2121: multiple words search doesn't find pages when words across on the page title and the page content. * #1884, #1885: plug-in html themes cannot inherit another plug-in theme. Thanks to Suzumizaki. -* #1818: `sphinx.ext.todo` directive generates broken html class attribute as +* #1818: ``sphinx.ext.todo`` directive generates broken html class attribute as 'admonition-' when :confval:`language` is specified with non-ASCII linguistic area like 'ru' or 'ja'. To fix this, now ``todo`` directive can use ``:class:`` option. @@ -6232,9 +6512,9 @@ Bugs fixed * #1777: Sphinx 1.3 can't load extra theme. Thanks to tell-k. * #1776: ``source_suffix = ['.rst']`` cause unfriendly error on prior version. * #1771: automated .mo building doesn't work properly. -* #1783: Autodoc: Python2 Allow unicode string in __all__. +* #1783: Autodoc: Python2 Allow unicode string in ``__all__``. Thanks to Jens Hedegaard Nielsen. -* #1781: Setting `html_domain_indices` to a list raises a type check warnings. +* #1781: Setting ``html_domain_indices`` to a list raises a type check warnings. Release 1.3 (released Mar 10, 2015) @@ -6253,7 +6533,7 @@ Features added * Add convenience directives and roles to the C++ domain: directive ``cpp:var`` as alias for ``cpp:member``, role ``:cpp:var`` as alias - for ``:cpp:member``, and role `any` for cross-reference to any C++ + for ``:cpp:member``, and role ``any`` for cross-reference to any C++ declaraction. #1577, #1744 * The :confval:`source_suffix` config value can now be a list of multiple suffixes. @@ -6293,22 +6573,22 @@ Release 1.3b3 (released Feb 24, 2015) Incompatible changes -------------------- -* Dependency requirement updates: docutils 0.11, Pygments 2.0 +* Dependency requirement updates: Docutils 0.11, Pygments 2.0 * The ``gettext_enables`` config value has been renamed to - `gettext_additional_targets`. + ``gettext_additional_targets``. * #1735: Use https://docs.python.org/ instead of ``http`` protocol. - It was used for `sphinx.ext.intersphinx` and some documentation. + It was used for ``sphinx.ext.intersphinx`` and some documentation. Features added -------------- * #1346: Add new default theme; - * Add 'alabaster' theme. - * Add 'sphinx_rtd_theme' theme. + * Add '``alabaster``' theme. + * Add '``sphinx_rtd_theme``' theme. * The 'default' html theme has been renamed to 'classic'. 'default' is still available, however it will emit notice a recommendation that using new - 'alabaster' theme. + '``alabaster``' theme. * Added ``highlight_options`` configuration value. * The ``language`` config value is now available in the HTML templates. @@ -6320,17 +6600,17 @@ Features added described in documentation. * HTML breadcrumb items tag has class "nav-item" and "nav-item-N" (like nav-item-0, 1, 2...). -* New option `sphinx-quickstart --use-make-mode` for generating Makefile that +* New option ``sphinx-quickstart --use-make-mode`` for generating Makefile that use sphinx-build make-mode. * #1235: i18n: several node can be translated if it is set to - `gettext_additional_targets` in conf.py. Supported nodes are: + ``gettext_additional_targets`` in conf.py. Supported nodes are: - 'literal-block' - 'doctest-block' - 'raw' - 'image' -* #1227: Add `html_scaled_image_link` config option to conf.py, to control +* #1227: Add ``html_scaled_image_link`` config option to conf.py, to control scaled image link. Bugs fixed @@ -6339,7 +6619,7 @@ Bugs fixed * LaTeX writer now generates correct markup for cells spanning multiple rows. * #1674: Do not crash if a module's ``__all__`` is not a list of strings. * #1629: Use VerbatimBorderColor to add frame to code-block in LaTeX -* On windows, make-mode didn't work on Win32 platform if sphinx was invoked as +* On windows, make-mode didn't work on Win32 platform if Sphinx was invoked as ``python sphinx-build.py``. * #1687: linkcheck now treats 401 Unauthorized responses as "working". * #1690: toctrees with ``glob`` option now can also contain entries for single @@ -6373,7 +6653,7 @@ Features added -------------- * #1597: Added possibility to return a new template name from - `html-page-context`. + ``html-page-context``. * PR#314, #1150: Configuration values are now checked for their type. A warning is raised if the configured and the default value do not have the same type and do not share a common non-trivial base class. @@ -6388,7 +6668,7 @@ Bugs fixed * #1607: Fix a crash when building latexpdf with "howto" class * #1251: Fix again. Sections which depth are lower than :tocdepth: should not be shown on localtoc sidebar. -* make-mode didn't work on Win32 platform if sphinx was installed by wheel +* make-mode didn't work on Win32 platform if Sphinx was installed by wheel package. @@ -6399,7 +6679,7 @@ Incompatible changes -------------------- * Dropped support for Python 2.5, 3.1 and 3.2. -* Dropped support for docutils versions up to 0.9. +* Dropped support for Docutils versions up to 0.9. * Removed the ``sphinx.ext.oldcmarkup`` extension. * The deprecated config values ``exclude_trees``, ``exclude_dirnames`` and ``unused_docs`` have been removed. @@ -6409,13 +6689,13 @@ Incompatible changes * PR#269, #1476: replace ``<tt>`` tag by ``<code>``. User customized stylesheets should be updated If the css contain some styles for ``tt>`` tag. Thanks to Takeshi Komiya. -* #1543: `templates_path` is automatically added to - `exclude_patterns` to avoid reading autosummary rst templates in the +* #1543: ``templates_path`` is automatically added to + ``exclude_patterns`` to avoid reading autosummary rst templates in the templates directory. -* Custom domains should implement the new `Domain.resolve_any_xref` - method to make the `any` role work properly. +* Custom domains should implement the new ``Domain.resolve_any_xref`` + method to make the ``any`` role work properly. * gettext builder: gettext doesn't emit uuid information to generated pot files - by default. Please set ``True`` to `gettext_uuid` to emit uuid information. + by default. Please set ``True`` to ``gettext_uuid`` to emit uuid information. Additionally, if the ``python-levenshtein`` 3rd-party package is installed, it will improve the calculation time. * gettext builder: disable extracting/apply 'index' node by default. Please set @@ -6426,38 +6706,38 @@ Features added -------------- * Add support for Python 3.4. -* Add support for docutils 0.12 +* Add support for Docutils 0.12 * Added ``sphinx.ext.napoleon`` extension for NumPy and Google style docstring support. * Added support for parallel reading (parsing) of source files with the - `sphinx-build -j` option. Third-party extensions will need to be checked for + ``sphinx-build -j`` option. Third-party extensions will need to be checked for compatibility and may need to be adapted if they store information in the - build environment object. See `env-merge-info`. -* Added the `any` role that can be used to find a cross-reference of + build environment object. See ``env-merge-info``. +* Added the ``any`` role that can be used to find a cross-reference of *any* type in *any* domain. Custom domains should implement the new - `Domain.resolve_any_xref` method to make this work properly. + ``Domain.resolve_any_xref`` method to make this work properly. * Exception logs now contain the last 10 messages emitted by Sphinx. * Added support for extension versions (a string returned by ``setup()``, these can be shown in the traceback log files). Version requirements for extensions - can be specified in projects using the new `needs_extensions` config + can be specified in projects using the new ``needs_extensions`` config value. * Changing the default role within a document with the :dudir:`default-role` directive is now supported. * PR#214: Added stemming support for 14 languages, so that the built-in document search can now handle these. Thanks to Shibukawa Yoshiki. * PR#296, PR#303, #76: numfig feature: Assign numbers to figures, tables and - code-blocks. This feature is configured with `numfig`, `numfig_secnum_depth` - and `numfig_format`. Also `numref` role is available. Thanks to Takeshi + code-blocks. This feature is configured with ``numfig``, ``numfig_secnum_depth`` + and ``numfig_format``. Also ``numref`` role is available. Thanks to Takeshi Komiya. * PR#202: Allow "." and "~" prefixed references in ``:param:`` doc fields for Python. -* PR#184: Add `autodoc_mock_imports`, allowing to mock imports of +* PR#184: Add ``autodoc_mock_imports``, allowing to mock imports of external modules that need not be present when autodocumenting. * #925: Allow list-typed config values to be provided on the command line, like ``-D key=val1,val2``. -* #668: Allow line numbering of `code-block` and `literalinclude` directives +* #668: Allow line numbering of ``code-block`` and ``literalinclude`` directives to start at an arbitrary line number, with a new ``lineno-start`` option. -* PR#172, PR#266: The `code-block` and `literalinclude` +* PR#172, PR#266: The ``code-block`` and ``literalinclude`` directives now can have a ``caption`` option that shows a filename before the code in the output. Thanks to Nasimul Haque, Takeshi Komiya. * Prompt for the document language in sphinx-quickstart. @@ -6477,12 +6757,12 @@ Features added and WAKAYAMA shirou. * PR#272: Added 'bizstyle' theme. Thanks to Shoji KUMAGAI. * Automatically compile ``*.mo`` files from ``*.po`` files when - `gettext_auto_build` is True (default) and ``*.po`` is newer than + ``gettext_auto_build`` is ``True`` (default) and ``*.po`` is newer than ``*.mo`` file. -* #623: `sphinx.ext.viewcode` supports imported function/class aliases. -* PR#275: `sphinx.ext.intersphinx` supports multiple target for the +* #623: ``sphinx.ext.viewcode`` supports imported function/class aliases. +* PR#275: ``sphinx.ext.intersphinx`` supports multiple target for the inventory. Thanks to Brigitta Sipocz. -* PR#261: Added the `env-before-read-docs` event that can be connected to modify +* PR#261: Added the ``env-before-read-docs`` event that can be connected to modify the order of documents before they are read by the environment. * #1284: Program options documented with :rst:dir:`option` can now start with ``+``. @@ -6492,7 +6772,7 @@ Features added Thanks to Takeshi Komiya. * #1344: add ``gettext_enables`` to enable extracting 'index' to gettext catalog output / applying translation catalog to generated documentation. -* PR#301, #1583: Allow the line numbering of the directive `literalinclude` to +* PR#301, #1583: Allow the line numbering of the directive ``literalinclude`` to match that of the included file, using a new ``lineno-match`` option. Thanks to Jeppe Pihl. * PR#299: add various options to sphinx-quickstart. Quiet mode option @@ -6509,7 +6789,7 @@ Bugs fixed * #1563: :meth:`~sphinx.application.Sphinx.add_search_language` raises AssertionError for correct type of argument. Thanks to rikoman. * #1174: Fix smart quotes being applied inside roles like :rst:role:`program` or - `makevar`. + ``makevar``. * PR#235: comment db schema of websupport lacked a length of the node_id field. Thanks to solos. * #1466,PR#241: Fix failure of the cpp domain parser to parse C+11 @@ -6545,8 +6825,8 @@ Bugs fixed qualified name. It should be rather easy to change this behaviour and potentially index by namespaces/classes as well. -* PR#258, #939: Add dedent option for `code-block` and - `literalinclude`. Thanks to Zafar Siddiqui. +* PR#258, #939: Add dedent option for ``code-block`` and + ``literalinclude``. Thanks to Zafar Siddiqui. * PR#268: Fix numbering section does not work at singlehtml mode. It still ad-hoc fix because there is a issue that section IDs are conflicted. Thanks to Takeshi Komiya. @@ -6554,10 +6834,10 @@ Bugs fixed Takeshi Komiya. * PR#274: Set its URL as a default title value if URL appears in toctree. Thanks to Takeshi Komiya. -* PR#276, #1381: `rfc` and `pep` roles support custom link +* PR#276, #1381: ``rfc`` and ``pep`` roles support custom link text. Thanks to Takeshi Komiya. * PR#277, #1513: highlights for function pointers in argument list of - `c:function`. Thanks to Takeshi Komiya. + ``c:function``. Thanks to Takeshi Komiya. * PR#278: Fix section entries were shown twice if toctree has been put under only directive. Thanks to Takeshi Komiya. * #1547: pgen2 tokenizer doesn't recognize ``...`` literal (Ellipsis for py3). @@ -6610,7 +6890,7 @@ Bugs fixed a user-friendly error message. * #1502: In autodoc, fix display of parameter defaults containing backslashes. * #1226: autodoc, autosummary: importing setup.py by automodule will invoke - setup process and execute ``sys.exit()``. Now sphinx avoids SystemExit + setup process and execute ``sys.exit()``. Now Sphinx avoids SystemExit exception and emits warnings without unexpected termination. * #1503: py:function directive generate incorrectly signature when specifying a default parameter with an empty list ``[]``. Thanks to Geert Jansen. @@ -6636,7 +6916,7 @@ Release 1.2.2 (released Mar 2, 2014) Bugs fixed ---------- -* PR#211: When checking for existence of the `html_logo` file, check +* PR#211: When checking for existence of the ``html_logo`` file, check the full relative path and not the basename. * PR#212: Fix traceback with autodoc and ``__init__`` methods without docstring. * PR#213: Fix a missing import in the setup command. @@ -6676,7 +6956,7 @@ Bugs fixed This was caused by a change for #1138. * #1340: Can't search alphabetical words on the HTML quick search generated with language='ja'. -* #1319: Do not crash if the `html_logo` file does not exist. +* #1319: Do not crash if the ``html_logo`` file does not exist. * #603: Do not use the HTML-ized title for building the search index (that resulted in "literal" being found on every page with a literal in the title). @@ -6694,7 +6974,7 @@ Bugs fixed * #923: Take the entire LaTeX document into account when caching pngmath-generated images. This rebuilds them correctly when ``pngmath_latex_preamble`` changes. -* #901: Emit a warning when using docutils' new "math" markup without a Sphinx +* #901: Emit a warning when using Docutils' new "math" markup without a Sphinx math extension active. * #845: In code blocks, when the selected lexer fails, display line numbers nevertheless if configured. @@ -6717,7 +6997,7 @@ Bugs fixed running Python version. * #1017: Be helpful and tell the user when the argument to :rst:dir:`option` does not match the required format. -* #1345: Fix two bugs with `nitpick_ignore`; now you don't have to +* #1345: Fix two bugs with ``nitpick_ignore``; now you don't have to remove the store environment for changes to have effect. * #1072: In the JS search, fix issues searching for upper-cased words by lowercasing words before stemming. @@ -6740,8 +7020,8 @@ Bugs fixed * #1300: Fix references not working in translated documents in some instances. * #1283: Fix a bug in the detection of changed files that would try to access doctrees of deleted documents. -* #1330: Fix `exclude_patterns` behavior with subdirectories in the - `html_static_path`. +* #1330: Fix ``exclude_patterns`` behavior with subdirectories in the + ``html_static_path``. * #1323: Fix emitting empty ``<ul>`` tags in the HTML writer, which is not valid HTML. * #1147: Don't emit a sidebar search box in the "singlehtml" builder. @@ -6840,7 +7120,7 @@ Features added * Support docutils.conf 'writers' and 'html4css1 writer' section in the HTML writer. The latex, manpage and texinfo writers also support their respective 'writers' sections. -* The new `html_extra_path` config value allows to specify directories +* The new ``html_extra_path`` config value allows to specify directories with files that should be copied directly to the HTML output directory. * Autodoc directives for module data and attributes now support an ``annotation`` option, so that the default display of the data/attribute @@ -6862,7 +7142,7 @@ Bugs fixed * PR#132: Updated jQuery version to 1.8.3. * PR#141, #982: Avoid crash when writing PNG file using Python 3. Thanks to Marcin Wojdyr. -* PR#145: In parallel builds, sphinx drops second document file to write. +* PR#145: In parallel builds, Sphinx drops second document file to write. Thanks to tychoish. * PR#151: Some styling updates to tables in LaTeX. * PR#153: The "extensions" config value can now be overridden. @@ -6911,10 +7191,10 @@ Incompatible changes * Removed ``sphinx.util.compat.directive_dwim()`` and ``sphinx.roles.xfileref_role()`` which were deprecated since version 1.0. -* PR#122: the files given in `latex_additional_files` now override TeX +* PR#122: the files given in ``latex_additional_files`` now override TeX files included by Sphinx, such as ``sphinx.sty``. -* PR#124: the node generated by `versionadded`, - `versionchanged` and `deprecated` directives now includes +* PR#124: the node generated by ``versionadded``, + ``versionchanged`` and ``deprecated`` directives now includes all added markup (such as "New in version X") as child nodes, and no additional text must be generated by writers. * PR#99: the :rst:dir:`seealso` directive now generates admonition nodes instead @@ -6968,7 +7248,7 @@ Features added asterisks ("*"). - The default value for the ``paragraphindent`` has been changed from 2 to 0 meaning that paragraphs are no longer indented by default. - - #1110: A new configuration value `texinfo_no_detailmenu` has been + - #1110: A new configuration value ``texinfo_no_detailmenu`` has been added for controlling whether a ``@detailmenu`` is added in the "Top" node's menu. - Detailed menus are no longer created except for the "Top" node. @@ -6977,16 +7257,16 @@ Features added * LaTeX builder: - - PR#115: Add ``'transition'`` item in `latex_elements` for + - PR#115: Add ``'transition'`` item in ``latex_elements`` for customizing how transitions are displayed. Thanks to Jeff Klukas. - PR#114: The LaTeX writer now includes the "cmap" package by default. The - ``'cmappkg'`` item in `latex_elements` can be used to control this. + ``'cmappkg'`` item in ``latex_elements`` can be used to control this. Thanks to Dmitry Shachnev. - - The ``'fontpkg'`` item in `latex_elements` now defaults to ``''`` + - The ``'fontpkg'`` item in ``latex_elements`` now defaults to ``''`` when the :confval:`language` uses the Cyrillic script. Suggested by Dmitry Shachnev. - - The `latex_documents`, `texinfo_documents`, and - `man_pages` configuration values will be set to default values based + - The ``latex_documents``, ``texinfo_documents``, and + ``man_pages`` configuration values will be set to default values based on the :confval:`master_doc` if not explicitly set in :file:`conf.py`. Previously, if these values were not set, no output would be generated by their respective builders. @@ -7005,13 +7285,13 @@ Features added :class:`~sphinx.builders.xml.XMLBuilder` and :class:`~sphinx.builders.xml.PseudoXMLBuilder`. - PR#45: The linkcheck builder now checks ``#anchor``\ s for existence. - - PR#123, #1106: Add `epub_use_index` configuration value. If - provided, it will be used instead of `html_use_index` for epub + - PR#123, #1106: Add ``epub_use_index`` configuration value. If + provided, it will be used instead of ``html_use_index`` for epub builder. - - PR#126: Add `epub_tocscope` configuration value. The setting + - PR#126: Add ``epub_tocscope`` configuration value. The setting controls the generation of the epub toc. The user can now also include hidden toc entries. - - PR#112: Add `epub_show_urls` configuration value. + - PR#112: Add ``epub_show_urls`` configuration value. * Extensions: @@ -7078,7 +7358,7 @@ Bugs fixed * #1127: Fix traceback when autodoc tries to tokenize a non-Python file. * #1126: Fix double-hyphen to en-dash conversion in wrong places such as command-line option names in LaTeX. -* #1123: Allow whitespaces in filenames given to `literalinclude`. +* #1123: Allow whitespaces in filenames given to ``literalinclude``. * #1120: Added improvements about i18n for themes "basic", "haiku" and "scrolls" that Sphinx built-in. Thanks to Leonardo J. Caballero G. * #1118: Updated Spanish translation. Thanks to Leonardo J. Caballero G. @@ -7086,7 +7366,7 @@ Bugs fixed * #1112: Avoid duplicate download files when referenced from documents in different ways (absolute/relative). * #1111: Fix failure to find uppercase words in search when - `html_search_language` is 'ja'. Thanks to Tomo Saito. + ``html_search_language`` is 'ja'. Thanks to Tomo Saito. * #1108: The text writer now correctly numbers enumerated lists with non-default start values (based on patch by Ewan Edwards). * #1102: Support multi-context "with" statements in autodoc. @@ -7117,7 +7397,7 @@ Bugs fixed * #1008: Fix test failures with Python 3.3. * #995: Fix table-of-contents and page numbering for the LaTeX "howto" class. * #976: Fix gettext does not extract index entries. -* PR#72: #975: Fix gettext not extracting definition terms before docutils 0.10. +* PR#72: #975: Fix gettext not extracting definition terms before Docutils 0.10. * #961: Fix LaTeX output for triple quotes in code snippets. * #958: Do not preserve ``environment.pickle`` after a failed build. * #955: Fix i18n transformation. @@ -7158,7 +7438,7 @@ Release 1.1.3 (Mar 10, 2012) * #851: Recognize and warn about circular toctrees, instead of running into recursion errors. -* #853: Restore compatibility with docutils trunk. +* #853: Restore compatibility with Docutils trunk. * #852: Fix HtmlHelp index entry links again. @@ -7215,7 +7495,7 @@ Release 1.1 (Oct 9, 2011) Incompatible changes -------------------- -* The `py:module` directive doesn't output its ``platform`` option +* The ``py:module`` directive doesn't output its ``platform`` option value anymore. (It was the only thing that the directive did output, and therefore quite inconsistent.) @@ -7251,7 +7531,7 @@ Features added :rst:dir:`toctree`\'s ``numbered`` option. - #586: Implemented improved :rst:dir:`glossary` markup which allows multiple terms per definition. - - #478: Added `py:decorator` directive to describe decorators. + - #478: Added ``py:decorator`` directive to describe decorators. - C++ domain now supports array definitions. - C++ domain now supports doc fields (``:param x:`` inside directives). - Section headings in :rst:dir:`only` directives are now correctly @@ -7307,8 +7587,8 @@ Features added - Added ``inline`` option to graphviz directives, and fixed the default (block-style) in LaTeX output. - #590: Added ``caption`` option to graphviz directives. - - #553: Added `testcleanup` blocks in the doctest extension. - - #594: `trim_doctest_flags` now also removes ``<BLANKLINE>`` + - #553: Added ``testcleanup`` blocks in the doctest extension. + - #594: ``trim_doctest_flags`` now also removes ``<BLANKLINE>`` indicators. - #367: Added automatic exclusion of hidden members in inheritance diagrams, and an option to selectively enable it. @@ -7385,7 +7665,7 @@ Release 1.0.8 (Sep 23, 2011) * #669: Respect the ``noindex`` flag option in py:module directives. * #675: Fix IndexErrors when including nonexisting lines with - `literalinclude`. + ``literalinclude``. * #676: Respect custom function/method parameter separator strings. @@ -7468,7 +7748,7 @@ Release 1.0.6 (Jan 04, 2011) * #570: Try decoding ``-D`` and ``-A`` command-line arguments with the locale's preferred encoding. -* #528: Observe `locale_dirs` when looking for the JS +* #528: Observe ``locale_dirs`` when looking for the JS translations file. * #574: Add special code for better support of Japanese documents @@ -7491,7 +7771,7 @@ Release 1.0.6 (Jan 04, 2011) * Fix strange reports of line numbers for warnings generated from autodoc-included docstrings, due to different behavior depending - on docutils version. + on Docutils version. * Several fixes to the C++ domain. @@ -7499,7 +7779,7 @@ Release 1.0.6 (Jan 04, 2011) Release 1.0.5 (Nov 12, 2010) ============================ -* #557: Add CSS styles required by docutils 0.7 for aligned images +* #557: Add CSS styles required by Docutils 0.7 for aligned images and figures. * In the Makefile generated by LaTeX output, do not delete pdf files @@ -7526,7 +7806,7 @@ Release 1.0.3 (Aug 23, 2010) ============================ * #495: Fix internal vs. external link distinction for links coming - from a docutils table-of-contents. + from a Docutils table-of-contents. * #494: Fix the ``maxdepth`` option for the ``toctree()`` template callable when used with ``collapse=True``. @@ -7626,7 +7906,7 @@ Incompatible changes * Removed support for old dependency versions; requirements are now: - - docutils >= 0.5 + - Docutils >= 0.5 - Jinja2 >= 2.2 * Removed deprecated elements: @@ -7646,17 +7926,17 @@ Features added * Markup: - - The `menuselection` and `guilabel` roles now + - The ``menuselection`` and ``guilabel`` roles now support ampersand accelerators. - New more compact doc field syntax is now recognized: ``:param type name: description``. - - Added ``tab-width`` option to `literalinclude` directive. + - Added ``tab-width`` option to ``literalinclude`` directive. - Added ``titlesonly`` option to :rst:dir:`toctree` directive. - Added the ``prepend`` and ``append`` options to the - `literalinclude` directive. + ``literalinclude`` directive. - #284: All docinfo metadata is now put into the document metadata, not just the author. - - The `ref` role can now also reference tables by caption. + - The ``ref`` role can now also reference tables by caption. - The :dudir:`include` directive now supports absolute paths, which are interpreted as relative to the source directory. - In the Python domain, references like ``:func:`.name``` now look for @@ -7664,28 +7944,28 @@ Features added * Configuration: - - Added `rst_prolog` config value. - - Added `html_secnumber_suffix` config value to control + - Added ``rst_prolog`` config value. + - Added ``html_secnumber_suffix`` config value to control section numbering format. - - Added `html_compact_lists` config value to control - docutils' compact lists feature. - - The `html_sidebars` config value can now contain patterns + - Added ``html_compact_lists`` config value to control + Docutils' compact lists feature. + - The ``html_sidebars`` config value can now contain patterns as keys, and the values can be lists that explicitly select which sidebar templates should be rendered. That means that the builtin sidebar contents can be included only selectively. - - `html_static_path` can now contain single file entries. - - The new universal config value `exclude_patterns` makes the + - ``html_static_path`` can now contain single file entries. + - The new universal config value ``exclude_patterns`` makes the old ``unused_docs``, ``exclude_trees`` and ``exclude_dirnames`` obsolete. - - Added `html_output_encoding` config value. - - Added the `latex_docclass` config value and made the + - Added ``html_output_encoding`` config value. + - Added the ``latex_docclass`` config value and made the "twoside" documentclass option overridable by "oneside". - - Added the `trim_doctest_flags` config value, which is true + - Added the ``trim_doctest_flags`` config value, which is true by default. - - Added `html_show_copyright` config value. - - Added `latex_show_pagerefs` and `latex_show_urls` + - Added ``html_show_copyright`` config value. + - Added ``latex_show_pagerefs``` and ``latex_show_urls`` config values. - - The behavior of `html_file_suffix` changed slightly: the + - The behavior of ``html_file_suffix``` changed slightly: the empty string now means "no suffix" instead of "default suffix", use ``None`` for "default suffix". @@ -7727,7 +8007,7 @@ Features added * Extension API: - Added :event:`html-collect-pages`. - - Added `needs_sphinx` config value and + - Added ``needs_sphinx`` config value and :meth:`~sphinx.application.Sphinx.require_sphinx` application API method. - #200: Added :meth:`!add_stylesheet` @@ -7739,7 +8019,7 @@ Features added - Added the :mod:`~sphinx.ext.extlinks` extension. - Added support for source ordering of members in autodoc, with ``autodoc_member_order = 'bysource'``. - - Added `autodoc_default_flags` config value, which can be + - Added ``autodoc_default_flags`` config value, which can be used to select default flags for all autodoc directives. - Added a way for intersphinx to refer to named labels in other projects, and to specify the project you want to link to. @@ -7749,7 +8029,7 @@ Features added extension, thanks to Pauli Virtanen. - #309: The :mod:`~sphinx.ext.graphviz` extension can now output SVG instead of PNG images, controlled by the - `graphviz_output_format` config value. + ``graphviz_output_format`` config value. - Added ``alt`` option to :rst:dir:`graphviz` extension directives. - Added ``exclude`` argument to :func:`.autodoc.between`. @@ -7779,7 +8059,7 @@ Release 0.6.7 (Jun 05, 2010) * Fix a bug that prevented some references being generated in the LaTeX builder. -* #428: Add some missing CSS styles for standard docutils classes. +* #428: Add some missing CSS styles for standard Docutils classes. * #432: Fix UnicodeErrors while building LaTeX in translated locale. @@ -7959,7 +8239,7 @@ Release 0.6.3 (Sep 03, 2009) * #213: Fix centering of images in LaTeX output. -* #211: Fix compatibility with docutils 0.5. +* #211: Fix compatibility with Docutils 0.5. Release 0.6.2 (Jun 16, 2009) @@ -7988,7 +8268,7 @@ Release 0.6.2 (Jun 16, 2009) * #178: apply ``add_function_parentheses`` config value to C functions as promised. -* #173: Respect the docutils ``title`` directive. +* #173: Respect the Docutils ``title`` directive. * #172: The ``obj`` role now links to modules as promised. @@ -8124,7 +8404,7 @@ New features added - Added a ``toctree`` callable to the templates, and the ability to include external links in toctrees. The 'collapse' keyword argument indicates whether or not to only display subitems of - the current page. (Defaults to True.) + the current page. (Defaults to ``True``.) * Configuration: @@ -8146,7 +8426,7 @@ New features added ignore certain package names for module index sorting. - The new ``trim_footnote_reference_space`` config value mirrors - the docutils config value of the same name and removes the + the Docutils config value of the same name and removes the space before a footnote reference that is necessary for reST to recognize the reference. @@ -8212,15 +8492,15 @@ New features added option per directive. - The function ``Sphinx.add_directive()`` now also supports - docutils 0.5-style directive classes. If they inherit from + Docutils 0.5-style directive classes. If they inherit from ``sphinx.util.compat.Directive``, they also work with - docutils 0.4. + Docutils 0.4. - There is now a ``Sphinx.add_lexer()`` method to be able to use custom Pygments lexers easily. - There is now ``Sphinx.add_generic_role()`` to mirror the - docutils' own function. + Docutils' own function. * Other changes: @@ -8349,7 +8629,7 @@ New features added - "System Message" warnings are now automatically removed from the built documentation, and only written to stderr. If you want the - old behavior, set the new config value ``keep_warnings`` to True. + old behavior, set the new config value ``keep_warnings`` to ``True``. - Glossary entries are now automatically added to the index. @@ -8384,7 +8664,7 @@ New features added - Highlighted code blocks now have CSS classes that make it possible to style them depending on their language. - - HTML ``<meta>`` tags via the docutils :dudir:`meta` directive are now + - HTML ``<meta>`` tags via the Docutils :dudir:`meta` directive are now supported. - ``SerializingHTMLBuilder`` was added as new abstract builder that @@ -8456,7 +8736,7 @@ New features added - sphinx.ext.autodoc has a new event ``autodoc-skip-member`` that allows tuning which members are included in the generated content. - - Respect __all__ when autodocumenting module members. + - Respect ``__all__`` when autodocumenting module members. - The ``automodule`` directive now supports the ``synopsis``, ``deprecated`` and ``platform`` options. @@ -8544,7 +8824,7 @@ Release 0.4.3 (Oct 8, 2008) "module", once as "module.". * Fix a bug in the HTML writer that created duplicate ``id`` - attributes for section titles with docutils 0.5. + attributes for section titles with Docutils 0.5. * Properly call ``super()`` in overridden blocks in templates. @@ -8606,7 +8886,7 @@ Release 0.4.1 (Jul 5, 2008) * Fix linkcheck builder crash for malformed URLs. -* Add compatibility for admonitions and docutils 0.5. +* Add compatibility for admonitions and Docutils 0.5. * Remove the silly restriction on "rubric" in the LaTeX writer: you can now write arbitrary "rubric" directives, and only those with @@ -8855,8 +9135,8 @@ New features added - Support a new method, ``add_crossref_type``. It works like ``add_description_unit`` but the directive will only create a target and no output. - - Support a new method, ``add_transform``. It takes a standard docutils - ``Transform`` subclass which is then applied by Sphinx' reader on + - Support a new method, ``add_transform``. It takes a standard Docutils + ``Transform`` subclass which is then applied by Sphinx's reader on parsing reST document trees. - Add support for other template engines than Jinja, by adding an abstraction called a "template bridge". This class handles rendering @@ -8882,7 +9162,7 @@ New features added - All references to "documentation" in the templates have been removed, so that it is now easier to use Sphinx for non-documentation documents with the default templates. - - Templates now have an XHTML doctype, to be consistent with docutils' + - Templates now have an XHTML doctype, to be consistent with Docutils' HTML output. - You can now create an OpenSearch description file with the ``html_use_opensearch`` config value. @@ -8962,7 +9242,7 @@ Release 0.1.61945 (Mar 26, 2008) latex Makefile. Really pass the correct paper and size options to the LaTeX document class. -* setup: On Python 2.4, don't egg-depend on docutils if a docutils is +* setup: On Python 2.4, don't egg-depend on Docutils if a Docutils is already installed -- else it will be overwritten. @@ -8993,7 +9273,7 @@ Release 0.1.61843 (Mar 24, 2008) Release 0.1.61798 (Mar 23, 2008) ================================ -* sphinx: Work with docutils SVN snapshots as well as 0.4. +* sphinx: Work with Docutils SVN snapshots as well as 0.4. * sphinx.ext.doctest: Make the group in which doctest blocks are placed selectable, and default to ``'default'``. |