From 7e27e09493096a20c30702b410a24ab330ecea10 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Tue, 6 Feb 2018 11:25:43 +0000 Subject: [PATCH 01/35] doc: Rework "builders" document There are a number of cleanup items. - Some paragraphs are reworded or clarified - Semantic markup is added where possible - Everything is wrapped to ~80 characters A number of TODOs are inserted. These will be resolved separately. Signed-off-by: Stephen Finucane --- doc/builders.rst | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/doc/builders.rst b/doc/builders.rst index d968f209f..ee0aa0a33 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -1,7 +1,8 @@ .. _builders: -Available builders -================== +======== +Builders +======== .. module:: sphinx.builders :synopsis: Available built-in builder classes. @@ -75,8 +76,8 @@ The builder's "name" must be given to the **-b** command-line option of .. class:: QtHelpBuilder This builder produces the same output as the standalone HTML builder, but - also generates `Qt help`_ collection support files that allow - the Qt collection generator to compile them. + also generates `Qt help`_ collection support files that allow the Qt + collection generator to compile them. .. autoattribute:: name @@ -144,7 +145,8 @@ The builder's "name" must be given to the **-b** command-line option of .. versionchanged:: 1.5 - Since Sphinx-1.5, the epub3 builder is used for the default builder of epub. + Since Sphinx-1.5, the epub3 builder is used for the default builder of + epub. .. module:: sphinx.builders.latex .. class:: LaTeXBuilder @@ -159,12 +161,12 @@ The builder's "name" must be given to the **-b** command-line option of in a "minimal" TeX distribution installation. For example, on Ubuntu, the following packages need to be installed for successful PDF builds: - * texlive-latex-recommended - * texlive-fonts-recommended - * texlive-latex-extra - * latexmk (for ``make latexpdf`` on GNU/Linux and MacOS X) - * latex-xcolor (old Ubuntu) - * texlive-luatex, texlive-xetex (see :confval:`latex_engine`) + * ``texlive-latex-recommended`` + * ``texlive-fonts-recommended`` + * ``texlive-latex-extra`` + * ``latexmk`` (for ``make latexpdf`` on GNU/Linux and MacOS X) + * ``latex-xcolor`` (old Ubuntu) + * ``texlive-luatex``, ``texlive-xetex`` (see :confval:`latex_engine`) The testing of Sphinx LaTeX is done on Ubuntu trusty with the above mentioned packages, which are from a TeXLive 2013 snapshot dated @@ -178,7 +180,7 @@ The builder's "name" must be given to the **-b** command-line option of Since 1.6, ``make latexpdf`` uses ``latexmk`` (not on Windows). This makes sure the needed number of runs is automatically executed to get the cross-references, bookmarks, indices, and tables of contents right. - + One can pass to ``latexmk`` options via the ``LATEXMKOPTS`` Makefile variable. For example: @@ -311,7 +313,6 @@ name is ``rinoh``. Refer to the `rinohtype manual`_ for details. The filename for the search index Sphinx generates. - See :ref:`serialization-details` for details about the output format. .. versionadded:: 0.5 From b595c4a45b3b19641dc4fbbb0ffa5f352ccdcf3d Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Fri, 3 Nov 2017 20:52:13 +0000 Subject: [PATCH 02/35] doc: Add "builders" to usage guide This is placed in a directory as this document will eventually be split up. However, this is not the day to do this. Signed-off-by: Stephen Finucane --- doc/contents.rst | 2 +- doc/glossary.rst | 3 ++- doc/man/sphinx-build.rst | 6 +++--- doc/{builders.rst => usage/builders/index.rst} | 0 doc/usage/restructuredtext/basics.rst | 2 +- 5 files changed, 7 insertions(+), 6 deletions(-) rename doc/{builders.rst => usage/builders/index.rst} (100%) diff --git a/doc/contents.rst b/doc/contents.rst index 77dcf6c42..2da3cb979 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -12,10 +12,10 @@ Sphinx documentation contents usage/restructuredtext/index usage/markdown usage/configuration + usage/builders/index intro man/index - builders intl theming setuptools diff --git a/doc/glossary.rst b/doc/glossary.rst index 167edb8d4..c74409453 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -12,7 +12,8 @@ Glossary use the builder builders that e.g. check for broken links in the documentation, or build coverage information. - See :ref:`builders` for an overview over Sphinx's built-in builders. + See :doc:`/usage/builders/index` for an overview over Sphinx's built-in + builders. configuration directory The directory containing :file:`conf.py`. By default, this is the same as diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst index fdd0d36c2..72235efad 100644 --- a/doc/man/sphinx-build.rst +++ b/doc/man/sphinx-build.rst @@ -86,8 +86,8 @@ Options Build compact pretty-printed "pseudo-XML" files displaying the internal structure of the intermediate document trees. - See :ref:`builders` for a list of all builders shipped with Sphinx. - Extensions can add their own builders. + See :doc:`/usage/builders/index` for a list of all builders shipped with + Sphinx. Extensions can add their own builders. .. _make_mode: @@ -96,7 +96,7 @@ Options Alternative to :option:`-b`. Uses the Sphinx :program:`make_mode` module, which provides the same build functionality as a default :ref:`Makefile or Make.bat `. In addition to all Sphinx - :ref:`builders `, the following build pipelines are available: + :doc:`/usage/builders/index`, the following build pipelines are available: **latexpdf** Build LaTeX files and run them through :program:`pdflatex`, or as per diff --git a/doc/builders.rst b/doc/usage/builders/index.rst similarity index 100% rename from doc/builders.rst rename to doc/usage/builders/index.rst diff --git a/doc/usage/restructuredtext/basics.rst b/doc/usage/restructuredtext/basics.rst index 3e1253544..1f36cdc40 100644 --- a/doc/usage/restructuredtext/basics.rst +++ b/doc/usage/restructuredtext/basics.rst @@ -444,7 +444,7 @@ candidates. For instance, if the file name ``gnu.*`` was given and two files :file:`gnu.pdf` and :file:`gnu.png` existed in the source tree, the LaTeX builder would choose the former, while the HTML builder would prefer the latter. Supported image types and choosing priority are defined at -:ref:`builders`. +:doc:`/usage/builders/index`. Note that image file names should not contain spaces. From 0b81af6a2eee5533e5c6c95097f2cca257f805e3 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Fri, 8 Jun 2018 17:27:13 +0100 Subject: [PATCH 03/35] doc: Rework "extensions" documents This is mostly spacing and other "niceness" fixes. Signed-off-by: Stephen Finucane --- doc/ext/autodoc.rst | 1 + doc/ext/autosectionlabel.rst | 1 + doc/ext/autosummary.rst | 2 -- doc/ext/coverage.rst | 2 -- doc/ext/doctest.rst | 1 - doc/ext/extlinks.rst | 1 - doc/ext/githubpages.rst | 2 -- doc/ext/graphviz.rst | 1 - doc/ext/imgconverter.rst | 22 ++++++++++++---------- doc/ext/inheritance.rst | 4 +++- doc/ext/intersphinx.rst | 13 ++++++++----- doc/ext/linkcode.rst | 4 ++++ doc/ext/napoleon.rst | 26 ++++++++++++-------------- doc/ext/todo.rst | 5 ++++- doc/ext/viewcode.rst | 14 +++++++------- 15 files changed, 52 insertions(+), 47 deletions(-) diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 9064fe1b3..385254734 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -405,6 +405,7 @@ There are also new config values that you can set: .. versionadded:: 1.7 + Docstring preprocessing ----------------------- diff --git a/doc/ext/autosectionlabel.rst b/doc/ext/autosectionlabel.rst index f4a6322c3..20b15ca20 100644 --- a/doc/ext/autosectionlabel.rst +++ b/doc/ext/autosectionlabel.rst @@ -27,6 +27,7 @@ default. The ``autosectionlabel_prefix_document`` configuration variable can be used to make headings which appear multiple times but in different documents unique. + Configuration ------------- diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst index 46d8e4b56..008bc5613 100644 --- a/doc/ext/autosummary.rst +++ b/doc/ext/autosummary.rst @@ -25,7 +25,6 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: These files by default contain only the corresponding :mod:`sphinx.ext.autodoc` directive, but can be customized with templates. - .. rst:directive:: autosummary Insert a table that contains links to documented items, and a short summary @@ -59,7 +58,6 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: :event:`autodoc-process-docstring` and :event:`autodoc-process-signature` hooks as :mod:`~sphinx.ext.autodoc`. - **Options** * If you want the :rst:dir:`autosummary` table to also serve as a diff --git a/doc/ext/coverage.rst b/doc/ext/coverage.rst index 839478fe1..94d4c6fe4 100644 --- a/doc/ext/coverage.rst +++ b/doc/ext/coverage.rst @@ -4,7 +4,6 @@ .. module:: sphinx.ext.coverage :synopsis: Check Python modules and C API for coverage in the documentation. - This extension features one additional builder, the :class:`CoverageBuilder`. .. class:: CoverageBuilder @@ -14,7 +13,6 @@ This extension features one additional builder, the :class:`CoverageBuilder`. .. todo:: Write this section. - Several new configuration values can be used to specify what the builder should check: diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst index 62221bf04..341b7a9a7 100644 --- a/doc/ext/doctest.rst +++ b/doc/ext/doctest.rst @@ -165,7 +165,6 @@ a comma-separated list of group names. Output text. - The following is an example for the usage of the directives. The test via :rst:dir:`doctest` and the test via :rst:dir:`testcode` and :rst:dir:`testoutput` are equivalent. :: diff --git a/doc/ext/extlinks.rst b/doc/ext/extlinks.rst index b809a740b..d818ba09b 100644 --- a/doc/ext/extlinks.rst +++ b/doc/ext/extlinks.rst @@ -7,7 +7,6 @@ .. versionadded:: 1.0 - This extension is meant to help with the common pattern of having many external links that point to URLs on one and the same site, e.g. links to bug trackers, version control web interfaces, or simply subpages in other websites. It does diff --git a/doc/ext/githubpages.rst b/doc/ext/githubpages.rst index 0cd76a2c9..f19666ef1 100644 --- a/doc/ext/githubpages.rst +++ b/doc/ext/githubpages.rst @@ -1,5 +1,3 @@ -.. highlight:: rest - :mod:`sphinx.ext.githubpages` -- Publish HTML docs in GitHub Pages ================================================================== diff --git a/doc/ext/graphviz.rst b/doc/ext/graphviz.rst index 8b9fff90b..f87f1a4b7 100644 --- a/doc/ext/graphviz.rst +++ b/doc/ext/graphviz.rst @@ -13,7 +13,6 @@ your documents. It adds these directives: - .. rst:directive:: graphviz Directive to embed graphviz code. The input code for ``dot`` is given as the diff --git a/doc/ext/imgconverter.rst b/doc/ext/imgconverter.rst index 322a9b5f3..5799fc3b3 100644 --- a/doc/ext/imgconverter.rst +++ b/doc/ext/imgconverter.rst @@ -1,28 +1,30 @@ -.. highlight:: rest - .. _sphinx.ext.imgconverter: -:mod:`sphinx.ext.imgconverter` -- A reference implementation for image converter using Imagemagick -================================================================================================== +:mod:`sphinx.ext.imgconverter` -- A reference image converter using Imagemagick +=============================================================================== .. module:: sphinx.ext.imgconverter :synopsis: Convert images to appropriate format for builders .. versionadded:: 1.6 -This extension converts images in your document to appropriate format for builders. -For example, it allows you to use SVG images with LaTeX builder. +This extension converts images in your document to appropriate format for +builders. For example, it allows you to use SVG images with LaTeX builder. As a result, you don't mind what image format the builder supports. Internally, this extension uses Imagemagick_ to convert images. .. _Imagemagick: https://www.imagemagick.org/script/index.php -.. note:: Imagemagick rasterizes a SVG image on conversion. As a result, the image - becomes not scalable. To avoid that, please use other image converters - like sphinxcontrib-svg2pdfconverter_ (which uses Inkscape or rsvg-convert). +.. note:: + + Imagemagick rasterizes a SVG image on conversion. As a result, the image + becomes not scalable. To avoid that, please use other image converters like + `sphinxcontrib-svg2pdfconverter`__ (which uses Inkscape or + ``rsvg-convert``). + +.. __: https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter -.. _sphinxcontrib-svg2pdfconverter: https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter Configuration ------------- diff --git a/doc/ext/inheritance.rst b/doc/ext/inheritance.rst index 0062a8afa..ef78d04fe 100644 --- a/doc/ext/inheritance.rst +++ b/doc/ext/inheritance.rst @@ -91,7 +91,9 @@ It adds this directive: .. versionchanged:: 1.7 Added ``top-classes`` option to limit the scope of inheritance graphs. -New config values are: + +Configuration +------------- .. confval:: inheritance_graph_attrs diff --git a/doc/ext/intersphinx.rst b/doc/ext/intersphinx.rst index b8ae104b3..cfda53e8f 100644 --- a/doc/ext/intersphinx.rst +++ b/doc/ext/intersphinx.rst @@ -38,8 +38,9 @@ Behind the scenes, this works as follows: specified individually, e.g. if the docs should be buildable without Internet access. -Configuring Intersphinx ------------------------ + +Configuration +------------- To use Intersphinx linking, add ``'sphinx.ext.intersphinx'`` to your :confval:`extensions` config value, and use these new config values to activate @@ -136,12 +137,14 @@ linking: exception is raised if the server has not issued a response for timeout seconds. + Showing all links of an Intersphinx mapping file ------------------------------------------------ -To show all Intersphinx links and their targets of an Intersphinx mapping file, run -``python -msphinx.ext.intersphinx url-or-path``. This is helpful when searching for the root cause of a broken -Intersphinx link in a documentation project. The following example prints the Intersphinx mapping of the Python 3 +To show all Intersphinx links and their targets of an Intersphinx mapping file, +run ``python -msphinx.ext.intersphinx url-or-path``. This is helpful when +searching for the root cause of a broken Intersphinx link in a documentation +project. The following example prints the Intersphinx mapping of the Python 3 documentation:: $ python -msphinx.ext.intersphinx https://docs.python.org/3/objects.inv diff --git a/doc/ext/linkcode.rst b/doc/ext/linkcode.rst index f00345fca..e65a0b780 100644 --- a/doc/ext/linkcode.rst +++ b/doc/ext/linkcode.rst @@ -16,6 +16,10 @@ found somewhere on the Internet. In your configuration, you need to specify a :confval:`linkcode_resolve` function that returns an URL based on the object. + +Configuration +------------- + .. confval:: linkcode_resolve This is a function ``linkcode_resolve(domain, info)``, diff --git a/doc/ext/napoleon.rst b/doc/ext/napoleon.rst index 6c5f0d61a..b6c8d681b 100644 --- a/doc/ext/napoleon.rst +++ b/doc/ext/napoleon.rst @@ -1,5 +1,5 @@ :mod:`sphinx.ext.napoleon` -- Support for NumPy and Google style docstrings -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=========================================================================== .. module:: sphinx.ext.napoleon :synopsis: Support for NumPy and Google style docstrings @@ -8,8 +8,8 @@ .. versionadded:: 1.3 -Napoleon - *Marching toward legible docstrings* -=============================================== +Overview +-------- .. highlight:: text @@ -25,7 +25,7 @@ Are you tired of writing docstrings that look like this:: :returns: A buffered writable file descriptor :rtype: BufferedFileStorage -`ReStructuredText`_ is great, but it creates visually dense, hard to read +`reStructuredText`_ is great, but it creates visually dense, hard to read `docstrings`_. Compare the jumble above to the same thing rewritten according to the `Google Python Style Guide`_:: @@ -40,8 +40,8 @@ according to the `Google Python Style Guide`_:: Much more legible, no? -Napoleon is a :doc:`../extensions` that enables Sphinx to parse both `NumPy`_ -and `Google`_ style docstrings - the style recommended by `Khan Academy`_. +Napoleon is a :term:`extension` that enables Sphinx to parse both `NumPy`_ and +`Google`_ style docstrings - the style recommended by `Khan Academy`_. Napoleon is a pre-processor that parses `NumPy`_ and `Google`_ style docstrings and converts them to reStructuredText before Sphinx attempts to @@ -61,7 +61,7 @@ source code files. https://github.com/Khan/style-guides/blob/master/style/python.md#docstrings Getting Started ---------------- +~~~~~~~~~~~~~~~ 1. After :doc:`setting up Sphinx ` to build your docs, enable napoleon in the Sphinx `conf.py` file:: @@ -77,7 +77,7 @@ Getting Started Docstrings ----------- +~~~~~~~~~~ Napoleon interprets every docstring that :mod:`autodoc ` can find, including docstrings on: ``modules``, ``classes``, ``attributes``, @@ -91,7 +91,7 @@ All standard reStructuredText formatting still works as expected. .. _Sections: Docstring Sections ------------------- +~~~~~~~~~~~~~~~~~~ All of the following section headers are supported: @@ -120,7 +120,7 @@ All of the following section headers are supported: * ``Yields`` Google vs NumPy ---------------- +~~~~~~~~~~~~~~~ Napoleon supports two styles of docstrings: `Google`_ and `NumPy`_. The main difference between the two styles is that Google uses indention to @@ -188,7 +188,7 @@ not be mixed. Choose one style for your project and be consistent with it. Type Annotations ----------------- +~~~~~~~~~~~~~~~~ `PEP 484`_ introduced a standard way to express types in Python code. This is an alternative to expressing types directly in docstrings. @@ -242,7 +242,7 @@ Google style with types in docstrings:: Configuration -============= +------------- Listed below are all the settings used by napoleon and their default values. These settings can be changed in the Sphinx `conf.py` file. Make @@ -271,8 +271,6 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`:: .. _NumPy style: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt - - .. confval:: napoleon_google_docstring True to parse `Google style`_ docstrings. False to disable support diff --git a/doc/ext/todo.rst b/doc/ext/todo.rst index 09abfa9b8..982005bd6 100644 --- a/doc/ext/todo.rst +++ b/doc/ext/todo.rst @@ -27,7 +27,10 @@ There are two additional directives when using this extension: documentation, if :confval:`todo_include_todos` is ``True``. -There is also an additional config value: +These can be configured as seen below. + +Configuration +------------- .. confval:: todo_include_todos diff --git a/doc/ext/viewcode.rst b/doc/ext/viewcode.rst index 87071144f..ea7d5d335 100644 --- a/doc/ext/viewcode.rst +++ b/doc/ext/viewcode.rst @@ -7,9 +7,8 @@ .. versionadded:: 1.0 - -This extension looks at your Python object descriptions (``.. class::``, -``.. function::`` etc.) and tries to find the source files where the objects are +This extension looks at your Python object descriptions (``.. class::``, ``.. +function::`` etc.) and tries to find the source files where the objects are contained. When found, a separate HTML page will be output for each module with a highlighted version of the source code, and a link will be added to all object descriptions that leads to the source code of the described object. A link back @@ -33,14 +32,15 @@ This extension works only on HTML related builders like ``html``, ``singlehtml``. By default ``epub`` builder doesn't support this extension (see :confval:`viewcode_enable_epub`). -There is an additional config value: +Configuration +------------- .. confval:: viewcode_follow_imported_members If this is ``True``, viewcode extension will follow alias objects that - imported from another module such as functions, classes and attributes. - As side effects, this option - else they produce nothing. The default is ``True``. + imported from another module such as functions, classes and attributes. As + side effects, this option else they produce nothing. The default is + ``True``. .. versionadded:: 1.3 From d9ccc957173da20174271e6950988cff9e091a42 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Fri, 3 Nov 2017 20:58:21 +0000 Subject: [PATCH 04/35] doc: Add "extensions" to usage guide Signed-off-by: Stephen Finucane --- doc/contents.rst | 2 +- doc/ext/builtins.rst | 25 --------- doc/extensions.rst | 16 ------ doc/glossary.rst | 6 +++ doc/usage/builders/index.rst | 2 +- doc/usage/configuration.rst | 5 +- doc/{ext => usage/extensions}/autodoc.rst | 0 .../extensions}/autosectionlabel.rst | 0 doc/{ext => usage/extensions}/autosummary.rst | 0 doc/{ext => usage/extensions}/coverage.rst | 0 doc/{ext => usage/extensions}/doctest.rst | 0 .../extensions}/example_google.py | 0 .../extensions}/example_google.rst | 0 .../extensions}/example_numpy.py | 0 .../extensions}/example_numpy.rst | 0 doc/{ext => usage/extensions}/extlinks.rst | 0 doc/{ext => usage/extensions}/githubpages.rst | 0 doc/{ext => usage/extensions}/graphviz.rst | 0 doc/{ext => usage/extensions}/ifconfig.rst | 0 .../extensions}/imgconverter.rst | 0 .../extensions/index.rst} | 51 ++++++++++++++++--- doc/{ext => usage/extensions}/inheritance.rst | 0 doc/{ext => usage/extensions}/intersphinx.rst | 0 doc/{ext => usage/extensions}/linkcode.rst | 0 doc/{ext => usage/extensions}/math.rst | 0 doc/{ext => usage/extensions}/napoleon.rst | 0 doc/{ext => usage/extensions}/todo.rst | 0 doc/{ext => usage/extensions}/viewcode.rst | 0 doc/usage/quickstart.rst | 7 +-- setup.cfg | 2 +- 30 files changed, 58 insertions(+), 58 deletions(-) delete mode 100644 doc/ext/builtins.rst delete mode 100644 doc/extensions.rst rename doc/{ext => usage/extensions}/autodoc.rst (100%) rename doc/{ext => usage/extensions}/autosectionlabel.rst (100%) rename doc/{ext => usage/extensions}/autosummary.rst (100%) rename doc/{ext => usage/extensions}/coverage.rst (100%) rename doc/{ext => usage/extensions}/doctest.rst (100%) rename doc/{ext => usage/extensions}/example_google.py (100%) rename doc/{ext => usage/extensions}/example_google.rst (100%) rename doc/{ext => usage/extensions}/example_numpy.py (100%) rename doc/{ext => usage/extensions}/example_numpy.rst (100%) rename doc/{ext => usage/extensions}/extlinks.rst (100%) rename doc/{ext => usage/extensions}/githubpages.rst (100%) rename doc/{ext => usage/extensions}/graphviz.rst (100%) rename doc/{ext => usage/extensions}/ifconfig.rst (100%) rename doc/{ext => usage/extensions}/imgconverter.rst (100%) rename doc/{ext/thirdparty.rst => usage/extensions/index.rst} (51%) rename doc/{ext => usage/extensions}/inheritance.rst (100%) rename doc/{ext => usage/extensions}/intersphinx.rst (100%) rename doc/{ext => usage/extensions}/linkcode.rst (100%) rename doc/{ext => usage/extensions}/math.rst (100%) rename doc/{ext => usage/extensions}/napoleon.rst (100%) rename doc/{ext => usage/extensions}/todo.rst (100%) rename doc/{ext => usage/extensions}/viewcode.rst (100%) diff --git a/doc/contents.rst b/doc/contents.rst index 2da3cb979..93f89f388 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -13,6 +13,7 @@ Sphinx documentation contents usage/markdown usage/configuration usage/builders/index + usage/extensions/index intro man/index @@ -21,7 +22,6 @@ Sphinx documentation contents setuptools templating latex - extensions extdev/index websupport diff --git a/doc/ext/builtins.rst b/doc/ext/builtins.rst deleted file mode 100644 index 6972a5957..000000000 --- a/doc/ext/builtins.rst +++ /dev/null @@ -1,25 +0,0 @@ -Builtin Sphinx extensions -------------------------- - -These extensions are built in and can be activated by respective entries in the -:confval:`extensions` configuration value: - -.. toctree:: - - autodoc - autosectionlabel - autosummary - coverage - doctest - extlinks - githubpages - graphviz - ifconfig - imgconverter - inheritance - intersphinx - linkcode - math - napoleon - todo - viewcode diff --git a/doc/extensions.rst b/doc/extensions.rst deleted file mode 100644 index c005218e8..000000000 --- a/doc/extensions.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _extensions: - -Sphinx Extensions -================= - -Since many projects will need special features in their documentation, Sphinx -allows adding "extensions" to the build process, each of which can modify almost -any aspect of document processing. - -This chapter describes the extensions bundled with Sphinx. For the API -documentation on writing your own extension, see :ref:`dev-extensions`. - -.. toctree:: - - ext/builtins - ext/thirdparty diff --git a/doc/glossary.rst b/doc/glossary.rst index c74409453..d3367e5df 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -67,6 +67,12 @@ Glossary parsing stage, so that successive runs only need to read and parse new and changed documents. + extension + A custom :term:`role`, :term:`directive` or other aspect of Sphinx that + allows users to modify any aspect of the build process within Sphinx. + + For more information, refer to :doc:`/usage/extensions/index`. + master document The document that contains the root :rst:dir:`toctree` directive. diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst index ee0aa0a33..bb107162c 100644 --- a/doc/usage/builders/index.rst +++ b/doc/usage/builders/index.rst @@ -8,7 +8,7 @@ Builders :synopsis: Available built-in builder classes. These are the built-in Sphinx builders. More builders can be added by -:ref:`extensions `. +:doc:`extensions `. The builder's "name" must be given to the **-b** command-line option of :program:`sphinx-build` to select a builder. diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 83700e65e..225b7fa01 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -65,8 +65,9 @@ General configuration .. confval:: extensions - A list of strings that are module names of :ref:`extensions`. These can be - extensions coming with Sphinx (named ``sphinx.ext.*``) or custom ones. + A list of strings that are module names of :doc:`extensions + `. These can be extensions coming with Sphinx (named + ``sphinx.ext.*``) or custom ones. Note that you can extend :data:`sys.path` within the conf file if your extensions live in another directory -- but make sure you use absolute paths. diff --git a/doc/ext/autodoc.rst b/doc/usage/extensions/autodoc.rst similarity index 100% rename from doc/ext/autodoc.rst rename to doc/usage/extensions/autodoc.rst diff --git a/doc/ext/autosectionlabel.rst b/doc/usage/extensions/autosectionlabel.rst similarity index 100% rename from doc/ext/autosectionlabel.rst rename to doc/usage/extensions/autosectionlabel.rst diff --git a/doc/ext/autosummary.rst b/doc/usage/extensions/autosummary.rst similarity index 100% rename from doc/ext/autosummary.rst rename to doc/usage/extensions/autosummary.rst diff --git a/doc/ext/coverage.rst b/doc/usage/extensions/coverage.rst similarity index 100% rename from doc/ext/coverage.rst rename to doc/usage/extensions/coverage.rst diff --git a/doc/ext/doctest.rst b/doc/usage/extensions/doctest.rst similarity index 100% rename from doc/ext/doctest.rst rename to doc/usage/extensions/doctest.rst diff --git a/doc/ext/example_google.py b/doc/usage/extensions/example_google.py similarity index 100% rename from doc/ext/example_google.py rename to doc/usage/extensions/example_google.py diff --git a/doc/ext/example_google.rst b/doc/usage/extensions/example_google.rst similarity index 100% rename from doc/ext/example_google.rst rename to doc/usage/extensions/example_google.rst diff --git a/doc/ext/example_numpy.py b/doc/usage/extensions/example_numpy.py similarity index 100% rename from doc/ext/example_numpy.py rename to doc/usage/extensions/example_numpy.py diff --git a/doc/ext/example_numpy.rst b/doc/usage/extensions/example_numpy.rst similarity index 100% rename from doc/ext/example_numpy.rst rename to doc/usage/extensions/example_numpy.rst diff --git a/doc/ext/extlinks.rst b/doc/usage/extensions/extlinks.rst similarity index 100% rename from doc/ext/extlinks.rst rename to doc/usage/extensions/extlinks.rst diff --git a/doc/ext/githubpages.rst b/doc/usage/extensions/githubpages.rst similarity index 100% rename from doc/ext/githubpages.rst rename to doc/usage/extensions/githubpages.rst diff --git a/doc/ext/graphviz.rst b/doc/usage/extensions/graphviz.rst similarity index 100% rename from doc/ext/graphviz.rst rename to doc/usage/extensions/graphviz.rst diff --git a/doc/ext/ifconfig.rst b/doc/usage/extensions/ifconfig.rst similarity index 100% rename from doc/ext/ifconfig.rst rename to doc/usage/extensions/ifconfig.rst diff --git a/doc/ext/imgconverter.rst b/doc/usage/extensions/imgconverter.rst similarity index 100% rename from doc/ext/imgconverter.rst rename to doc/usage/extensions/imgconverter.rst diff --git a/doc/ext/thirdparty.rst b/doc/usage/extensions/index.rst similarity index 51% rename from doc/ext/thirdparty.rst rename to doc/usage/extensions/index.rst index 20dda9ff1..ae9639ee8 100644 --- a/doc/ext/thirdparty.rst +++ b/doc/usage/extensions/index.rst @@ -1,9 +1,50 @@ +========== +Extensions +========== + +Since many projects will need special features in their documentation, Sphinx +allows adding "extensions" to the build process, each of which can modify +almost any aspect of document processing. + +This chapter describes the extensions bundled with Sphinx. For the API +documentation on writing your own extension, refer to :ref:`dev-extensions`. + + +Built-in extensions +------------------- + +These extensions are built in and can be activated by respective entries in the +:confval:`extensions` configuration value: + +.. toctree:: + + autodoc + autosectionlabel + autosummary + coverage + doctest + extlinks + githubpages + graphviz + ifconfig + imgconverter + inheritance + intersphinx + linkcode + math + napoleon + todo + viewcode + + Third-party extensions ---------------------- +.. todo:: This should reference the GitHub organization now + You can find several extensions contributed by users in the `Sphinx Contrib`_ -repository. It is open for anyone who wants to maintain an extension -publicly; just send a short message asking for write permissions. +repository. It is open for anyone who wants to maintain an extension publicly; +just send a short message asking for write permissions. There are also several extensions hosted elsewhere. The `Sphinx extension survey `__ and `awesome-sphinxdoc @@ -16,15 +57,13 @@ list (`join here `_). .. _Sphinx Contrib: https://bitbucket.org/birkenfeld/sphinx-contrib - Where to put your own extensions? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Extensions local to a project should be put within the project's directory structure. Set Python's module search path, ``sys.path``, accordingly so that -Sphinx can find them. -E.g., if your extension ``foo.py`` lies in the ``exts`` subdirectory of the -project root, put into :file:`conf.py`:: +Sphinx can find them. For example, if your extension ``foo.py`` lies in the +``exts`` subdirectory of the project root, put into :file:`conf.py`:: import sys, os diff --git a/doc/ext/inheritance.rst b/doc/usage/extensions/inheritance.rst similarity index 100% rename from doc/ext/inheritance.rst rename to doc/usage/extensions/inheritance.rst diff --git a/doc/ext/intersphinx.rst b/doc/usage/extensions/intersphinx.rst similarity index 100% rename from doc/ext/intersphinx.rst rename to doc/usage/extensions/intersphinx.rst diff --git a/doc/ext/linkcode.rst b/doc/usage/extensions/linkcode.rst similarity index 100% rename from doc/ext/linkcode.rst rename to doc/usage/extensions/linkcode.rst diff --git a/doc/ext/math.rst b/doc/usage/extensions/math.rst similarity index 100% rename from doc/ext/math.rst rename to doc/usage/extensions/math.rst diff --git a/doc/ext/napoleon.rst b/doc/usage/extensions/napoleon.rst similarity index 100% rename from doc/ext/napoleon.rst rename to doc/usage/extensions/napoleon.rst diff --git a/doc/ext/todo.rst b/doc/usage/extensions/todo.rst similarity index 100% rename from doc/ext/todo.rst rename to doc/usage/extensions/todo.rst diff --git a/doc/ext/viewcode.rst b/doc/usage/extensions/viewcode.rst similarity index 100% rename from doc/ext/viewcode.rst rename to doc/usage/extensions/viewcode.rst diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst index e90b993c6..fabbf9905 100644 --- a/doc/usage/quickstart.rst +++ b/doc/usage/quickstart.rst @@ -318,12 +318,7 @@ features of intersphinx. More topics to be covered ------------------------- -- :doc:`Other extensions `: - - * :doc:`/ext/math`, - * :doc:`/ext/viewcode`, - * :doc:`/ext/doctest`, - * ... +- :doc:`Other extensions `: - Static files - :doc:`Selecting a theme ` - :doc:`/setuptools` diff --git a/setup.cfg b/setup.cfg index 091b59bbd..86f0be001 100644 --- a/setup.cfg +++ b/setup.cfg @@ -32,7 +32,7 @@ directory = sphinx/locale/ [flake8] max-line-length = 95 ignore = E116,E241,E251,E741,I101 -exclude = .git,.tox,.venv,tests/*,build/*,doc/_build/*,sphinx/search/*,doc/ext/example*.py +exclude = .git,.tox,.venv,tests/*,build/*,doc/_build/*,sphinx/search/*,doc/usage/extensions/example*.py application-import-names = sphinx import-order-style = smarkets From c0f42b6519e411ab92dc9a1fb1514e0f56f0763c Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Wed, 20 Jun 2018 09:34:16 +0100 Subject: [PATCH 05/35] Escape raw strings These were resulting in the below warning messages when running flake8 under Python 3.6. :48: DeprecationWarning: invalid escape sequence \[ :143: DeprecationWarning: invalid escape sequence \- :250: DeprecationWarning: invalid escape sequence \s Signed-off-by: Stephen Finucane --- sphinx/builders/qthelp.py | 2 +- sphinx/directives/other.py | 2 +- sphinx/writers/latex.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/sphinx/builders/qthelp.py b/sphinx/builders/qthelp.py index a40cb2709..1b666cb4d 100644 --- a/sphinx/builders/qthelp.py +++ b/sphinx/builders/qthelp.py @@ -140,7 +140,7 @@ class QtHelpBuilder(StandaloneHTMLBuilder): else: nspace = 'org.sphinx.%s.%s' % (outname, self.config.version) - nspace = re.sub('[^a-zA-Z0-9.\-]', '', nspace) + nspace = re.sub(r'[^a-zA-Z0-9.\-]', '', nspace) nspace = re.sub(r'\.+', '.', nspace).strip('.') nspace = nspace.lower() diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index 41b21f917..c6c82ff43 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -45,7 +45,7 @@ locale.versionlabels = DeprecatedDict( RemovedInSphinx30Warning ) -glob_re = re.compile('.*[*?\[].*') +glob_re = re.compile(r'.*[*?\[].*') def int_or_nothing(argument): diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index e4fdf3ca1..dfb698b35 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -247,7 +247,7 @@ class ExtBabel(Babel): def get_mainlanguage_options(self): # type: () -> unicode - """Return options for polyglossia's ``\setmainlanguage``.""" + """Return options for polyglossia's ``\\setmainlanguage``.""" if self.use_polyglossia is False: return None elif self.language == 'german': From 93589a3572814dd699aada718233a127c7811291 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Wed, 20 Jun 2018 09:53:29 +0100 Subject: [PATCH 06/35] tox: Run everything but unit tests under Python 3 The demise of Python 2.7 is not far off and we intend to drop support for it in Sphinx 2.0. As a result, there probably isn't a better time than now to start testing with Python 3 by default. There are a couple of advantages to this: - flake8 is stricter under Python 3 and we don't need to ignore files with Python 3 syntax - We get to dogfood Sphinx against its own documentation using Python 3 - pylint gains support for Python 3 syntax Signed-off-by: Stephen Finucane --- tox.ini | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tox.ini b/tox.ini index 16ea8f9ba..d2f253fb3 100644 --- a/tox.ini +++ b/tox.ini @@ -27,12 +27,14 @@ commands= pytest -Wall --durations 25 {posargs} [testenv:flake8] +basepython = python3 description = Run style checks. commands = flake8 [testenv:pylint] +basepython = python3 description = Run source code analyzer. deps = @@ -42,6 +44,7 @@ commands = pylint --rcfile utils/pylintrc sphinx [testenv:coverage] +basepython = python3 description = Run code coverage checks. setenv = @@ -51,6 +54,7 @@ commands = coverage report [testenv:mypy] +basepython = python3 description = Run type checks. deps = @@ -59,6 +63,7 @@ commands= mypy sphinx/ [testenv:docs] +basepython = python3 description = Build documentation. commands = From 2a4827af4f8fb161c4c23157e3c25e72dd68d8c9 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Wed, 20 Jun 2018 19:11:20 +0100 Subject: [PATCH 07/35] make: Default to Python 3 As with the tox change, it makes sense to test things against Python 3 by default now, seeing as that will be the only version supported in Sphinx 2.0. Signed-off-by: Stephen Finucane --- Makefile | 2 +- doc/Makefile | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 04ec5be96..1d14ea277 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -PYTHON ?= python +PYTHON ?= python3 .PHONY: all all: clean-pyc clean-backupfiles style-check type-check test diff --git a/doc/Makefile b/doc/Makefile index 4d2067071..d90ae0881 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,6 +1,6 @@ # Makefile for Sphinx documentation # -PYTHON ?= python +PYTHON ?= python3 # You can set these variables from the command line. SPHINXOPTS = From 3eb26a33358ab2181ec1469de109e6176945bfaf Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Thu, 21 Jun 2018 15:11:42 +0100 Subject: [PATCH 08/35] travis: Run flake8 against Python 3.6 As with tox and make before it, we run everything that we can against Python 3 (Python 3.6 in this case). Signed-off-by: Stephen Finucane --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 1662af810..86d7559ca 100644 --- a/.travis.yml +++ b/.travis.yml @@ -30,7 +30,7 @@ matrix: env: TOXENV=docs - python: '3.6' env: TOXENV=mypy - - python: '2.7' + - python: '3.6' env: TOXENV=flake8 install: From c2b85b923f193b5558485504c6830cc2c5f60916 Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Mon, 25 Jun 2018 06:38:32 +0200 Subject: [PATCH 09/35] doc: fix list with add_object_type This seems to have been accidentally broken in eaaab75ec. --- sphinx/application.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/sphinx/application.py b/sphinx/application.py index cfaba1161..937f78323 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -850,8 +850,9 @@ class Sphinx(object): object. It will automatically add index entries if *indextemplate* is nonempty; if given, it must contain exactly one instance of ``%s``. See the example below for how the template will be - interpreted. * Create a new role (called *rolename*) to - cross-reference to these object descriptions. + interpreted. + - Create a new role (called *rolename*) to cross-reference to these + object descriptions. - If you provide *parse_node*, it must be a function that takes a string and a docutils node, and it must populate the node with children parsed from the string. It must then return the name of the From 8f94429a211ae1217f64704dc31785feebea88f8 Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Mon, 25 Jun 2018 08:23:15 +0200 Subject: [PATCH 10/35] doc: fix func/meth references to Sphinx --- doc/extdev/parserapi.rst | 2 +- doc/usage/configuration.rst | 2 +- doc/usage/restructuredtext/roles.rst | 2 +- sphinx/application.py | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/extdev/parserapi.rst b/doc/extdev/parserapi.rst index e71661b2e..11a690387 100644 --- a/doc/extdev/parserapi.rst +++ b/doc/extdev/parserapi.rst @@ -12,7 +12,7 @@ __ http://docutils.sourceforge.net/docs/dev/hacking.html#parsing-the-document In Sphinx, the parser modules works as same as docutils. The parsers are registered to Sphinx by extensions using Application APIs; -:meth:`Sphinx.add_source_suffix()` and :meth:`Sphinx.add_source_parsers()`. +:meth:`.Sphinx.add_source_suffix()` and :meth:`.Sphinx.add_source_parsers()`. The *source suffix* is a mapping from file suffix to file type. For example, ``.rst`` file is mapped to ``'restructuredtext'`` type. Sphinx uses the diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 83700e65e..4fc540c2c 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -142,7 +142,7 @@ General configuration .. versionadded:: 1.3 .. deprecated:: 1.8 - Now Sphinx provides an API :meth:`Sphinx.add_source_parser` to register + Now Sphinx provides an API :meth:`.Sphinx.add_source_parser` to register a source parser. Please use it instead. .. confval:: master_doc diff --git a/doc/usage/restructuredtext/roles.rst b/doc/usage/restructuredtext/roles.rst index 04991c3a9..882647d07 100644 --- a/doc/usage/restructuredtext/roles.rst +++ b/doc/usage/restructuredtext/roles.rst @@ -62,7 +62,7 @@ Cross-referencing anything by :rst:role:`doc`, :rst:role:`ref` or :rst:role:`option`. Custom objects added to the standard domain by extensions (see - :meth:`Sphinx.add_object_type`) are also searched. + :meth:`.Sphinx.add_object_type`) are also searched. * Then, it looks for objects (targets) in all loaded domains. It is up to the domains how specific a match must be. For example, in the Python diff --git a/sphinx/application.py b/sphinx/application.py index cfaba1161..20ee2012c 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -642,7 +642,7 @@ class Sphinx(object): a title. Other keyword arguments are used for node visitor functions. See the - :meth:`Sphinx.add_node` for details. + :meth:`.Sphinx.add_node` for details. .. versionadded:: 1.4 """ From b6c4ebc37aaae48b20f709bb4712921281f5006e Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 30 Jun 2018 01:43:54 +0900 Subject: [PATCH 11/35] Fix #5125: sphinx-build: Interface of ``sphinx:main()`` has changed --- CHANGES | 1 + sphinx/__init__.py | 6 +++--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/CHANGES b/CHANGES index b860e53ed..144ac28a7 100644 --- a/CHANGES +++ b/CHANGES @@ -33,6 +33,7 @@ Bugs fixed * #5091: latex: curly braces in index entries are not handled correctly * #5070: epub: Wrong internal href fragment links * #5104: apidoc: Interface of ``sphinx.apidoc:main()`` has changed +* #5125: sphinx-build: Interface of ``sphinx:main()`` has changed Testing -------- diff --git a/sphinx/__init__.py b/sphinx/__init__.py index c81166603..34bd365bc 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -60,15 +60,15 @@ if __version__.endswith('+'): pass -def main(*args, **kwargs): +def main(argv=sys.argv): from .cmd import build warnings.warn( '`sphinx.main()` has moved to `sphinx.cmd.build.main()`.', RemovedInSphinx20Warning, stacklevel=2, ) - args = args[1:] # skip first argument to adjust arguments (refs: #4615) - return build.main(*args, **kwargs) + argv = argv[1:] # skip first argument to adjust arguments (refs: #4615) + return build.main(argv) def build_main(argv=sys.argv): From b8f4e5d1421632059b7d23cabb5e494c9f470db4 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sat, 30 Jun 2018 01:46:04 +0900 Subject: [PATCH 12/35] Fix sphinx-build: ``sphinx.cmd.build.main()`` refers ``sys.argv`` instead of given argument --- CHANGES | 2 ++ sphinx/cmd/build.py | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index 144ac28a7..44d16ced3 100644 --- a/CHANGES +++ b/CHANGES @@ -34,6 +34,8 @@ Bugs fixed * #5070: epub: Wrong internal href fragment links * #5104: apidoc: Interface of ``sphinx.apidoc:main()`` has changed * #5125: sphinx-build: Interface of ``sphinx:main()`` has changed +* sphinx-build: ``sphinx.cmd.build.main()`` refers ``sys.argv`` instead of given + argument Testing -------- diff --git a/sphinx/cmd/build.py b/sphinx/cmd/build.py index c0c31ae67..1add951ca 100644 --- a/sphinx/cmd/build.py +++ b/sphinx/cmd/build.py @@ -32,7 +32,7 @@ def make_main(argv=sys.argv[1:]): def main(argv=sys.argv[1:]): # type: (List[str]) -> int - if sys.argv[1:2] == ['-M']: + if argv[:1] == ['-M']: return make_main(argv) else: return build_main(argv) From 0f5d5ac126d81175f5569b7ff505a79e6d810226 Mon Sep 17 00:00:00 2001 From: jfbu Date: Sat, 30 Jun 2018 19:51:37 +0200 Subject: [PATCH 13/35] Add ``latex_use_xindy`` new config variable for UTF-8 enabled indices Fix: #5132 --- sphinx/builders/latex/__init__.py | 35 +++++++++++++++++++++++++++++- sphinx/templates/latex/latex.tex_t | 2 +- sphinx/texinputs/Makefile_t | 6 +++++ sphinx/texinputs/latexmkrc_t | 4 ++++ sphinx/texinputs/python.xdy | 16 ++++++++++++++ sphinx/texinputs/sphinx.sty | 4 +++- sphinx/writers/latex.py | 7 ++++-- 7 files changed, 69 insertions(+), 5 deletions(-) create mode 100644 sphinx/texinputs/python.xdy diff --git a/sphinx/builders/latex/__init__.py b/sphinx/builders/latex/__init__.py index 382914731..806b67723 100644 --- a/sphinx/builders/latex/__init__.py +++ b/sphinx/builders/latex/__init__.py @@ -44,6 +44,31 @@ if False: from sphinx.config import Config # NOQA +XINDY_LANGUAGES = { +# currently only Latin scripts here, for use with -L option of texindy +# code, name + 'hr': 'croatian', + 'cs': 'czech', + 'da': 'danish', + 'en': 'english', + 'et': 'estonian', + 'fi': 'finnish', + 'fr': 'french', + 'de': 'german-din', # there is also german-duden + 'hu': 'hungarian', + 'it': 'italian', + 'lv': 'latvian', + 'lt': 'lithuanian', + 'nb': 'norwegian', + 'pl': 'polish', + 'pt': 'portuguese', + 'sk': 'slovak-small', # xindy recognizes slovak-small and slovak-large + 'sl': 'slovenian', + 'es': 'spanish-modern', + 'sv': 'swedish', + 'tr': 'turkish' +} + logger = logging.getLogger(__name__) @@ -232,7 +257,14 @@ class LaTeXBuilder(Builder): self.copy_image_files() # copy TeX support files from texinputs - context = {'latex_engine': self.config.latex_engine} + if self.config.language: + xindy_lang = \ + XINDY_LANGUAGES.get(self.config.language[:2], 'general') + else: + xindy_lang = 'english' + context = {'latex_engine': self.config.latex_engine, + 'latex_use_xindy': self.config.latex_use_xindy, + 'xindy_lang': xindy_lang} logger.info(bold(__('copying TeX support files...'))) staticdirname = path.join(package_dir, 'texinputs') for filename in os.listdir(staticdirname): @@ -334,6 +366,7 @@ def setup(app): app.add_config_value('latex_logo', None, None, string_classes) app.add_config_value('latex_appendices', [], None) app.add_config_value('latex_use_latex_multicolumn', False, None) + app.add_config_value('latex_use_xindy', False, None) app.add_config_value('latex_toplevel_sectioning', None, None, ENUM(None, 'part', 'chapter', 'section')) app.add_config_value('latex_domain_indices', True, None, [list]) diff --git a/sphinx/templates/latex/latex.tex_t b/sphinx/templates/latex/latex.tex_t index 0ea75557f..5a158444c 100644 --- a/sphinx/templates/latex/latex.tex_t +++ b/sphinx/templates/latex/latex.tex_t @@ -31,7 +31,7 @@ <%= hyperref %> <%= contentsname %> <%= numfig_format %> -<%= literalblockpto %> +<%= translatablestrings %> <%= pageautorefname %> <%= tocdepth %> <%= secnumdepth %> diff --git a/sphinx/texinputs/Makefile_t b/sphinx/texinputs/Makefile_t index 06bd6c4d7..82ea29de1 100644 --- a/sphinx/texinputs/Makefile_t +++ b/sphinx/texinputs/Makefile_t @@ -22,6 +22,12 @@ export LATEXOPTS = # or on command line for faster builds. {% endif -%} LATEXMKOPTS = +{% if latex_use_xindy -%} +export XINDYOPTS = -L {{ xindy_lang }} -C utf8 -M python.xdy +{% if latex_engine == 'xelatex' or latex_engine == 'lualatex' -%} +export XINDYOPTS += -I xelatex +{% endif -%} +{% endif -%} # format: pdf or dvi (used only by archive targets) FMT = pdf diff --git a/sphinx/texinputs/latexmkrc_t b/sphinx/texinputs/latexmkrc_t index e3cd14f48..c0965ffe3 100644 --- a/sphinx/texinputs/latexmkrc_t +++ b/sphinx/texinputs/latexmkrc_t @@ -10,7 +10,11 @@ $pdflatex = 'xelatex ' . $ENV{'LATEXOPTS'} . ' %O %S'; {% endif -%} $lualatex = 'lualatex ' . $ENV{'LATEXOPTS'} . ' %O %S'; $xelatex = 'xelatex --no-pdf ' . $ENV{'LATEXOPTS'} . ' %O %S'; +{% if latex_use_xindy -%} +$makeindex = 'texindy ' . $ENV{'XINDYOPTS'} . ' -t %B.ilg %O -o %D %S'; +{% else -%} $makeindex = 'makeindex -s python.ist %O -o %D %S'; +{% endif -%} add_cus_dep( "glo", "gls", 0, "makeglo" ); sub makeglo { return system( "makeindex -s gglo.ist -o '$_[0].gls' '$_[0].glo'" ); diff --git a/sphinx/texinputs/python.xdy b/sphinx/texinputs/python.xdy new file mode 100644 index 000000000..1095437e6 --- /dev/null +++ b/sphinx/texinputs/python.xdy @@ -0,0 +1,16 @@ +(markup-index :open "\begin{sphinxtheindex} +\providecommand\lettergroup[1]{{\Large\sffamily#1}\nopagebreak\vspace{1mm}} +\providecommand\lettergroupDefault[1]{{\Large\sffamily\sphinxsymbolsandnumbersname}\nopagebreak\vspace{1mm}} + +" + :close " + +\end{sphinxtheindex} +" + :tree) + +;; End + +;; Local Variables: +;; mode: lisp +;; End: diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 96be30338..42aeedc88 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -6,7 +6,7 @@ % \NeedsTeXFormat{LaTeX2e}[1995/12/01] -\ProvidesPackage{sphinx}[2018/03/28 v1.8 LaTeX package (Sphinx markup)] +\ProvidesPackage{sphinx}[2018/06/30 v1.8 LaTeX package (Sphinx markup)] % provides \ltx@ifundefined % (many packages load ltxcmds: graphicx does for pdftex and lualatex but @@ -470,6 +470,8 @@ {\newenvironment{sphinxtheindex}{\begin{theindex}}{\end{theindex}}}% {}% else clause of \ltx@ifundefined +% for usage with xindy string is internationalized in document preamble +\newcommand*{\sphinxsymbolsandnumbersname}{Symbols and Numbers} %% COLOR (general) % diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 55d37da79..c335e611d 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -130,7 +130,7 @@ DEFAULT_SETTINGS = { 'tocdepth': '', 'secnumdepth': '', 'pageautorefname': '', - 'literalblockpto': '', + 'translatablestrings': '', } # type: Dict[unicode, unicode] ADDITIONAL_SETTINGS = { @@ -667,12 +667,15 @@ class LaTeXTranslator(nodes.NodeVisitor): if self.elements['extraclassoptions']: self.elements['classoptions'] += ',' + \ self.elements['extraclassoptions'] - self.elements['literalblockpto'] = ( + self.elements['translatablestrings'] = ( self.babel_renewcommand( '\\literalblockcontinuedname', self.encode(_('continued from previous page')) ) + self.babel_renewcommand( '\\literalblockcontinuesname', self.encode(_('continues on next page')) + ) + + self.babel_renewcommand( + '\\sphinxsymbolsandnumbersname', self.encode(_('Symbols and Numbers')) ) ) self.elements['pageautorefname'] = \ From 90c2b528b1595d9efe7497682f5e0172517453c7 Mon Sep 17 00:00:00 2001 From: jfbu Date: Sat, 30 Jun 2018 23:37:26 +0200 Subject: [PATCH 14/35] Update docs and CHANGES for ``latex_use_xindy`` config variable --- CHANGES | 2 ++ doc/usage/configuration.rst | 27 +++++++++++++++++++++++++++ 2 files changed, 29 insertions(+) diff --git a/CHANGES b/CHANGES index d7761f542..d04da2e54 100644 --- a/CHANGES +++ b/CHANGES @@ -143,6 +143,7 @@ Features added for mathjax * #4362: latex: Don't overwrite .tex file if document not changed * #1431: latex: Add alphanumeric enumerated list support +* Add :confval:`latex_use_xindy` for UTF-8 savvy indexing Bugs fixed ---------- @@ -152,6 +153,7 @@ Bugs fixed * #4945: i18n: fix lang_COUNTRY not fallback correctly for IndexBuilder. Thanks to Shengjing Zhu. * #4983: productionlist directive generates invalid IDs for the tokens +* #5132: (lualatex) PDF build fails if indexed word starts with Unicode characters Testing -------- diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index a0fbe641a..99b55f67e 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -1872,6 +1872,33 @@ information. .. versionadded:: 1.6 +.. confval:: latex_use_xindy + + If ``True`` (default ``False``), the PDF build from the LaTeX files + created by Sphinx will use :program:`xindy` (doc__) rather than + :program:`makeindex`. This means that utf-8 initials in indexed + words will be handled correctly, and entries will be ordered + according to the rules appropriate to the :confval:`language`. + Currently, this uses :program:`texindy` and only (most) European + languages with Latin scripts are supported. For usages requiring + direct use of ``xindy``, user will have to customize the files + :file:`Makefile` and :file:`latexmkrc` which are written to LaTeX + build repertory. This can be done via + :confval:`latex_additional_files` and customized such files located + in source repertory. + + __ http://xindy.sourceforge.net/ + + This option is recommended in case of :confval:`latex_engine` set + to ``xelatex`` or ``lualatex`` (it is even mandatory for the latter + as the PDF build is broken if some indexed terms start with a + non-ascii character). It is without effect in case of + :confval:`platex` (Japanese documents). Even if + :confval:`latex_engine` is left to its default, the option is + recommended as soon as indexed terms use non-ascii characters. + + .. versionadded:: 1.8 + .. confval:: latex_elements .. versionadded:: 0.5 From 5a383e13e6a5cefbadc0ca7a371929ed6c268ad5 Mon Sep 17 00:00:00 2001 From: jfbu Date: Sun, 1 Jul 2018 00:13:31 +0200 Subject: [PATCH 15/35] Fix flake8 --- sphinx/builders/latex/__init__.py | 44 +++++++++++++++---------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/sphinx/builders/latex/__init__.py b/sphinx/builders/latex/__init__.py index 806b67723..d90feb32b 100644 --- a/sphinx/builders/latex/__init__.py +++ b/sphinx/builders/latex/__init__.py @@ -45,28 +45,28 @@ if False: XINDY_LANGUAGES = { -# currently only Latin scripts here, for use with -L option of texindy -# code, name - 'hr': 'croatian', - 'cs': 'czech', - 'da': 'danish', - 'en': 'english', - 'et': 'estonian', - 'fi': 'finnish', - 'fr': 'french', - 'de': 'german-din', # there is also german-duden - 'hu': 'hungarian', - 'it': 'italian', - 'lv': 'latvian', - 'lt': 'lithuanian', - 'nb': 'norwegian', - 'pl': 'polish', - 'pt': 'portuguese', - 'sk': 'slovak-small', # xindy recognizes slovak-small and slovak-large - 'sl': 'slovenian', - 'es': 'spanish-modern', - 'sv': 'swedish', - 'tr': 'turkish' + # currently only Latin scripts here, for use with -L option of texindy + # code, name + 'hr': 'croatian', + 'cs': 'czech', + 'da': 'danish', + 'en': 'english', + 'et': 'estonian', + 'fi': 'finnish', + 'fr': 'french', + 'de': 'german-din', # there is also german-duden + 'hu': 'hungarian', + 'it': 'italian', + 'lv': 'latvian', + 'lt': 'lithuanian', + 'nb': 'norwegian', + 'pl': 'polish', + 'pt': 'portuguese', + 'sk': 'slovak-small', # xindy recognizes slovak-small and slovak-large + 'sl': 'slovenian', + 'es': 'spanish-modern', + 'sv': 'swedish', + 'tr': 'turkish' } logger = logging.getLogger(__name__) From a6d063eb01cb89f3e5460d7b31b02b197f303de7 Mon Sep 17 00:00:00 2001 From: jfbu Date: Tue, 3 Jul 2018 14:38:39 +0200 Subject: [PATCH 16/35] LaTeX: improve customizabilty of Sphinx generated indices --- sphinx/texinputs/python.ist | 2 +- sphinx/texinputs/python.xdy | 4 ++-- sphinx/texinputs/sphinx.sty | 10 ++++++---- sphinx/writers/latex.py | 5 ++--- 4 files changed, 11 insertions(+), 10 deletions(-) diff --git a/sphinx/texinputs/python.ist b/sphinx/texinputs/python.ist index 687d26cd4..f560754c0 100644 --- a/sphinx/texinputs/python.ist +++ b/sphinx/texinputs/python.ist @@ -3,7 +3,7 @@ headings_flag 1 heading_prefix " \\bigletter " preamble "\\begin{sphinxtheindex} -\\def\\bigletter#1{{\\Large\\sffamily#1}\\nopagebreak\\vspace{1mm}} +\\let\\bigletter\\sphinxstyleindexletterhead " diff --git a/sphinx/texinputs/python.xdy b/sphinx/texinputs/python.xdy index 1095437e6..d84b9668b 100644 --- a/sphinx/texinputs/python.xdy +++ b/sphinx/texinputs/python.xdy @@ -1,6 +1,6 @@ (markup-index :open "\begin{sphinxtheindex} -\providecommand\lettergroup[1]{{\Large\sffamily#1}\nopagebreak\vspace{1mm}} -\providecommand\lettergroupDefault[1]{{\Large\sffamily\sphinxsymbolsandnumbersname}\nopagebreak\vspace{1mm}} +\let\lettergroup\sphinxstyleindexletterhead +\let\lettergroupDefault\sphinxstyleindexxindygroupheadsymbols " :close " diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 42aeedc88..d8ee2ed65 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -1593,10 +1593,12 @@ {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}} % additional customizable styling -% FIXME: convert this to package options ? -\protected\def\sphinxstyleindexentry #1{\texttt{#1}} -\protected\def\sphinxstyleindexextra #1{ \emph{(#1)}} -\protected\def\sphinxstyleindexpageref #1{, \pageref{#1}} +\def\sphinxstyleindexentry #1{\texttt{#1}} +\def\sphinxstyleindexextra #1{ \emph{(#1)}} +\def\sphinxstyleindexpageref #1{, \pageref{#1}} +\def\sphinxstyleindexletterhead #1{{\Large\sffamily#1}\nopagebreak\vspace{1mm}} +\def\sphinxstyleindexxindygroupheadsymbols + {{\Large\sffamily\sphinxsymbolsandnumbersname}\nopagebreak\vspace{1mm}} \protected\def\sphinxstyletopictitle #1{\textbf{#1}\par\medskip} \let\sphinxstylesidebartitle\sphinxstyletopictitle \protected\def\sphinxstyleothertitle #1{\textbf{#1}} diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index c335e611d..da63f7953 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -859,8 +859,7 @@ class LaTeXTranslator(nodes.NodeVisitor): def generate(content, collapsed): # type: (List[Tuple[unicode, List[Tuple[unicode, unicode, unicode, unicode, unicode]]]], bool) -> None # NOQA ret.append('\\begin{sphinxtheindex}\n') - ret.append('\\def\\bigletter#1{{\\Large\\sffamily#1}' - '\\nopagebreak\\vspace{1mm}}\n') + ret.append('\\let\\bigletter\\sphinxstyleindexletterhead\n') for i, (letter, entries) in enumerate(content): if i > 0: ret.append('\\indexspace\n') @@ -869,7 +868,7 @@ class LaTeXTranslator(nodes.NodeVisitor): for entry in entries: if not entry[3]: continue - ret.append('\\item {\\sphinxstyleindexentry{%s}}' % self.encode(entry[0])) + ret.append('\\item\\relax\\sphinxstyleindexentry{%s}' % self.encode(entry[0])) if entry[4]: # add "extra" info ret.append('\\sphinxstyleindexextra{%s}' % self.encode(entry[4])) From b553c23ab1cadfe75db6637ca95daa11abc87049 Mon Sep 17 00:00:00 2001 From: Michel Alexandre Salim Date: Tue, 3 Jul 2018 09:28:54 -0700 Subject: [PATCH 17/35] Closes #5076: [ext/napoleon] explicitly catch StopIteration (#5119) * Closes #5076: [ext/napoleon] explicitly catch StopIteration Per PEP 479, Python 3.7 no longer allows bubbling up StopIteration outside of a generator. Instead, wrap attribute parsing in a try block and provide a sane default in case it raises an exception ([]). * Fix mypy and flake8 issues --- sphinx/ext/napoleon/docstring.py | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/sphinx/ext/napoleon/docstring.py b/sphinx/ext/napoleon/docstring.py index b349c761f..64107d8fb 100644 --- a/sphinx/ext/napoleon/docstring.py +++ b/sphinx/ext/napoleon/docstring.py @@ -527,7 +527,14 @@ class GoogleDocstring(UnicodeMixin): self._parsed_lines = self._consume_empty() if self._name and (self._what == 'attribute' or self._what == 'data'): - self._parsed_lines.extend(self._parse_attribute_docstring()) + # Implicit stop using StopIteration no longer allowed in + # Python 3.7; see PEP 479 + res = [] # type: List[unicode] + try: + res = self._parse_attribute_docstring() + except StopIteration: + pass + self._parsed_lines.extend(res) return while self._line_iter.has_next(): From 46bc56636e1799f80ead24215c4d4d41fc4665c1 Mon Sep 17 00:00:00 2001 From: jfbu Date: Sun, 1 Jul 2018 10:06:23 +0200 Subject: [PATCH 18/35] Fix: #5133 via ``\sphinxsymbolsname``, ``\sphinxnumbersname`` Also adds usage of \sphinxstyleindexletterhead in python.ist as a customizable alias of original \bigletter. --- CHANGES | 1 + sphinx/texinputs/python.ist | 6 +++--- sphinx/texinputs/sphinx.sty | 10 +++++++--- sphinx/writers/latex.py | 6 ++++++ 4 files changed, 17 insertions(+), 6 deletions(-) diff --git a/CHANGES b/CHANGES index d7761f542..2eee0e158 100644 --- a/CHANGES +++ b/CHANGES @@ -152,6 +152,7 @@ Bugs fixed * #4945: i18n: fix lang_COUNTRY not fallback correctly for IndexBuilder. Thanks to Shengjing Zhu. * #4983: productionlist directive generates invalid IDs for the tokens +* #5133: latex: index headings "Symbols" and "Numbers" not internationalized Testing -------- diff --git a/sphinx/texinputs/python.ist b/sphinx/texinputs/python.ist index 687d26cd4..acb71712e 100644 --- a/sphinx/texinputs/python.ist +++ b/sphinx/texinputs/python.ist @@ -3,11 +3,11 @@ headings_flag 1 heading_prefix " \\bigletter " preamble "\\begin{sphinxtheindex} -\\def\\bigletter#1{{\\Large\\sffamily#1}\\nopagebreak\\vspace{1mm}} +\\let\\bigletter\\sphinxstyleindexletterhead " postamble "\n\n\\end{sphinxtheindex}\n" -symhead_positive "{Symbols}" -numhead_positive "{Numbers}" +symhead_positive "{\\sphinxsymbolsname}" +numhead_positive "{\\sphinxnumbersname}" diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 96be30338..ee7698a46 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -470,6 +470,9 @@ {\newenvironment{sphinxtheindex}{\begin{theindex}}{\end{theindex}}}% {}% else clause of \ltx@ifundefined +% redefined in preamble, headings for makeindex produced index +\newcommand*{\sphinxsymbolsname}{Symbols} +\newcommand*{\sphinxnumbersname}{Numbers} %% COLOR (general) % @@ -1592,9 +1595,10 @@ % additional customizable styling % FIXME: convert this to package options ? -\protected\def\sphinxstyleindexentry #1{\texttt{#1}} -\protected\def\sphinxstyleindexextra #1{ \emph{(#1)}} -\protected\def\sphinxstyleindexpageref #1{, \pageref{#1}} +\def\sphinxstyleindexentry #1{\texttt{#1}} +\def\sphinxstyleindexextra #1{ \emph{(#1)}} +\def\sphinxstyleindexpageref #1{, \pageref{#1}} +\def\sphinxstyleindexletterhead #1{{\Large\sffamily#1}\nopagebreak\vspace{1mm}} \protected\def\sphinxstyletopictitle #1{\textbf{#1}\par\medskip} \let\sphinxstylesidebartitle\sphinxstyletopictitle \protected\def\sphinxstyleothertitle #1{\textbf{#1}} diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 55d37da79..833afd8ee 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -673,6 +673,12 @@ class LaTeXTranslator(nodes.NodeVisitor): ) + self.babel_renewcommand( '\\literalblockcontinuesname', self.encode(_('continues on next page')) + ) + + self.babel_renewcommand( + '\\sphinxsymbolsname', self.encode(_('Symbols')) + ) + + self.babel_renewcommand( + '\\sphinxnumbersname', self.encode(_('Numbers')) ) ) self.elements['pageautorefname'] = \ From e7ee03505047d11c8c8e08e3c10821fe8db97ff8 Mon Sep 17 00:00:00 2001 From: jfbu Date: Wed, 4 Jul 2018 08:37:57 +0200 Subject: [PATCH 19/35] LaTeX use ``\sphinxstyleindexletterhead`` also for domain indices --- sphinx/writers/latex.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 833afd8ee..3b50751c8 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -862,8 +862,7 @@ class LaTeXTranslator(nodes.NodeVisitor): def generate(content, collapsed): # type: (List[Tuple[unicode, List[Tuple[unicode, unicode, unicode, unicode, unicode]]]], bool) -> None # NOQA ret.append('\\begin{sphinxtheindex}\n') - ret.append('\\def\\bigletter#1{{\\Large\\sffamily#1}' - '\\nopagebreak\\vspace{1mm}}\n') + ret.append('\\let\\bigletter\\sphinxstyleindexletterhead\n') for i, (letter, entries) in enumerate(content): if i > 0: ret.append('\\indexspace\n') From 35c69ccfb506595c3728487553bba6f4b267efba Mon Sep 17 00:00:00 2001 From: jfbu Date: Wed, 4 Jul 2018 08:46:25 +0200 Subject: [PATCH 20/35] Fix line too long --- sphinx/writers/latex.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index da63f7953..ee1a886e9 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -868,7 +868,8 @@ class LaTeXTranslator(nodes.NodeVisitor): for entry in entries: if not entry[3]: continue - ret.append('\\item\\relax\\sphinxstyleindexentry{%s}' % self.encode(entry[0])) + ret.append('\\item\\relax\\sphinxstyleindexentry{%s}' % + self.encode(entry[0])) if entry[4]: # add "extra" info ret.append('\\sphinxstyleindexextra{%s}' % self.encode(entry[4])) From d6c85619b4415472e039568f41258d4dd6ba88aa Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 8 Jul 2018 20:41:38 +0900 Subject: [PATCH 21/35] Fix autosummary: warnings of autosummary indicates wrong location (refs: #5146) --- CHANGES | 1 + sphinx/ext/autosummary/__init__.py | 20 +++++++++++--------- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/CHANGES b/CHANGES index b860e53ed..fef9a2113 100644 --- a/CHANGES +++ b/CHANGES @@ -33,6 +33,7 @@ Bugs fixed * #5091: latex: curly braces in index entries are not handled correctly * #5070: epub: Wrong internal href fragment links * #5104: apidoc: Interface of ``sphinx.apidoc:main()`` has changed +* autosummary: warnings of autosummary indicates wrong location (refs: #5146) Testing -------- diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index a1b468a69..84ef340f7 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -77,7 +77,7 @@ from sphinx.ext.autodoc.directive import DocumenterBridge, Options from sphinx.ext.autodoc.importer import import_module from sphinx.pycode import ModuleAnalyzer, PycodeError from sphinx.util import import_object, rst, logging -from sphinx.util.docutils import NullReporter, new_document +from sphinx.util.docutils import NullReporter, new_document, switch_source_input if False: # For type annotation @@ -373,17 +373,19 @@ class Autosummary(Directive): def append_row(*column_texts): # type: (unicode) -> None row = nodes.row('') + source, line = self.state_machine.get_source_and_line() for text in column_texts: node = nodes.paragraph('') vl = ViewList() - vl.append(text, '') - self.state.nested_parse(vl, 0, node) - try: - if isinstance(node[0], nodes.paragraph): - node = node[0] - except IndexError: - pass - row.append(nodes.entry('', node)) + vl.append(text, '%s:%d:' % (source, line)) + with switch_source_input(self.state, vl): + self.state.nested_parse(vl, 0, node) + try: + if isinstance(node[0], nodes.paragraph): + node = node[0] + except IndexError: + pass + row.append(nodes.entry('', node)) body.append(row) for name, sig, summary, real_name in items: From a2f6de88c1285b3826a257f02d61b393467c44ed Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 8 Jul 2018 21:14:01 +0900 Subject: [PATCH 22/35] Fix #5146: autosummary: warning is emitted when the first line of docstring ends with literal notation --- CHANGES | 2 ++ sphinx/ext/autosummary/__init__.py | 4 ++++ tests/test_ext_autosummary.py | 4 ++++ 3 files changed, 10 insertions(+) diff --git a/CHANGES b/CHANGES index b860e53ed..c1bd68e00 100644 --- a/CHANGES +++ b/CHANGES @@ -33,6 +33,8 @@ Bugs fixed * #5091: latex: curly braces in index entries are not handled correctly * #5070: epub: Wrong internal href fragment links * #5104: apidoc: Interface of ``sphinx.apidoc:main()`` has changed +* #5146: autosummary: warning is emitted when the first line of docstring ends + with literal notation Testing -------- diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index a1b468a69..733e81ca5 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -91,6 +91,7 @@ logger = logging.getLogger(__name__) periods_re = re.compile(r'\.(?:\s+)') +literal_re = re.compile(r'::\s*$') # -- autosummary_toc node ------------------------------------------------------ @@ -484,6 +485,9 @@ def extract_summary(doc, document): # considered as that splitting by period does not break inline markups break + # strip literal notation mark ``::`` from tail of summary + summary = literal_re.sub('.', summary) + return summary diff --git a/tests/test_ext_autosummary.py b/tests/test_ext_autosummary.py index 1138fe4a6..fba0ae33c 100644 --- a/tests/test_ext_autosummary.py +++ b/tests/test_ext_autosummary.py @@ -81,6 +81,10 @@ def test_extract_summary(capsys): doc = ['Blabla, i.e. bla.'] assert extract_summary(doc, document) == 'Blabla, i.e.' + # literal + doc = ['blah blah::'] + assert extract_summary(doc, document) == 'blah blah.' + _, err = capsys.readouterr() assert err == '' From 2e66ffba57939fdb408a0fd052c67f79ff3ad55a Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Mon, 9 Jul 2018 10:44:14 +0900 Subject: [PATCH 23/35] Update CHANGES for PR #5119 --- CHANGES | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGES b/CHANGES index b860e53ed..2c4f1aa91 100644 --- a/CHANGES +++ b/CHANGES @@ -33,6 +33,7 @@ Bugs fixed * #5091: latex: curly braces in index entries are not handled correctly * #5070: epub: Wrong internal href fragment links * #5104: apidoc: Interface of ``sphinx.apidoc:main()`` has changed +* #5076: napoleon raises RuntimeError with python 3.7 Testing -------- From 83c93802999f41545fac2e4d94f486a09773cf00 Mon Sep 17 00:00:00 2001 From: Dan Abdinoor Date: Tue, 10 Jul 2018 12:14:45 -0400 Subject: [PATCH 24/35] Fix links to sphinx-build man page Swap``program`` for ``doc`` links to sphinx-build man page. --- doc/usage/quickstart.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst index fabbf9905..0f9452f05 100644 --- a/doc/usage/quickstart.rst +++ b/doc/usage/quickstart.rst @@ -127,7 +127,7 @@ directory in which you want to place the built documentation. The :option:`-b ` option selects a builder; in this example Sphinx will build HTML files. -|more| Refer to the :program:`sphinx-build man page ` for all +|more| Refer to the :doc:`sphinx-build man page ` for all options that :program:`sphinx-build` supports. However, :program:`sphinx-quickstart` script creates a :file:`Makefile` and a @@ -331,7 +331,7 @@ More topics to be covered .. [#] This is the usual layout. However, :file:`conf.py` can also live in another directory, the :term:`configuration directory`. Refer to the - :program:`sphinx-build man page ` for more information. + :doc:`sphinx-build man page ` for more information. .. |more| image:: /_static/more.png :align: middle From f0eeb5457c36025aea5e3fda55d7daa99deeec44 Mon Sep 17 00:00:00 2001 From: jfbu Date: Wed, 11 Jul 2018 18:33:30 +0200 Subject: [PATCH 25/35] LaTeX: fix indexing of terms containing @ character --- sphinx/writers/latex.py | 1 + 1 file changed, 1 insertion(+) diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index ee1a886e9..22463457f 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -1924,6 +1924,7 @@ class LaTeXTranslator(nodes.NodeVisitor): value = self.encode(value) value = value.replace(r'\{', r'{\sphinxleftcurlybrace}') value = value.replace(r'\}', r'{\sphinxrightcurlybrace}') + value = value.replace('@', '"@') return value if not node.get('inline', True): From 7166451dbdb2823a6c8c5943c225234a197b40b9 Mon Sep 17 00:00:00 2001 From: jfbu Date: Wed, 11 Jul 2018 18:34:40 +0200 Subject: [PATCH 26/35] LaTeX: fix indexing of terms containing ! character --- sphinx/writers/latex.py | 1 + 1 file changed, 1 insertion(+) diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 22463457f..49d0a849b 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -1925,6 +1925,7 @@ class LaTeXTranslator(nodes.NodeVisitor): value = value.replace(r'\{', r'{\sphinxleftcurlybrace}') value = value.replace(r'\}', r'{\sphinxrightcurlybrace}') value = value.replace('@', '"@') + value = value.replace('!', '"!') return value if not node.get('inline', True): From a68d06a1da848e58876e309f472880f171012094 Mon Sep 17 00:00:00 2001 From: jfbu Date: Wed, 11 Jul 2018 18:37:31 +0200 Subject: [PATCH 27/35] LaTeX: fix indexing of terms containing " character --- sphinx/writers/latex.py | 1 + 1 file changed, 1 insertion(+) diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 49d0a849b..5054d7943 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -1924,6 +1924,7 @@ class LaTeXTranslator(nodes.NodeVisitor): value = self.encode(value) value = value.replace(r'\{', r'{\sphinxleftcurlybrace}') value = value.replace(r'\}', r'{\sphinxrightcurlybrace}') + value = value.replace('"', '""') value = value.replace('@', '"@') value = value.replace('!', '"!') return value From 60b160431a4083a58a4d09051d5fba2275e2b712 Mon Sep 17 00:00:00 2001 From: jfbu Date: Fri, 6 Jul 2018 19:05:38 +0200 Subject: [PATCH 28/35] LaTeX: add hyperref support to general index as handled by xindy - achieve hyperlinked page numbers in general index, despite xindy's incompatibility with hyperref, - obtain compatibility of pdflatex with xindy for documents with Cyrillic scripts, - use xindy by default with xelatex/lualatex because any non-ascii character as first letter of an indexed term breaks PDF build if using makeindex with lualatex, and produces incoherent index with xelatex. This commit also switches off xindy logs (which were activated in parent commits) as they are voluminous and not of immediate use to Sphinx user. --- CHANGES | 14 ++- doc/usage/configuration.rst | 45 +++++----- sphinx/builders/latex/__init__.py | 113 +++++++++++++++++------- sphinx/templates/latex/latex.tex_t | 5 ++ sphinx/texinputs/Makefile_t | 9 +- sphinx/texinputs/cyrLICRutf8.xdy | 103 ++++++++++++++++++++++ sphinx/texinputs/latexmkrc_t | 4 +- sphinx/texinputs/python.ist | 2 +- sphinx/texinputs/python.xdy | 16 ---- sphinx/texinputs/sphinx.sty | 11 +-- sphinx/texinputs/sphinx.xdy | 133 +++++++++++++++++++++++++++++ sphinx/writers/latex.py | 9 +- 12 files changed, 381 insertions(+), 83 deletions(-) create mode 100644 sphinx/texinputs/cyrLICRutf8.xdy delete mode 100644 sphinx/texinputs/python.xdy create mode 100644 sphinx/texinputs/sphinx.xdy diff --git a/CHANGES b/CHANGES index d04da2e54..eacf8b9f4 100644 --- a/CHANGES +++ b/CHANGES @@ -4,6 +4,11 @@ Release 1.8.0 (in development) Dependencies ------------ +* LaTeX: :confval:`latex_use_xindy`, if ``True`` (default for + ``xelatex/lualatex``), instructs ``make latexpdf`` to use :program:`xindy` + for general index. Make sure your LaTeX distribution includes it. + (refs: #5134) + Incompatible changes -------------------- @@ -39,6 +44,10 @@ Incompatible changes Please use ``app.add_js_file()`` instead. * #5072: Save environment object also with only new documents * #5035: qthelp builder allows dashes in :confval:`qthelp_namespace` +* LaTeX: with lualatex or xelatex use by default :program:`xindy` as + UTF-8 able replacement of :program:`makeindex` (refs: #5134). After + upgrading Sphinx, please clean latex build repertory of existing project + before new build. Deprecated ---------- @@ -143,7 +152,8 @@ Features added for mathjax * #4362: latex: Don't overwrite .tex file if document not changed * #1431: latex: Add alphanumeric enumerated list support -* Add :confval:`latex_use_xindy` for UTF-8 savvy indexing +* Add :confval:`latex_use_xindy` for UTF-8 savvy indexing, defaults to ``True`` + if :confval:`latex_engine` is ``'xelatex'`` or ``'lualatex'``. Bugs fixed ---------- @@ -153,7 +163,7 @@ Bugs fixed * #4945: i18n: fix lang_COUNTRY not fallback correctly for IndexBuilder. Thanks to Shengjing Zhu. * #4983: productionlist directive generates invalid IDs for the tokens -* #5132: (lualatex) PDF build fails if indexed word starts with Unicode characters +* #5132: (lualatex) PDF build fails if indexed word starts with Unicode character Testing -------- diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 99b55f67e..8db606515 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -1874,28 +1874,35 @@ information. .. confval:: latex_use_xindy - If ``True`` (default ``False``), the PDF build from the LaTeX files - created by Sphinx will use :program:`xindy` (doc__) rather than - :program:`makeindex`. This means that utf-8 initials in indexed - words will be handled correctly, and entries will be ordered - according to the rules appropriate to the :confval:`language`. - Currently, this uses :program:`texindy` and only (most) European - languages with Latin scripts are supported. For usages requiring - direct use of ``xindy``, user will have to customize the files - :file:`Makefile` and :file:`latexmkrc` which are written to LaTeX - build repertory. This can be done via - :confval:`latex_additional_files` and customized such files located - in source repertory. + If ``True``, the PDF build from the LaTeX files created by Sphinx + will use :program:`xindy` (doc__) rather than :program:`makeindex` + for preparing the index of general terms (from :rst:dir:`index` + usage). This means that words with UTF-8 characters will get + ordered correctly for the :confval:`language`. __ http://xindy.sourceforge.net/ - This option is recommended in case of :confval:`latex_engine` set - to ``xelatex`` or ``lualatex`` (it is even mandatory for the latter - as the PDF build is broken if some indexed terms start with a - non-ascii character). It is without effect in case of - :confval:`platex` (Japanese documents). Even if - :confval:`latex_engine` is left to its default, the option is - recommended as soon as indexed terms use non-ascii characters. + - This option is ignored if :confval:`latex_engine` is ``'platex'`` + (Japanese documents) as :program:`mendex` is used in that case. + + - The default is ``True`` for ``'xelatex'`` or ``'lualatex'`` as + :program:`makeindex`, if any indexed term starts with a non-ascii + character, creates ``.ind`` file containing invalid bytes for + UTF-8 encoding. With ``'lualatex'`` this then breaks the PDF + build. Notice that :program:`xindy` supports most but not + all European languages. + + - The default is ``False`` for ``'pdflatex'`` but ``True`` is + recommended for non-English documents as soon as some indexed + terms use non-ascii characters from the language script. + Cyrillic scripts are (transparently) supported with + ``'pdflatex'`` thanks to a specific Sphinx-contributed ``xindy`` + style file :file:`cyrLICRutf8.xdy`. + + As :program:`xindy` does not support the same range of languages + as ``LaTeX/babel`` does, the default :program:`makeindex` for + ``'pdflatex'`` may be preferred in some circumstances, although + the index will be ill-formed probably. .. versionadded:: 1.8 diff --git a/sphinx/builders/latex/__init__.py b/sphinx/builders/latex/__init__.py index d90feb32b..c17ead5c2 100644 --- a/sphinx/builders/latex/__init__.py +++ b/sphinx/builders/latex/__init__.py @@ -44,30 +44,66 @@ if False: from sphinx.config import Config # NOQA -XINDY_LANGUAGES = { - # currently only Latin scripts here, for use with -L option of texindy - # code, name - 'hr': 'croatian', - 'cs': 'czech', - 'da': 'danish', - 'en': 'english', - 'et': 'estonian', - 'fi': 'finnish', - 'fr': 'french', - 'de': 'german-din', # there is also german-duden - 'hu': 'hungarian', - 'it': 'italian', - 'lv': 'latvian', - 'lt': 'lithuanian', - 'nb': 'norwegian', - 'pl': 'polish', - 'pt': 'portuguese', - 'sk': 'slovak-small', # xindy recognizes slovak-small and slovak-large - 'sl': 'slovenian', - 'es': 'spanish-modern', - 'sv': 'swedish', - 'tr': 'turkish' -} +XINDY_LANG_OPTIONS = { + # language codes from docutils.writers.latex2e.Babel + # ! xindy language names may differ from those in use by LaTeX/babel + # ! xindy does not support all Latin scripts as recognized by LaTeX/babel + # ! not all xindy-supported languages appear in Babel.language_codes + # cd /usr/local/texlive/2018/texmf-dist/xindy/modules/lang + # find . -name '*utf8.xdy' + # LATIN + 'sq': '-L albanian -C utf8 ', + 'hr': '-L croatian -C utf8 ', + 'cs': '-L czech -C utf8 ', + 'da': '-L danish -C utf8 ', + 'nl': '-L dutch -C ij-as-ij-utf8 ', + 'en': '-L english -C utf8 ', + 'eo': '-L esperanto -C utf8 ', + 'et': '-L estonian -C utf8 ', + 'fi': '-L finnish -C utf8 ', + 'fr': '-L french -C utf8 ', + 'de': '-L german -C din5007-utf8 ', + 'is': '-L icelandic -C utf8 ', + 'it': '-L italian -C utf8 ', + 'la': '-L latin -C utf8 ', + 'lv': '-L latvian -C utf8 ', + 'lt': '-L lithuanian -C utf8 ', + 'dsb': '-L lower-sorbian -C utf8 ', + 'ds': '-L lower-sorbian -C utf8 ', # trick, no conflict + 'nb': '-L norwegian -C utf8 ', + 'no': '-L norwegian -C utf8 ', # and what about nynorsk? + 'pl': '-L polish -C utf8 ', + 'pt': '-L portuguese -C utf8 ', + 'ro': '-L romanian -C utf8 ', + 'sk': '-L slovak -C small-utf8 ', # there is also slovak-large + 'sl': '-L slovenian -C utf8 ', + 'es': '-L spanish -C modern-utf8 ', # there is also spanish-traditional + 'sv': '-L swedish -C utf8 ', + 'tr': '-L turkish -C utf8 ', + 'hsb': '-L upper-sorbian -C utf8 ', + 'hs': '-L upper-sorbian -C utf8 ', # trick, no conflict + 'vi': '-L vietnamese -C utf8 ', + # CYRILLIC + # for usage with pdflatex, needs also cyrLICRutf8.xdy module + 'be': '-L belarusian -C utf8 ', + 'bg': '-L bulgarian -C utf8 ', + 'mk': '-L macedonian -C utf8 ', + 'mn': '-L mongolian -C cyrillic-utf8 ', + 'ru': '-L russian -C utf8 ', + 'sr': '-L serbian -C utf8 ', + 'sh-cyrl': '-L serbian -C utf8 ', + 'sh': '-L serbian -C utf8 ', # trick, no conflict + 'uk': '-L ukrainian -C utf8 ', + # GREEK + # can work only with xelatex/lualatex, not supported by texindy+pdflatex + 'el': '-L greek -C utf8 ', + # FIXME, not compatible with [:2] slice but does Sphinx support Greek ? + 'el-polyton': '-L greek -C polytonic-utf8 ', +} # type: Dict[unicode, unicode] + +XINDY_CYRILLIC_SCRIPTS = [ + 'be', 'bg', 'mk', 'mn', 'ru', 'sr', 'sh', 'uk', +] # type: List[unicode] logger = logging.getLogger(__name__) @@ -257,14 +293,23 @@ class LaTeXBuilder(Builder): self.copy_image_files() # copy TeX support files from texinputs + # configure usage of xindy (impacts Makefile and latexmkrc) + # FIXME: convert this rather to a confval with suitable default + # according to language ? but would require extra documentation if self.config.language: - xindy_lang = \ - XINDY_LANGUAGES.get(self.config.language[:2], 'general') + xindy_lang_option = \ + XINDY_LANG_OPTIONS.get(self.config.language[:2], + '-L general -C utf8 ') + xindy_cyrillic = self.config.language[:2] in XINDY_CYRILLIC_SCRIPTS else: - xindy_lang = 'english' - context = {'latex_engine': self.config.latex_engine, - 'latex_use_xindy': self.config.latex_use_xindy, - 'xindy_lang': xindy_lang} + xindy_lang_option = '-L english -C utf8 ' + xindy_cyrillic = False + context = { + 'latex_engine': self.config.latex_engine, + 'xindy_use': self.config.latex_use_xindy, + 'xindy_lang_option': xindy_lang_option, + 'xindy_cyrillic': xindy_cyrillic, + } logger.info(bold(__('copying TeX support files...'))) staticdirname = path.join(package_dir, 'texinputs') for filename in os.listdir(staticdirname): @@ -349,6 +394,12 @@ def default_latex_docclass(config): return {} +def default_latex_use_xindy(config): + # type: (Config) -> bool + """ Better default latex_use_xindy settings for specific engines. """ + return config.latex_engine in {'xelatex', 'lualatex'} + + def setup(app): # type: (Sphinx) -> Dict[unicode, Any] app.add_builder(LaTeXBuilder) @@ -366,7 +417,7 @@ def setup(app): app.add_config_value('latex_logo', None, None, string_classes) app.add_config_value('latex_appendices', [], None) app.add_config_value('latex_use_latex_multicolumn', False, None) - app.add_config_value('latex_use_xindy', False, None) + app.add_config_value('latex_use_xindy', default_latex_use_xindy, None) app.add_config_value('latex_toplevel_sectioning', None, None, ENUM(None, 'part', 'chapter', 'section')) app.add_config_value('latex_domain_indices', True, None, [list]) diff --git a/sphinx/templates/latex/latex.tex_t b/sphinx/templates/latex/latex.tex_t index 5a158444c..d219f8525 100644 --- a/sphinx/templates/latex/latex.tex_t +++ b/sphinx/templates/latex/latex.tex_t @@ -13,6 +13,11 @@ \ifdefined\pdfpxdimen \let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen \fi \sphinxpxdimen=<%= pxunit %>\relax +<% if use_xindy -%> +%% turn off hyperref patch of \index as sphinx.xdy xindy module takes care of +%% suitable \hyperpage mark-up, working around hyperref-xindy incompatibility +\PassOptionsToPackage{hyperindex=false}{hyperref} +<% endif -%> <%= passoptionstopackages %> \PassOptionsToPackage{warn}{textcomp} <%= inputenc %> diff --git a/sphinx/texinputs/Makefile_t b/sphinx/texinputs/Makefile_t index 82ea29de1..1ce4b1324 100644 --- a/sphinx/texinputs/Makefile_t +++ b/sphinx/texinputs/Makefile_t @@ -22,10 +22,13 @@ export LATEXOPTS = # or on command line for faster builds. {% endif -%} LATEXMKOPTS = -{% if latex_use_xindy -%} -export XINDYOPTS = -L {{ xindy_lang }} -C utf8 -M python.xdy +{% if xindy_use -%} +export XINDYOPTS = {{ xindy_lang_option }} -M sphinx.xdy +{% if latex_engine == 'pdflatex' and xindy_cyrillic -%} +XINDYOPTS += -M cyrLICRutf8.xdy +{% endif -%} {% if latex_engine == 'xelatex' or latex_engine == 'lualatex' -%} -export XINDYOPTS += -I xelatex +XINDYOPTS += -I xelatex {% endif -%} {% endif -%} # format: pdf or dvi (used only by archive targets) diff --git a/sphinx/texinputs/cyrLICRutf8.xdy b/sphinx/texinputs/cyrLICRutf8.xdy new file mode 100644 index 000000000..86d8cd87b --- /dev/null +++ b/sphinx/texinputs/cyrLICRutf8.xdy @@ -0,0 +1,103 @@ +;; -*- coding: utf-8; mode: Lisp; -*- +;; style file for xindy +;; filename: cyrLICRutf8.xdy +;; description: style file for xindy which maps back LaTeX Internal +;; Character Representation of Cyrillic to utf-8 +;; usage: for use with pdflatex produced .idx files. +;; This module must be loaded after the rule for suppressing space +;; characters has been executed, hence after module sphinx.xdy. +;; Contributed by the Sphinx team, July 2018. +(merge-rule "\IeC{\'\CYRG}" "Ѓ" :string) +(merge-rule "\IeC{\'\CYRK}" "Ќ" :string) +(merge-rule "\IeC{\'\cyrg}" "ѓ" :string) +(merge-rule "\IeC{\'\cyrk}" "ќ" :string) +(merge-rule "\IeC{\CYRA}" "А" :string) +(merge-rule "\IeC{\CYRB}" "Б" :string) +(merge-rule "\IeC{\CYRC}" "Ц" :string) +(merge-rule "\IeC{\CYRCH}" "Ч" :string) +(merge-rule "\IeC{\CYRD}" "Д" :string) +(merge-rule "\IeC{\CYRDJE}" "Ђ" :string) +(merge-rule "\IeC{\CYRDZE}" "Ѕ" :string) +(merge-rule "\IeC{\CYRDZHE}" "Џ" :string) +(merge-rule "\IeC{\CYRE}" "Е" :string) +(merge-rule "\IeC{\CYREREV}" "Э" :string) +(merge-rule "\IeC{\CYRERY}" "Ы" :string) +(merge-rule "\IeC{\CYRF}" "Ф" :string) +(merge-rule "\IeC{\CYRG}" "Г" :string) +(merge-rule "\IeC{\CYRGUP}" "Ґ" :string) +(merge-rule "\IeC{\CYRH}" "Х" :string) +(merge-rule "\IeC{\CYRHRDSN}" "Ъ" :string) +(merge-rule "\IeC{\CYRI}" "И" :string) +(merge-rule "\IeC{\CYRIE}" "Є" :string) +(merge-rule "\IeC{\CYRII}" "І" :string) +(merge-rule "\IeC{\CYRISHRT}" "Й" :string) +(merge-rule "\IeC{\CYRJE}" "Ј" :string) +(merge-rule "\IeC{\CYRK}" "К" :string) +(merge-rule "\IeC{\CYRL}" "Л" :string) +(merge-rule "\IeC{\CYRLJE}" "Љ" :string) +(merge-rule "\IeC{\CYRM}" "М" :string) +(merge-rule "\IeC{\CYRN}" "Н" :string) +(merge-rule "\IeC{\CYRNJE}" "Њ" :string) +(merge-rule "\IeC{\CYRO}" "О" :string) +(merge-rule "\IeC{\CYRP}" "П" :string) +(merge-rule "\IeC{\CYRR}" "Р" :string) +(merge-rule "\IeC{\CYRS}" "С" :string) +(merge-rule "\IeC{\CYRSFTSN}" "Ь" :string) +(merge-rule "\IeC{\CYRSH}" "Ш" :string) +(merge-rule "\IeC{\CYRSHCH}" "Щ" :string) +(merge-rule "\IeC{\CYRT}" "Т" :string) +(merge-rule "\IeC{\CYRTSHE}" "Ћ" :string) +(merge-rule "\IeC{\CYRU}" "У" :string) +(merge-rule "\IeC{\CYRUSHRT}" "Ў" :string) +(merge-rule "\IeC{\CYRV}" "В" :string) +(merge-rule "\IeC{\CYRYA}" "Я" :string) +(merge-rule "\IeC{\CYRYI}" "Ї" :string) +(merge-rule "\IeC{\CYRYO}" "Ё" :string) +(merge-rule "\IeC{\CYRYU}" "Ю" :string) +(merge-rule "\IeC{\CYRZ}" "З" :string) +(merge-rule "\IeC{\CYRZH}" "Ж" :string) +(merge-rule "\IeC{\cyra}" "а" :string) +(merge-rule "\IeC{\cyrb}" "б" :string) +(merge-rule "\IeC{\cyrc}" "ц" :string) +(merge-rule "\IeC{\cyrch}" "ч" :string) +(merge-rule "\IeC{\cyrd}" "д" :string) +(merge-rule "\IeC{\cyrdje}" "ђ" :string) +(merge-rule "\IeC{\cyrdze}" "ѕ" :string) +(merge-rule "\IeC{\cyrdzhe}" "џ" :string) +(merge-rule "\IeC{\cyre}" "е" :string) +(merge-rule "\IeC{\cyrerev}" "э" :string) +(merge-rule "\IeC{\cyrery}" "ы" :string) +(merge-rule "\IeC{\cyrf}" "ф" :string) +(merge-rule "\IeC{\cyrg}" "г" :string) +(merge-rule "\IeC{\cyrgup}" "ґ" :string) +(merge-rule "\IeC{\cyrh}" "х" :string) +(merge-rule "\IeC{\cyrhrdsn}" "ъ" :string) +(merge-rule "\IeC{\cyri}" "и" :string) +(merge-rule "\IeC{\cyrie}" "є" :string) +(merge-rule "\IeC{\cyrii}" "і" :string) +(merge-rule "\IeC{\cyrishrt}" "й" :string) +(merge-rule "\IeC{\cyrje}" "ј" :string) +(merge-rule "\IeC{\cyrk}" "к" :string) +(merge-rule "\IeC{\cyrl}" "л" :string) +(merge-rule "\IeC{\cyrlje}" "љ" :string) +(merge-rule "\IeC{\cyrm}" "м" :string) +(merge-rule "\IeC{\cyrn}" "н" :string) +(merge-rule "\IeC{\cyrnje}" "њ" :string) +(merge-rule "\IeC{\cyro}" "о" :string) +(merge-rule "\IeC{\cyrp}" "п" :string) +(merge-rule "\IeC{\cyrr}" "р" :string) +(merge-rule "\IeC{\cyrs}" "с" :string) +(merge-rule "\IeC{\cyrsftsn}" "ь" :string) +(merge-rule "\IeC{\cyrsh}" "ш" :string) +(merge-rule "\IeC{\cyrshch}" "щ" :string) +(merge-rule "\IeC{\cyrt}" "т" :string) +(merge-rule "\IeC{\cyrtshe}" "ћ" :string) +(merge-rule "\IeC{\cyru}" "у" :string) +(merge-rule "\IeC{\cyrushrt}" "ў" :string) +(merge-rule "\IeC{\cyrv}" "в" :string) +(merge-rule "\IeC{\cyrya}" "я" :string) +(merge-rule "\IeC{\cyryi}" "ї" :string) +(merge-rule "\IeC{\cyryo}" "ё" :string) +(merge-rule "\IeC{\cyryu}" "ю" :string) +(merge-rule "\IeC{\cyrz}" "з" :string) +(merge-rule "\IeC{\cyrzh}" "ж" :string) diff --git a/sphinx/texinputs/latexmkrc_t b/sphinx/texinputs/latexmkrc_t index c0965ffe3..d52681fbd 100644 --- a/sphinx/texinputs/latexmkrc_t +++ b/sphinx/texinputs/latexmkrc_t @@ -10,8 +10,8 @@ $pdflatex = 'xelatex ' . $ENV{'LATEXOPTS'} . ' %O %S'; {% endif -%} $lualatex = 'lualatex ' . $ENV{'LATEXOPTS'} . ' %O %S'; $xelatex = 'xelatex --no-pdf ' . $ENV{'LATEXOPTS'} . ' %O %S'; -{% if latex_use_xindy -%} -$makeindex = 'texindy ' . $ENV{'XINDYOPTS'} . ' -t %B.ilg %O -o %D %S'; +{% if xindy_use -%} +$makeindex = 'xindy ' . $ENV{'XINDYOPTS'} . ' %O -o %D %S'; {% else -%} $makeindex = 'makeindex -s python.ist %O -o %D %S'; {% endif -%} diff --git a/sphinx/texinputs/python.ist b/sphinx/texinputs/python.ist index f560754c0..203fde319 100644 --- a/sphinx/texinputs/python.ist +++ b/sphinx/texinputs/python.ist @@ -3,7 +3,7 @@ headings_flag 1 heading_prefix " \\bigletter " preamble "\\begin{sphinxtheindex} -\\let\\bigletter\\sphinxstyleindexletterhead +\\let\\bigletter\\sphinxstyleindexlettergroup " diff --git a/sphinx/texinputs/python.xdy b/sphinx/texinputs/python.xdy deleted file mode 100644 index d84b9668b..000000000 --- a/sphinx/texinputs/python.xdy +++ /dev/null @@ -1,16 +0,0 @@ -(markup-index :open "\begin{sphinxtheindex} -\let\lettergroup\sphinxstyleindexletterhead -\let\lettergroupDefault\sphinxstyleindexxindygroupheadsymbols - -" - :close " - -\end{sphinxtheindex} -" - :tree) - -;; End - -;; Local Variables: -;; mode: lisp -;; End: diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index d8ee2ed65..6ee1acb90 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -470,8 +470,8 @@ {\newenvironment{sphinxtheindex}{\begin{theindex}}{\end{theindex}}}% {}% else clause of \ltx@ifundefined -% for usage with xindy string is internationalized in document preamble -\newcommand*{\sphinxsymbolsandnumbersname}{Symbols and Numbers} +% for usage with xindy: this string gets internationalized in preamble +\newcommand*{\sphinxnonalphabeticalgroupname}{} %% COLOR (general) % @@ -1596,9 +1596,10 @@ \def\sphinxstyleindexentry #1{\texttt{#1}} \def\sphinxstyleindexextra #1{ \emph{(#1)}} \def\sphinxstyleindexpageref #1{, \pageref{#1}} -\def\sphinxstyleindexletterhead #1{{\Large\sffamily#1}\nopagebreak\vspace{1mm}} -\def\sphinxstyleindexxindygroupheadsymbols - {{\Large\sffamily\sphinxsymbolsandnumbersname}\nopagebreak\vspace{1mm}} +\def\sphinxstyleindexlettergroup #1% + {{\Large\sffamily#1}\nopagebreak\vspace{1mm}} +\def\sphinxstyleindexlettergroupDefault #1% + {{\Large\sffamily\sphinxnonalphabeticalgroupname}\nopagebreak\vspace{1mm}} \protected\def\sphinxstyletopictitle #1{\textbf{#1}\par\medskip} \let\sphinxstylesidebartitle\sphinxstyletopictitle \protected\def\sphinxstyleothertitle #1{\textbf{#1}} diff --git a/sphinx/texinputs/sphinx.xdy b/sphinx/texinputs/sphinx.xdy new file mode 100644 index 000000000..d9f99dc2a --- /dev/null +++ b/sphinx/texinputs/sphinx.xdy @@ -0,0 +1,133 @@ +;;; -*- mode: lisp; coding: utf-8; -*- + +;; Unfortunately xindy is out-of-the-box hyperref-incompatible. This +;; configuration is a workaround, which requires to pass option +;; hyperindex=false to hyperref. +;; textit and emph not currently used by Sphinx LaTeX writer. +(define-attributes (("textbf" "textit" "emph" "default"))) +(markup-locref :open "\textbf{\hyperpage{" :close "}}" :attr "textbf") +(markup-locref :open "\textit{\hyperpage{" :close "}}" :attr "textit") +(markup-locref :open "\emph{\hyperpage{" :close "}}" :attr "emph") +(markup-locref :open "\hyperpage{" :close "}" :attr "default") + +(require "numeric-sort.xdy") + +;; xindy base module latex.xdy loads tex.xdy and the latter instructs +;; xindy to ignore **all** TeX macros in .idx entries, except those +;; explicitely described in merge rule. But when after applying all +;; merge rules an empty string results, xindy raises an error: + +;; ERROR: CHAR: index 0 should be less than the length of the string + +;; For example when using pdflatex with utf-8 characters the index +;; file will contain \IeC macros and they will get ignored except if +;; suitable merge rules are loaded early. The texindy script coming +;; with xindy provides this, but only for Latin scripts. The texindy +;; man page says to use rather xelatex or lualatex in case of Cyrillic +;; scripts. + +;; Sphinx contributes cyrLICRutf8.xdy to provide support for Cyrillic +;; scripts for the pdflatex engine. + +;; Another issue caused by xindy ignoring all TeX macros except those +;; explicitely declared reveals itself when attempting to index ">>>", +;; as the ">" is converted to "\textgreater{}" by Sphinx's LaTeX +;; escaping. + +;; To fix this, Sphinx does **not** use texindy, and does not even +;; load the xindy latex.xdy base module. + +;(require "latex.xdy") + +;; Rather it incorporates some suitable extracts from latex.xdy and +;; tex.xdy with additional Sphinx contributed rules. + +;;;;;;;; extracts from tex.xdy (discarding most original comments): + +;;; +;;; TeX conventions +;;; + +;; Discard leading and trailing white space. Collapse multiple white +;; space characters to blank. + +(merge-rule "^ +" "" :eregexp) +(merge-rule " +$" "" :eregexp) +(merge-rule " +" " " :eregexp) + +;; Handle TeX markup + +(merge-rule "\\([{}$%&#])" "\1" :eregexp) + +;;;;;;;; end of extracts from xindy's tex.xdy + +;;;;;;;; extracts from latex.xdy: + +;; Standard location classes: arabic and roman numbers, and alphabets. + +(define-location-class "arabic-page-numbers" ("arabic-numbers")) +(define-location-class "roman-page-numbers" ("roman-numbers-lowercase")) +(define-location-class "Roman-page-numbers" ("roman-numbers-uppercase")) +(define-location-class "alpha-page-numbers" ("alpha")) +(define-location-class "Alpha-page-numbers" ("ALPHA")) + +;; Output Markup + +(markup-letter-group-list :sep "~n~n \indexspace~n") + +(markup-indexentry :open "~n \item " :depth 0) +(markup-indexentry :open "~n \subitem " :depth 1) +(markup-indexentry :open "~n \subsubitem " :depth 2) + +(markup-locclass-list :open ", " :sep ", ") +(markup-locref-list :sep ", ") + +;;;;;;;; end of extracts from latex.xdy + +;; Sphinx additions, cf sphinx.util.texescape for rationale +;; +;; blanks are already ignored from above merge-rules, so no space +;; character after TeX control words, despite the fact that they will +;; be present in .idx file. + +(merge-rule "\\sphinxleftcurlybrace\{\}" "{") +(merge-rule "\\sphinxrightcurlybrace\{\}" "}") +(merge-rule "\\_" "_") +(merge-rule "\{\[\}" "[") +(merge-rule "\{\]\}" "]") +(merge-rule "\{\}`" "`") +(merge-rule "\\textbackslash\{\}" "\\") +(merge-rule "\\textasciitilde\{\}" "~~") +(merge-rule "\\textless\{\}" "<") +(merge-rule "\\textgreater\{\}" ">") +(merge-rule "\\textasciicircum\{\}" "^") +(merge-rule "\\P\{\}" "¶") +(merge-rule "\\S\{\}" "§") +(merge-rule "\\texteuro\{\}" "€") +(merge-rule "\\\(\\infty\\\)" "∞") +(merge-rule "\\\(\\pm\\\)" "±") +(merge-rule "\\\(\\rightarrow\\\)" "→") +(merge-rule "\\\(\\checkmark\\\)" "✓") +(merge-rule "\\textendash\{\}" "–") +(merge-rule "\\textbar\{\}" "|") + +;; This xindy module provides some basic support for "see" +(require "makeindex.xdy") + +;; This creates one-letter headings and works fine with utf-8 letters. +;; For Cyrillic and pdflatex necessitates cyrLICRutf8.xdy to be loaded too. +(require "latin-lettergroups.xdy") + +;; currently we don't (know how to easily) separate "Numbers" from +;; "Symbols" with xindy as is the case with makeindex. +(markup-index :open "\begin{sphinxtheindex} +\let\lettergroup\sphinxstyleindexlettergroup +\let\lettergroupDefault\sphinxstyleindexlettergroupDefault + +" + :close " + +\end{sphinxtheindex} +" + :tree) + diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 5054d7943..3e170baa0 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -497,6 +497,7 @@ class LaTeXTranslator(nodes.NodeVisitor): 'release': self.encode(builder.config.release), 'author': document.settings.author, # treat as a raw LaTeX code 'indexname': _('Index'), + 'use_xindy': builder.config.latex_use_xindy, }) if not self.elements['releasename'] and self.elements['release']: self.elements.update({ @@ -675,7 +676,7 @@ class LaTeXTranslator(nodes.NodeVisitor): '\\literalblockcontinuesname', self.encode(_('continues on next page')) ) + self.babel_renewcommand( - '\\sphinxsymbolsandnumbersname', self.encode(_('Symbols and Numbers')) + '\\sphinxnonalphabeticalgroupname', self.encode(_('Non-alphabetical')) ) ) self.elements['pageautorefname'] = \ @@ -859,7 +860,7 @@ class LaTeXTranslator(nodes.NodeVisitor): def generate(content, collapsed): # type: (List[Tuple[unicode, List[Tuple[unicode, unicode, unicode, unicode, unicode]]]], bool) -> None # NOQA ret.append('\\begin{sphinxtheindex}\n') - ret.append('\\let\\bigletter\\sphinxstyleindexletterhead\n') + ret.append('\\let\\bigletter\\sphinxstyleindexlettergroup\n') for i, (letter, entries) in enumerate(content): if i > 0: ret.append('\\indexspace\n') @@ -1922,8 +1923,8 @@ class LaTeXTranslator(nodes.NodeVisitor): # type: (nodes.Node, Pattern) -> None def escape(value): value = self.encode(value) - value = value.replace(r'\{', r'{\sphinxleftcurlybrace}') - value = value.replace(r'\}', r'{\sphinxrightcurlybrace}') + value = value.replace(r'\{', r'\sphinxleftcurlybrace{}') + value = value.replace(r'\}', r'\sphinxrightcurlybrace{}') value = value.replace('"', '""') value = value.replace('@', '"@') value = value.replace('!', '"!') From 7b44adb0485a5dc7d1f8bfca10f73b90f0fb2eac Mon Sep 17 00:00:00 2001 From: jfbu Date: Fri, 13 Jul 2018 14:37:39 +0200 Subject: [PATCH 29/35] Use xindy for Sphinx's own PDF documentation Makeindex gathered under heading "Symbols" all command line options, this seems less satisfactory than index produced by xindy. --- doc/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/conf.py b/doc/conf.py index 732c4d4a0..724d355d0 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -72,6 +72,7 @@ latex_elements = { ''', } latex_show_urls = 'footnote' +latex_use_xindy = True autodoc_member_order = 'groupwise' todo_include_todos = True From e34fd5b503a72474548e853f44021a80ff3b729f Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 15 Jul 2018 14:07:00 +0900 Subject: [PATCH 30/35] Fix mypy violations --- sphinx/config.py | 2 +- sphinx/ext/autosummary/generate.py | 2 +- sphinx/locale/__init__.py | 16 ++++++++-------- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/sphinx/config.py b/sphinx/config.py index 1f80ab366..c938c834e 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -122,7 +122,7 @@ class Config(object): rst_epilog = (None, 'env', string_classes), rst_prolog = (None, 'env', string_classes), trim_doctest_flags = (True, 'env'), - primary_domain = ('py', 'env', [NoneType]), + primary_domain = ('py', 'env', [NoneType]), # type: ignore needs_sphinx = (None, None, string_classes), needs_extensions = ({}, None), manpages_url = (None, 'env'), diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py index 2818ab3c7..0c83a4e25 100644 --- a/sphinx/ext/autosummary/generate.py +++ b/sphinx/ext/autosummary/generate.py @@ -120,7 +120,7 @@ def generate_autosummary_docs(sources, output_dir=None, suffix='.rst', else: if template_dir: template_dirs.insert(0, template_dir) - template_loader = FileSystemLoader(template_dirs) # type: ignore + template_loader = FileSystemLoader(template_dirs) template_env = SandboxedEnvironment(loader=template_loader) template_env.filters['underline'] = _underline diff --git a/sphinx/locale/__init__.py b/sphinx/locale/__init__.py index e148f2c12..ae86686e8 100644 --- a/sphinx/locale/__init__.py +++ b/sphinx/locale/__init__.py @@ -58,7 +58,7 @@ class _TranslationProxy(UserString, object): # replace function from UserString; it instantiates a self.__class__ # for the encoding result - def encode(self, encoding=None, errors=None): + def encode(self, encoding=None, errors=None): # type: ignore # type: (unicode, unicode) -> str if encoding: if errors: @@ -82,7 +82,7 @@ class _TranslationProxy(UserString, object): return dir(text_type) def __iter__(self): - # type: () -> Iterator[unicode] + # type: () -> Iterator return iter(self.data) def __len__(self): @@ -97,15 +97,15 @@ class _TranslationProxy(UserString, object): # type: () -> unicode return text_type(self.data) - def __add__(self, other): + def __add__(self, other): # type: ignore # type: (unicode) -> unicode return self.data + other - def __radd__(self, other): + def __radd__(self, other): # type: ignore # type: (unicode) -> unicode return other + self.data - def __mod__(self, other): + def __mod__(self, other): # type: ignore # type: (unicode) -> unicode return self.data % other @@ -113,11 +113,11 @@ class _TranslationProxy(UserString, object): # type: (unicode) -> unicode return other % self.data - def __mul__(self, other): + def __mul__(self, other): # type: ignore # type: (Any) -> unicode return self.data * other - def __rmul__(self, other): + def __rmul__(self, other): # type: ignore # type: (Any) -> unicode return other * self.data @@ -159,7 +159,7 @@ class _TranslationProxy(UserString, object): # type: (Tuple[Callable, Tuple[unicode]]) -> None self._func, self._args = tup - def __getitem__(self, key): + def __getitem__(self, key): # type: ignore # type: (Any) -> unicode return self.data[key] From a54abd760c2531ffaa205b4502ac56bacf0e2920 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 15 Jul 2018 14:55:22 +0900 Subject: [PATCH 31/35] Fix mypy violations --- sphinx/testing/path.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/testing/path.py b/sphinx/testing/path.py index 209046246..585933499 100644 --- a/sphinx/testing/path.py +++ b/sphinx/testing/path.py @@ -223,7 +223,7 @@ class path(text_type): """ Joins the path with the argument given and returns the result. """ - return self.__class__(os.path.join(self, *map(self.__class__, args))) # type: ignore # NOQA + return self.__class__(os.path.join(self, *map(self.__class__, args))) def listdir(self): # type: () -> List[unicode] From 2e4db4854fcb244d0dd813f2b4b5a7a6e64c2262 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 15 Jul 2018 15:15:57 +0900 Subject: [PATCH 32/35] Fix flake8 violation --- sphinx/ext/autosummary/__init__.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index dcff43b56..7c740be31 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -78,7 +78,9 @@ from sphinx.ext.autodoc.importer import import_module from sphinx.locale import __ from sphinx.pycode import ModuleAnalyzer, PycodeError from sphinx.util import import_object, rst, logging -from sphinx.util.docutils import NullReporter, SphinxDirective, new_document, switch_source_input +from sphinx.util.docutils import ( + NullReporter, SphinxDirective, new_document, switch_source_input +) if False: # For type annotation From 2d7fe69362863825c54f866ec86e29b1d34aa1d9 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 15 Jul 2018 15:44:31 +0900 Subject: [PATCH 33/35] Fix #5143: autodoc: crashed on inspecting dict like object --- CHANGES | 2 ++ sphinx/util/inspect.py | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index d5a67ac27..e67684297 100644 --- a/CHANGES +++ b/CHANGES @@ -40,6 +40,8 @@ Bugs fixed * #5146: autosummary: warning is emitted when the first line of docstring ends with literal notation * autosummary: warnings of autosummary indicates wrong location (refs: #5146) +* #5143: autodoc: crashed on inspecting dict like object which does not support + sorting Testing -------- diff --git a/sphinx/util/inspect.py b/sphinx/util/inspect.py index fbef01341..0abd537e3 100644 --- a/sphinx/util/inspect.py +++ b/sphinx/util/inspect.py @@ -241,7 +241,7 @@ def object_description(object): if isinstance(object, dict): try: sorted_keys = sorted(object) - except TypeError: + except Exception: pass # Cannot sort dict keys, fall back to generic repr else: items = ("%r: %r" % (key, object[key]) for key in sorted_keys) From 3c3dca8203f84285d1017ffa92336b69391dd42c Mon Sep 17 00:00:00 2001 From: jfbu Date: Mon, 16 Jul 2018 01:06:27 +0200 Subject: [PATCH 34/35] Fix failed test (changed \sphinxleftcurlybrace) --- tests/test_build_latex.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_build_latex.py b/tests/test_build_latex.py index 2573a74da..8075bf8d0 100644 --- a/tests/test_build_latex.py +++ b/tests/test_build_latex.py @@ -1201,7 +1201,7 @@ def test_latex_index(app, status, warning): result = (app.outdir / 'Python.tex').text(encoding='utf8') assert 'A \\index{famous}famous \\index{equation}equation:\n' in result assert '\n\\index{Einstein}\\index{relativity}\\ignorespaces \nand' in result - assert '\n\\index{main {\\sphinxleftcurlybrace}}\\ignorespaces ' in result + assert '\n\\index{main \\sphinxleftcurlybrace{}}\\ignorespaces ' in result @pytest.mark.sphinx('latex', testroot='latex-equations') From fb45af7cde8d2707bac0f85c31cb3567e51d6009 Mon Sep 17 00:00:00 2001 From: jfbu Date: Mon, 16 Jul 2018 01:57:40 +0200 Subject: [PATCH 35/35] Rename macros for conformity with choices done at PR #5134 --- sphinx/texinputs/python.ist | 2 +- sphinx/texinputs/sphinx.sty | 6 +++--- sphinx/writers/latex.py | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/sphinx/texinputs/python.ist b/sphinx/texinputs/python.ist index acb71712e..7a1c06fbd 100644 --- a/sphinx/texinputs/python.ist +++ b/sphinx/texinputs/python.ist @@ -3,7 +3,7 @@ headings_flag 1 heading_prefix " \\bigletter " preamble "\\begin{sphinxtheindex} -\\let\\bigletter\\sphinxstyleindexletterhead +\\let\\bigletter\\sphinxstyleindexlettergroup " diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index ee7698a46..3333fcc62 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -471,8 +471,8 @@ {}% else clause of \ltx@ifundefined % redefined in preamble, headings for makeindex produced index -\newcommand*{\sphinxsymbolsname}{Symbols} -\newcommand*{\sphinxnumbersname}{Numbers} +\newcommand*{\sphinxsymbolsname}{} +\newcommand*{\sphinxnumbersname}{} %% COLOR (general) % @@ -1598,7 +1598,7 @@ \def\sphinxstyleindexentry #1{\texttt{#1}} \def\sphinxstyleindexextra #1{ \emph{(#1)}} \def\sphinxstyleindexpageref #1{, \pageref{#1}} -\def\sphinxstyleindexletterhead #1{{\Large\sffamily#1}\nopagebreak\vspace{1mm}} +\def\sphinxstyleindexlettergroup #1{{\Large\sffamily#1}\nopagebreak\vspace{1mm}} \protected\def\sphinxstyletopictitle #1{\textbf{#1}\par\medskip} \let\sphinxstylesidebartitle\sphinxstyletopictitle \protected\def\sphinxstyleothertitle #1{\textbf{#1}} diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 3b50751c8..3b5a4f3e8 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -862,7 +862,7 @@ class LaTeXTranslator(nodes.NodeVisitor): def generate(content, collapsed): # type: (List[Tuple[unicode, List[Tuple[unicode, unicode, unicode, unicode, unicode]]]], bool) -> None # NOQA ret.append('\\begin{sphinxtheindex}\n') - ret.append('\\let\\bigletter\\sphinxstyleindexletterhead\n') + ret.append('\\let\\bigletter\\sphinxstyleindexlettergroup\n') for i, (letter, entries) in enumerate(content): if i > 0: ret.append('\\indexspace\n')