Merge branch 'master' into refactor_singlehtml

CHANGES

@@ -58,6 +58,10 @@ Deprecated
 
 * Support for evaluating Python 2 syntax is deprecated. This includes
   configuration files which should be converted to Python 3.
+* The arguments of ``EpubBuilder.build_mimetype()``,
+  ``EpubBuilder.build_container()``, ``EpubBuilder.bulid_content()``,
+  ``EpubBuilder.build_toc()`` and ``EpubBuilder.build_epub()``
+* The arguments of ``Epub3Builder.build_navigation_doc()``
 * The ``encoding`` argument of ``autodoc.Documenter.get_doc()``,
   ``autodoc.DocstringSignatureMixin.get_doc()``,
   ``autodoc.DocstringSignatureMixin._find_signature()``, and
@@ -71,6 +75,7 @@ Deprecated
   ``IndexBuilder.feed()`` method is deprecated.
 * ``sphinx.addnodes.abbreviation``
 * ``sphinx.application.Sphinx._setting_up_extension``
+* ``sphinx.builders.epub3.Epub3Builder.validate_config_value()``
 * ``sphinx.builders.html.SingleFileHTMLBuilder``
 * ``sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()``
 * ``sphinx.cmd.quickstart.term_decode()``
@@ -147,6 +152,8 @@ Features added
   (``added``, ``changed`` and ``deprecated``, respectively) in addition to the
   generic ``versionmodified`` class.
 * #5841: apidoc: Add --extensions option to sphinx-apidoc
+* #4981: C++, added an alias directive for inserting lists of declarations,
+  that references existing declarations (e.g., for making a synopsis).
 
 Bugs fixed
 ----------

doc/contents.rst

@@ -7,6 +7,8 @@ Sphinx documentation contents
 .. toctree::
    :maxdepth: 2
 
+   intro
+
    usage/installation
    usage/quickstart
    usage/restructuredtext/index
@@ -19,7 +21,6 @@ Sphinx documentation contents
    usage/advanced/setuptools
    usage/advanced/websupport/index
 
-   intro
    man/index
    theming
    templating

doc/extdev/index.rst

@@ -242,6 +242,18 @@ The following is a list of deprecated interfaces.
      - 4.0
      - N/A
 
+   * - arguments of ``EpubBuilder.build_mimetype()``,
+       ``EpubBuilder.build_container()``, ``EpubBuilder.build_content()``,
+       ``EpubBuilder.build_toc()`` and ``EpubBuilder.build_epub()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - arguments of ``Epub3Builder.build_navigation_doc()``
+     - 2.0
+     - 4.0
+     - N/A
+
    * - ``nodetype`` argument of
        ``sphinx.search.WordCollector.is_meta_keywords()``
      - 2.0
@@ -263,6 +275,11 @@ The following is a list of deprecated interfaces.
      - 4.0
      - ``docutils.nodes.abbreviation``
 
+   * - ``sphinx.builders.epub3.Epub3Builder.validate_config_value()``
+     - 2.0
+     - 4.0
+     - ``sphinx.builders.epub3.validate_config_values()``
+
    * - ``sphinx.builders.html.SingleFileHTMLBuilder``
      - 2.0
      - 4.0

doc/latex.rst

@@ -8,9 +8,6 @@ LaTeX customization
 .. module:: latex
    :synopsis: LaTeX specifics.
 
-For details of the LaTeX/PDF builder command line invocation, refer to
-:py:class:`~sphinx.builders.latex.LaTeXBuilder`.
-
 .. raw:: latex
 
    \begingroup
@@ -29,15 +26,24 @@ For details of the LaTeX/PDF builder command line invocation, refer to
          cautionBgColor={named}{LightCyan}}
    \relax
 
-.. _latex-basic:
-
-Basic customization
--------------------
-
 The *latex* target does not benefit from prepared themes.
 
-Basic customization is obtained via usage of the :ref:`latex-options`. For
+The :ref:`latex-options`, and particularly among them the
-example::
+:ref:`latex_elements <latex_elements_confval>` variable
+provides much of the interface for customization.
+
+For some details of the LaTeX/PDF builder command line
+invocation, refer to :py:class:`~sphinx.builders.latex.LaTeXBuilder`.
+
+.. _latex-basic:
+
+Example
+-------
+
+Keep in mind that backslashes must be doubled in Python string literals to
+avoid interpretation as escape sequences, or use raw strings (as is done here).
+
+::
 
    # inside conf.py
    latex_engine = 'xelatex'
@@ -59,49 +65,412 @@ example::
    }
    latex_show_urls = 'footnote'
 
-.. the above was tested on Sphinx's own 1.5a2 documentation with good effect!
-
 .. highlight:: latex
 
-If the size of the ``'preamble'`` contents becomes inconvenient, one may move
+.. _latex_elements_confval:
-all needed macros into some file :file:`mystyle.tex.txt` of the project source
-repertory, and get LaTeX to import it at run time::
 
-   'preamble': r'\input{mystyle.tex.txt}',
+The latex_elements configuration setting
-   # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
+----------------------------------------
-   'preamble': r'\usepackage{mystyle}',
 
-It is then needed to set appropriately :confval:`latex_additional_files`, for
+A dictionary that contains LaTeX snippets overriding those Sphinx usually puts
-example::
+into the generated ``.tex`` files.  Its ``'sphinxsetup'`` key is described
+`separately <latexsphinxsetup_>`_.
+
+* Keys that you may want to override include:
+
+  ``'papersize'``
+     Paper size option of the document class (``'a4paper'`` or
+     ``'letterpaper'``), default ``'letterpaper'``.
+
+  ``'pointsize'``
+     Point size option of the document class (``'10pt'``, ``'11pt'`` or
+     ``'12pt'``), default ``'10pt'``.
+
+  ``'pxunit'``
+     the value of the ``px`` when used in image attributes ``width`` and
+     ``height``. The default value is ``'0.75bp'`` which achieves
+     ``96px=1in`` (in TeX ``1in = 72bp = 72.27pt``.) To obtain for
+     example ``100px=1in`` use ``'0.01in'`` or ``'0.7227pt'`` (the latter
+     leads to TeX computing a more precise value, due to the smaller unit
+     used in the specification); for ``72px=1in``, simply use ``'1bp'``; for
+     ``90px=1in``, use ``'0.8bp'`` or ``'0.803pt'``.
+
+     .. versionadded:: 1.5
+
+  ``'passoptionstopackages'``
+     A string which will be positioned early in the preamble, designed to
+     contain ``\\PassOptionsToPackage{options}{foo}`` commands. Default empty.
+
+     .. versionadded:: 1.4
+
+  ``'babel'``
+     "babel" package inclusion, default ``'\\usepackage{babel}'`` (the
+     suitable document language string is passed as class option, and
+     ``english`` is used if no language.) For Japanese documents, the
+     default is the empty string.
+
+     With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document to use
+     `polyglossia`_, but one should be aware that current `babel`_ has
+     improved its support for Unicode engines in recent years and for some
+     languages it may make sense to prefer ``babel`` over ``polyglossia``.
+
+     .. hint::
+
+        After modifiying a core LaTeX key like this one, clean up the LaTeX
+        build repertory before next PDF build, else left-over auxiliary
+        files are likely to break the build.
+
+     .. _`polyglossia`: https://ctan.org/pkg/polyglossia
+     .. _`babel`: https://ctan.org/pkg/babel
+
+     .. versionchanged:: 1.5
+        For :confval:`latex_engine` set to ``'xelatex'``, the default
+        is ``'\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'``.
+     .. versionchanged:: 1.6
+        ``'lualatex'`` uses same default setting as ``'xelatex'``
+     .. versionchanged:: 1.7.6
+        For French, ``xelatex`` and ``lualatex`` default to using
+        ``babel``, not ``polyglossia``.
+
+  ``'fontpkg'``
+     Font package inclusion, the default is ``'\\usepackage{times}'`` which
+     uses Times for text, Helvetica for sans serif and Courier for monospace.
+
+     .. versionchanged:: 1.2
+        Defaults to ``''`` when the :confval:`language` uses the Cyrillic
+        script.
+     .. versionchanged:: 2.0
+        Support for individual Greek and Cyrillic letters:
+
+        - In order to support occasional Cyrillic (физика частиц)
+          or Greek letters (Σωματιδιακή φυσική) in
+          a document whose language is English or a  Latin European
+          one, the default set-up is enhanced (only for ``'pdflatex'``
+          engine) to do:
+
+          .. code-block:: latex
+
+             \substitutefont{LGR}{\rmdefault}{cmr}
+             \substitutefont{LGR}{\sfdefault}{cmss}
+             \substitutefont{LGR}{\ttdefault}{cmtt}
+             \substitutefont{X2}{\rmdefault}{cmr}
+             \substitutefont{X2}{\sfdefault}{cmss}
+             \substitutefont{X2}{\ttdefault}{cmtt}
+
+          but this is activated only under the condition that the
+          ``'fontenc'`` key is configured to load the ``LGR`` (Greek)
+          and/or ``X2`` (Cyrillic) pdflatex-font encodings (if the
+          :confval:`language` is set to a Cyrillic language, this
+          ``'fontpkg'`` key must be used as "times" package has no direct
+          support for it; then keep only ``LGR`` lines from the above,
+          if support is needed for Greek in the text).
+
+          The ``\substitutefont`` command is from the eponymous LaTeX
+          package, which is loaded by Sphinx if needed (on Ubuntu xenial it
+          is part of ``texlive-latex-extra`` which is a Sphinx
+          requirement).
+
+          Only if the document actually does contain Unicode Greek letters
+          (in text) or Cyrillic letters, will the above default set-up
+          cause additional requirements for the PDF build.  On Ubuntu
+          xenial, ``texlive-lang-greek``, ``texlive-lang-cyrillic``, and
+          (with the above choice of fonts) the ``cm-super`` (or
+          ``cm-super-minimal``) package.
+
+        - For ``'xelatex'`` and ``'lualatex'``, the default is to
+          use the FreeFont family:  this OpenType font family
+          supports both Cyrillic and Greek scripts and is available as
+          separate Ubuntu xenial package ``fonts-freefont-otf``, it is not
+          needed to install the big package ``texlive-fonts-extra``.
+
+        - ``'platex'`` (Japanese documents) engine supports individual
+          Cyrillic and Greek letters with no need of extra user set-up.
+
+  ``'fncychap'``
+     Inclusion of the "fncychap" package (which makes fancy chapter titles),
+     default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation
+     (this option is slightly customized by Sphinx),
+     ``'\\usepackage[Sonny]{fncychap}'`` for internationalized docs (because
+     the "Bjarne" style uses numbers spelled out in English).  Other
+     "fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and
+     "Bjornstrup".  You can also set this to ``''`` to disable fncychap.
+
+     The default is ``''`` for Japanese documents.
+
+  ``'preamble'``
+     Additional preamble content, default empty.  One may move all needed
+     macros into some file :file:`mystyle.tex.txt` of the project source
+     repertory, and get LaTeX to import it at run time::
+
+       'preamble': r'\input{mystyle.tex.txt}',
+       # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
+       'preamble': r'\usepackage{mystyle}',
+
+     It is then needed to set appropriately
+     :confval:`latex_additional_files`, for example::
+
+        latex_additional_files = ["mystyle.sty"]
+
+
+  ``'figure_align'``
+     Latex figure float alignment, default 'htbp' (here, top, bottom, page).
+     Whenever an image doesn't fit into the current page, it will be
+     'floated' into the next page but may be preceded by any other text.
+     If you don't like this behavior, use 'H' which will disable floating
+     and position figures strictly in the order they appear in the source.
+
+     .. versionadded:: 1.3
+
+  ``'atendofbody'``
+     Additional document content (right before the indices), default empty.
+
+     .. versionadded:: 1.5
+
+  ``'footer'``
+     Additional footer content (before the indices), default empty.
+
+     .. deprecated:: 1.5
+        Use ``'atendofbody'`` key instead.
+
+* Keys that don't need to be overridden unless in special cases are:
+
+  ``'extraclassoptions'``
+     The default is the empty string. Example: ``'extraclassoptions':
+     'openany'`` will allow chapters (for documents of the ``'manual'``
+     type) to start on any page.
+
+     .. versionadded:: 1.2
+     .. versionchanged:: 1.6
+        Added this documentation.
+
+  ``'maxlistdepth'``
+     LaTeX allows by default at most 6 levels for nesting list and
+     quote-like environments, with at most 4 enumerated lists, and 4 bullet
+     lists. Setting this key for example to ``'10'`` (as a string) will
+     allow up to 10 nested levels (of all sorts). Leaving it to the empty
+     string means to obey the LaTeX default.
+
+     .. warning::
+
+        - Using this key may prove incompatible with some LaTeX packages
+          or special document classes which do their own list customization.
+
+        - The key setting is silently *ignored* if ``\usepackage{enumitem}``
+          is executed inside the document preamble. Use then rather the
+          dedicated commands of this LaTeX package.
+
+     .. versionadded:: 1.5
+
+  ``'inputenc'``
+     "inputenc" package inclusion, defaults to
+     ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex.
+     Otherwise empty.
+
+     .. versionchanged:: 1.4.3
+        Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all
+        compilers.
+
+  ``'cmappkg'``
+     "cmap" package inclusion, default ``'\\usepackage{cmap}'``.
+
+     .. versionadded:: 1.2
+
+  ``'fontenc'``
+     "fontenc" package inclusion, defaults to
+     ``'\\usepackage[T1]{fontenc}'``.
+
+     If ``'pdflatex'`` is the :confval:`latex_engine`, one can add ``LGR``
+     for support of Greek letters in the document, and also ``X2`` (or
+     ``T2A``) for Cyrillic letters, like this:
+
+     .. code-block:: latex
+
+        r'\usepackage[LGR,X2,T1]{fontenc}'
+
+     .. attention::
+
+        Prior to 2.0, Unicode Greek letters were escaped to use LaTeX math
+        mark-up.  This is not the case anymore, and the above must be used
+        (only in case of ``'pdflatex'`` engine) if the source contains such
+        Unicode Greek.
+
+        On Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super``
+        (for the latter, only if the ``'fontpkg'`` setting is left to its
+        default) are needed for ``LGR`` to work.  In place of ``cm-super``
+        one can install smaller ``cm-super-minimal``, but it requires the
+        LaTeX document to execute ``\usepackage[10pt]{type1ec}`` before
+        loading ``fontenc``.  Thus, use this key with this extra at its
+        start if needed.
+
+     .. versionchanged:: 1.5
+        Defaults to ``'\\usepackage{fontspec}'`` when
+        :confval:`latex_engine` is ``'xelatex'``.
+     .. versionchanged:: 1.6
+        ``'lualatex'`` uses ``fontspec`` per default like ``'xelatex'``.
+     .. versionchanged:: 2.0
+        ``'lualatex'`` executes
+        ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` to disable TeX
+        ligatures.
+     .. versionchanged:: 2.0
+        Detection of ``LGR``, ``T2A``, ``X2`` to trigger support of
+        occasional Greek or Cyrillic (``'pdflatex'`` only, as this support
+        is provided natively by ``'platex'`` and only requires suitable
+        font with ``'xelatex'/'lualatex'``).
+
+  ``'textgreek'``
+     The default (``'pdflatex'`` only) is
+     ``'\\usepackage{textalpha}'``, but only if ``'fontenc'`` was
+     modified by user to include ``LGR`` option.  If not, the key
+     value will be forced to be the empty string.
+
+     This is needed for ``pdfLaTeX`` to support Unicode input of Greek
+     letters such as φύσις.  Expert users may want to load the ``textalpha``
+     package with its option ``normalize-symbols``.
+
+     .. hint::
+
+        Unicode Greek (but no further Unicode symbols) in :rst:dir:`math`
+        can be supported by ``'pdflatex'`` from setting this key to
+        ``r'\usepackage{textalpha,alphabeta}'``.  Then ``:math:`α``` (U+03B1)
+        will render as :math:`\alpha`.  For wider Unicode support in math
+        input, see the discussion of :confval:`latex_engine`.
+
+     With ``'platex'`` (Japanese),  ``'xelatex'`` or ``'lualatex'``, this
+     key is ignored.
+
+     .. versionadded:: 2.0
+  ``'geometry'``
+     "geometry" package inclusion, the default definition is:
+
+       ``'\\usepackage{geometry}'``
+
+     with an additional ``[dvipdfm]`` for Japanese documents.
+     The Sphinx LaTeX style file executes:
+
+       ``\PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}``
+
+     which can be customized via corresponding :ref:`'sphinxsetup' options
+     <latexsphinxsetup>`.
+
+     .. versionadded:: 1.5
+
+     .. versionchanged:: 1.5.2
+        ``dvipdfm`` option if :confval:`latex_engine` is ``'platex'``.
+
+     .. versionadded:: 1.5.3
+        The :ref:`'sphinxsetup' keys for the margins
+        <latexsphinxsetuphmargin>`.
+
+     .. versionchanged:: 1.5.3
+        The location in the LaTeX file has been moved to after
+        ``\usepackage{sphinx}`` and ``\sphinxsetup{..}``, hence also after
+        insertion of ``'fontpkg'`` key. This is in order to handle the paper
+        layout options in a special way for Japanese documents: the text
+        width will be set to an integer multiple of the *zenkaku* width, and
+        the text height to an integer multiple of the baseline. See the
+        :ref:`hmargin <latexsphinxsetuphmargin>` documentation for more.
+
+  ``'hyperref'``
+     "hyperref" package inclusion; also loads package "hypcap" and issues
+     ``\urlstyle{same}``. This is done after :file:`sphinx.sty` file is
+     loaded and before executing the contents of ``'preamble'`` key.
+
+     .. attention::
+
+        Loading of packages "hyperref" and "hypcap" is mandatory.
+
+     .. versionadded:: 1.5
+        Previously this was done from inside :file:`sphinx.sty`.
+
+  ``'maketitle'``
+     "maketitle" call, default ``'\\sphinxmaketitle'``. Override
+     if you want to generate a differently styled title page.
+
+     .. hint::
+
+        If the key value is set to
+        ``r'\newcommand\sphinxbackoftitlepage{<Extra
+        material>}\sphinxmaketitle'``, then ``<Extra material>`` will be
+        typeset on back of title page (``'manual'`` docclass only).
+
+     .. versionchanged:: 1.8.3
+        Original ``\maketitle`` from document class is not overwritten,
+        hence is re-usable as part of some custom setting for this key.
+     .. versionadded:: 1.8.3
+        ``\sphinxbackoftitlepage`` optional macro.  It can also be defined
+        inside ``'preamble'`` key rather than this one.
+
+  ``'releasename'``
+     value that prefixes ``'release'`` element on title page, default
+     ``'Release'``. As for *title* and *author* used in the tuples of
+     :confval:`latex_documents`, it is inserted as LaTeX markup.
+
+  ``'tableofcontents'``
+     "tableofcontents" call, default ``'\\sphinxtableofcontents'`` (it is a
+     wrapper of unmodified ``\tableofcontents``, which may itself be
+     customized by user loaded packages.)
+     Override if
+     you want to generate a different table of contents or put content
+     between the title page and the TOC.
+
+     .. versionchanged:: 1.5
+        Previously the meaning of ``\tableofcontents`` itself was modified
+        by Sphinx. This created an incompatibility with dedicated packages
+        modifying it also such as "tocloft" or "etoc".
+
+  ``'transition'``
+     Commands used to display transitions, default
+     ``'\n\n\\bigskip\\hrule\\bigskip\n\n'``.  Override if you want to
+     display transitions differently.
+
+     .. versionadded:: 1.2
+     .. versionchanged:: 1.6
+        Remove unneeded ``{}`` after ``\\hrule``.
+
+  ``'printindex'``
+     "printindex" call, the last thing in the file, default
+     ``'\\printindex'``.  Override if you want to generate the index
+     differently or append some content after the index. For example
+     ``'\\footnotesize\\raggedright\\printindex'`` is advisable when the
+     index is full of long entries.
+
+  ``'fvset'``
+     Customization of ``fancyvrb`` LaTeX package.  Sphinx does by default
+     ``'fvset': '\\fvset{fontsize=\\small}'``, to adjust for the large
+     character width of the monospace font, used in code-blocks.
+     You may need to modify this if you use custom fonts.
+
+     .. versionadded:: 1.8
+     .. versionchanged:: 2.0
+        Due to new default font choice for ``'xelatex'`` and ``'lualatex'``
+        (FreeFont), Sphinx does ``\\fvset{fontsize=\\small}`` also with these
+        engines (and not ``\\fvset{fontsize=auto}``).
+
+* Keys that are set by other options and therefore should not be overridden
+  are:
+
+  ``'docclass'``
+  ``'classoptions'``
+  ``'title'``
+  ``'release'``
+  ``'author'``
+  ``'makeindex'``
 
-   latex_additional_files = ["mystyle.sty"]
 
 .. _latexsphinxsetup:
 
-The LaTeX style file options
+\\'sphinxsetup\\' key
-----------------------------
+---------------------
 
-Additional customization is possible via LaTeX options of the Sphinx style
+The ``'sphinxsetup'`` key of :ref:`latex_elements <latex_elements_confval>`
-file.
+provides a LaTeX-type customization interface::
-
-The sphinxsetup interface
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The ``'sphinxsetup'`` key of :confval:`latex_elements` provides a convenient
-interface::
 
    latex_elements = {
        'sphinxsetup': 'key1=value1, key2=value2, ...',
    }
 
-- some values may be LaTeX macros, then the backslashes must be
+It defaults to empty.  If non-empty, it will be passed as argument to the
-  Python-escaped, or the whole must be a Python raw string,
+``\sphinxsetup`` macro inside the document preamble, like this::
-- LaTeX boolean keys require *lowercase* ``true`` or ``false`` values,
-- spaces around the commas and equal signs are ignored, spaces inside LaTeX
-  macros may be significant.
-
-If non-empty, it will be passed as argument to the ``\sphinxsetup`` macro
-inside the document preamble, like this::
 
    \usepackage{sphinx}
    \sphinxsetup{key1=value1, key2=value2,...}
@@ -112,7 +481,7 @@ inside the document preamble, like this::
 
    It is possible to insert further uses of the ``\sphinxsetup`` LaTeX macro
    directly into the body of the document, via the help of the :rst:dir:`raw`
-   directive.  Here is how this present chapter in PDF is styled::
+   directive.  Here is how this present chapter is styled in the PDF output::
 
      .. raw:: latex
 
@@ -147,8 +516,9 @@ inside the document preamble, like this::
       }
 
 
-The available styling options
+LaTeX boolean keys require *lowercase* ``true`` or ``false`` values.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Spaces around the commas and equal signs are ignored, spaces inside LaTeX
+macros may be significant.
 
 .. _latexsphinxsetuphmargin:
 

doc/usage/configuration.rst

@@ -864,6 +864,8 @@ that use Sphinx's HTMLWriter class.
    The URL which points to the root of the HTML documentation.  It is used to
    indicate the location of document like ``canonical_url``.
 
+   .. versionadded:: 1.8
+
 .. confval:: html_context
 
    A dictionary of values to pass into the template engine's context for all
@@ -1782,8 +1784,7 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
 Options for LaTeX output
 ------------------------
 
-These options influence LaTeX output. Refer to :doc:`/latex` for more
+These options influence LaTeX output.
-information.
 
 .. confval:: latex_engine
 
@@ -1974,383 +1975,7 @@ information.
 
    .. versionadded:: 0.5
 
-   A dictionary that contains LaTeX snippets that override those Sphinx usually
+   Its :ref:`documentation <latex_elements_confval>` has moved to :doc:`/latex`.
-   puts into the generated ``.tex`` files.
-
-   Keep in mind that backslashes must be doubled in Python string literals to
-   avoid interpretation as escape sequences.
-
-   * Keys that you may want to override include:
-
-     ``'papersize'``
-        Paper size option of the document class (``'a4paper'`` or
-        ``'letterpaper'``), default ``'letterpaper'``.
-
-     ``'pointsize'``
-        Point size option of the document class (``'10pt'``, ``'11pt'`` or
-        ``'12pt'``), default ``'10pt'``.
-
-     ``'pxunit'``
-        the value of the ``px`` when used in image attributes ``width`` and
-        ``height``. The default value is ``'0.75bp'`` which achieves
-        ``96px=1in`` (in TeX ``1in = 72bp = 72.27pt``.) To obtain for
-        example ``100px=1in`` use ``'0.01in'`` or ``'0.7227pt'`` (the latter
-        leads to TeX computing a more precise value, due to the smaller unit
-        used in the specification); for ``72px=1in``, simply use ``'1bp'``; for
-        ``90px=1in``, use ``'0.8bp'`` or ``'0.803pt'``.
-
-        .. versionadded:: 1.5
-
-     ``'sphinxsetup'``
-        A comma separated list of ``key=value`` package options for the Sphinx
-        LaTeX style, default empty. See :doc:`/latex`.
-
-        .. versionadded:: 1.5
-
-     ``'passoptionstopackages'``
-        A string which will be positioned early in the preamble, designed to
-        contain ``\\PassOptionsToPackage{options}{foo}`` commands. Default empty.
-
-        .. versionadded:: 1.4
-
-     ``'babel'``
-        "babel" package inclusion, default ``'\\usepackage{babel}'`` (the
-        suitable document language string is passed as class option, and
-        ``english`` is used if no language.) For Japanese documents, the
-        default is the empty string.
-
-        With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document to use
-        `polyglossia`_, but one should be aware that current `babel`_ has
-        improved its support for Unicode engines in recent years and for some
-        languages it may make sense to prefer ``babel`` over ``polyglossia``.
-
-        .. hint::
-
-           After modifiying a core LaTeX key like this one, clean up the LaTeX
-           build repertory before next PDF build, else left-over auxiliary
-           files are likely to break the build.
-
-        .. _`polyglossia`: https://ctan.org/pkg/polyglossia
-        .. _`babel`: https://ctan.org/pkg/babel
-
-        .. versionchanged:: 1.5
-           For :confval:`latex_engine` set to ``'xelatex'``, the default
-           is ``'\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'``.
-        .. versionchanged:: 1.6
-           ``'lualatex'`` uses same default setting as ``'xelatex'``
-        .. versionchanged:: 1.7.6
-           For French, ``xelatex`` and ``lualatex`` default to using
-           ``babel``, not ``polyglossia``.
-
-     ``'fontpkg'``
-        Font package inclusion, the default is ``'\\usepackage{times}'`` which
-        uses Times for text, Helvetica for sans serif and Courier for monospace.
-
-        .. versionchanged:: 1.2
-           Defaults to ``''`` when the :confval:`language` uses the Cyrillic
-           script.
-        .. versionchanged:: 2.0
-           Support for individual Greek and Cyrillic letters:
-
-           - In order to support occasional Cyrillic (физика частиц)
-             or Greek letters (Σωματιδιακή φυσική) in
-             a document whose language is English or a  Latin European
-             one, the default set-up is enhanced (only for ``'pdflatex'``
-             engine) to do:
-
-             .. code-block:: latex
-
-                \substitutefont{LGR}{\rmdefault}{cmr}
-                \substitutefont{LGR}{\sfdefault}{cmss}
-                \substitutefont{LGR}{\ttdefault}{cmtt}
-                \substitutefont{X2}{\rmdefault}{cmr}
-                \substitutefont{X2}{\sfdefault}{cmss}
-                \substitutefont{X2}{\ttdefault}{cmtt}
-
-             but this is activated only under the condition that the
-             ``'fontenc'`` key is configured to load the ``LGR`` (Greek)
-             and/or ``X2`` (Cyrillic) pdflatex-font encodings (if the
-             :confval:`language` is set to a Cyrillic language, this
-             ``'fontpkg'`` key must be used as "times" package has no direct
-             support for it; then keep only ``LGR`` lines from the above,
-             if support is needed for Greek in the text).
-
-             The ``\substitutefont`` command is from the eponymous LaTeX
-             package, which is loaded by Sphinx if needed (on Ubuntu xenial it
-             is part of ``texlive-latex-extra`` which is a Sphinx
-             requirement).
-
-             Only if the document actually does contain Unicode Greek letters
-             (in text) or Cyrillic letters, will the above default set-up
-             cause additional requirements for the PDF build.  On Ubuntu
-             xenial, ``texlive-lang-greek``, ``texlive-lang-cyrillic``, and
-             (with the above choice of fonts) the ``cm-super`` (or
-             ``cm-super-minimal``) package.
-
-           - For ``'xelatex'`` and ``'lualatex'``, the default is to
-             use the FreeFont family:  this OpenType font family
-             supports both Cyrillic and Greek scripts and is available as
-             separate Ubuntu xenial package ``fonts-freefont-otf``, it is not
-             needed to install the big package ``texlive-fonts-extra``.
-
-           - ``'platex'`` (Japanese documents) engine supports individual
-             Cyrillic and Greek letters with no need of extra user set-up.
-     ``'fncychap'``
-        Inclusion of the "fncychap" package (which makes fancy chapter titles),
-        default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation
-        (this option is slightly customized by Sphinx),
-        ``'\\usepackage[Sonny]{fncychap}'`` for internationalized docs (because
-        the "Bjarne" style uses numbers spelled out in English).  Other
-        "fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and
-        "Bjornstrup".  You can also set this to ``''`` to disable fncychap.
-
-        The default is ``''`` for Japanese documents.
-
-     ``'preamble'``
-        Additional preamble content, default empty. See :doc:`/latex`.
-
-     ``'atendofbody'``
-        Additional document content (right before the indices), default empty.
-
-        .. versionadded:: 1.5
-
-     ``'figure_align'``
-        Latex figure float alignment, default 'htbp' (here, top, bottom, page).
-        Whenever an image doesn't fit into the current page, it will be
-        'floated' into the next page but may be preceded by any other text.
-        If you don't like this behavior, use 'H' which will disable floating
-        and position figures strictly in the order they appear in the source.
-
-        .. versionadded:: 1.3
-
-     ``'footer'``
-        Additional footer content (before the indices), default empty.
-
-        .. deprecated:: 1.5
-           Use ``'atendofbody'`` key instead.
-
-   * Keys that don't need to be overridden unless in special cases are:
-
-     ``'extraclassoptions'``
-        The default is the empty string. Example: ``'extraclassoptions':
-        'openany'`` will allow chapters (for documents of the ``'manual'``
-        type) to start on any page.
-
-        .. versionadded:: 1.2
-        .. versionchanged:: 1.6
-           Added this documentation.
-
-     ``'maxlistdepth'``
-        LaTeX allows by default at most 6 levels for nesting list and
-        quote-like environments, with at most 4 enumerated lists, and 4 bullet
-        lists. Setting this key for example to ``'10'`` (as a string) will
-        allow up to 10 nested levels (of all sorts). Leaving it to the empty
-        string means to obey the LaTeX default.
-
-        .. warning::
-
-           - Using this key may prove incompatible with some LaTeX packages
-             or special document classes which do their own list customization.
-
-           - The key setting is silently *ignored* if ``\usepackage{enumitem}``
-             is executed inside the document preamble. Use then rather the
-             dedicated commands of this LaTeX package.
-
-        .. versionadded:: 1.5
-
-     ``'inputenc'``
-        "inputenc" package inclusion, defaults to
-        ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex.
-        Otherwise empty.
-
-        .. versionchanged:: 1.4.3
-           Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all
-           compilers.
-
-     ``'cmappkg'``
-        "cmap" package inclusion, default ``'\\usepackage{cmap}'``.
-
-        .. versionadded:: 1.2
-
-     ``'fontenc'``
-        "fontenc" package inclusion, defaults to
-        ``'\\usepackage[T1]{fontenc}'``.
-
-        If ``'pdflatex'`` is the :confval:`latex_engine`, one can add ``LGR``
-        for support of Greek letters in the document, and also ``X2`` (or
-        ``T2A``) for Cyrillic letters, like this:
-
-        .. code-block:: latex
-
-           r'\usepackage[LGR,X2,T1]{fontenc}'
-
-        .. attention::
-
-           Prior to 2.0, Unicode Greek letters were escaped to use LaTeX math
-           mark-up.  This is not the case anymore, and the above must be used
-           (only in case of ``'pdflatex'`` engine) if the source contains such
-           Unicode Greek.
-
-           On Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super``
-           (for the latter, only if the ``'fontpkg'`` setting is left to its
-           default) are needed for ``LGR`` to work.  In place of ``cm-super``
-           one can install smaller ``cm-super-minimal``, but it requires the
-           LaTeX document to execute ``\usepackage[10pt]{type1ec}`` before
-           loading ``fontenc``.  Thus, use this key with this extra at its
-           start if needed.
-
-        .. versionchanged:: 1.5
-           Defaults to ``'\\usepackage{fontspec}'`` when
-           :confval:`latex_engine` is ``'xelatex'``.
-        .. versionchanged:: 1.6
-           ``'lualatex'`` uses ``fontspec`` per default like ``'xelatex'``.
-        .. versionchanged:: 2.0
-           ``'lualatex'`` executes
-           ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` to disable TeX
-           ligatures.
-        .. versionchanged:: 2.0
-           Detection of ``LGR``, ``T2A``, ``X2`` to trigger support of
-           occasional Greek or Cyrillic (``'pdflatex'`` only, as this support
-           is provided natively by ``'platex'`` and only requires suitable
-           font with ``'xelatex'/'lualatex'``).
-
-     ``'textgreek'``
-        The default (``'pdflatex'`` only) is
-        ``'\\usepackage{textalpha}'``, but only if ``'fontenc'`` was
-        modified by user to include ``LGR`` option.  If not, the key
-        value will be forced to be the empty string.
-
-        This is needed for ``pdfLaTeX`` to support Unicode input of Greek
-        letters such as φύσις.  Expert users may want to load the ``textalpha``
-        package with its option ``normalize-symbols``.
-
-        .. hint::
-
-           Unicode Greek (but no further Unicode symbols) in :rst:dir:`math`
-           can be supported by ``'pdflatex'`` from setting this key to
-           ``r'\usepackage{textalpha,alphabeta}'``.  Then ``:math:`α``` (U+03B1)
-           will render as :math:`\alpha`.  For wider Unicode support in math
-           input, see the discussion of :confval:`latex_engine`.
-
-        With ``'platex'`` (Japanese),  ``'xelatex'`` or ``'lualatex'``, this
-        key is ignored.
-
-        .. versionadded:: 2.0
-     ``'geometry'``
-        "geometry" package inclusion, the default definition is:
-
-          ``'\\usepackage{geometry}'``
-
-        with an additional ``[dvipdfm]`` for Japanese documents.
-        The Sphinx LaTeX style file executes:
-
-          ``\PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}``
-
-        which can be customized via corresponding :ref:`'sphinxsetup' options
-        <latexsphinxsetup>`.
-
-        .. versionadded:: 1.5
-
-        .. versionchanged:: 1.5.2
-           ``dvipdfm`` option if :confval:`latex_engine` is ``'platex'``.
-
-        .. versionadded:: 1.5.3
-           The :ref:`'sphinxsetup' keys for the margins
-           <latexsphinxsetuphmargin>`.
-
-        .. versionchanged:: 1.5.3
-           The location in the LaTeX file has been moved to after
-           ``\usepackage{sphinx}`` and ``\sphinxsetup{..}``, hence also after
-           insertion of ``'fontpkg'`` key. This is in order to handle the paper
-           layout options in a special way for Japanese documents: the text
-           width will be set to an integer multiple of the *zenkaku* width, and
-           the text height to an integer multiple of the baseline. See the
-           :ref:`hmargin <latexsphinxsetuphmargin>` documentation for more.
-
-     ``'hyperref'``
-        "hyperref" package inclusion; also loads package "hypcap" and issues
-        ``\urlstyle{same}``. This is done after :file:`sphinx.sty` file is
-        loaded and before executing the contents of ``'preamble'`` key.
-
-        .. attention::
-
-           Loading of packages "hyperref" and "hypcap" is mandatory.
-
-        .. versionadded:: 1.5
-           Previously this was done from inside :file:`sphinx.sty`.
-
-     ``'maketitle'``
-        "maketitle" call, default ``'\\sphinxmaketitle'``. Override
-        if you want to generate a differently styled title page.
-
-        .. hint::
-
-           If the key value is set to
-           ``r'\newcommand\sphinxbackoftitlepage{<Extra
-           material>}\sphinxmaketitle'``, then ``<Extra material>`` will be
-           typeset on back of title page (``'manual'`` docclass only).
-
-        .. versionchanged:: 1.8.3
-           Original ``\maketitle`` from document class is not overwritten,
-           hence is re-usable as part of some custom setting for this key.
-        .. versionadded:: 1.8.3
-           ``\sphinxbackoftitlepage`` optional macro.  It can also be defined
-           inside ``'preamble'`` key rather than this one.
-     ``'releasename'``
-        value that prefixes ``'release'`` element on title page, default
-        ``'Release'``. As for *title* and *author* used in the tuples of
-        :confval:`latex_documents`, it is inserted as LaTeX markup.
-
-     ``'tableofcontents'``
-        "tableofcontents" call, default ``'\\sphinxtableofcontents'`` (it is a
-        wrapper of unmodified ``\tableofcontents``, which may itself be
-        customized by user loaded packages.)
-        Override if
-        you want to generate a different table of contents or put content
-        between the title page and the TOC.
-
-        .. versionchanged:: 1.5
-           Previously the meaning of ``\tableofcontents`` itself was modified
-           by Sphinx. This created an incompatibility with dedicated packages
-           modifying it also such as "tocloft" or "etoc".
-
-     ``'transition'``
-        Commands used to display transitions, default
-        ``'\n\n\\bigskip\\hrule\\bigskip\n\n'``.  Override if you want to
-        display transitions differently.
-
-        .. versionadded:: 1.2
-        .. versionchanged:: 1.6
-           Remove unneeded ``{}`` after ``\\hrule``.
-
-     ``'printindex'``
-        "printindex" call, the last thing in the file, default
-        ``'\\printindex'``.  Override if you want to generate the index
-        differently or append some content after the index. For example
-        ``'\\footnotesize\\raggedright\\printindex'`` is advisable when the
-        index is full of long entries.
-
-     ``'fvset'``
-        Customization of ``fancyvrb`` LaTeX package.  Sphinx does by default
-        ``'fvset': '\\fvset{fontsize=\\small}'``, to adjust for the large
-        character width of the monospace font, used in code-blocks.
-        You may need to modify this if you use custom fonts.
-
-        .. versionadded:: 1.8
-        .. versionchanged:: 2.0
-           Due to new default font choice for ``'xelatex'`` and ``'lualatex'``
-           (FreeFont), Sphinx does ``\\fvset{fontsize=\\small}`` also with these
-           engines (and not ``\\fvset{fontsize=auto}``).
-
-   * Keys that are set by other options and therefore should not be overridden
-     are:
-
-     ``'docclass'``
-     ``'classoptions'``
-     ``'title'``
-     ``'release'``
-     ``'author'``
-     ``'makeindex'``
 
 .. confval:: latex_docclass
 

doc/usage/markdown.rst

@@ -22,18 +22,14 @@ Configuration
 
 To configure your Sphinx project for Markdown support, proceed as follows:
 
-#. Install the Markdown parser *recommonmark* from its source on GitHub::
+#. Install the Markdown parser *recommonmark*::
 
-      pip install git+https://github.com/rtfd/recommonmark
+      pip install --upgrade recommonmark
 
    .. note::
 
       The configuration as explained here requires recommonmark version
-      0.5.0.dev or higher, which is at the time of writing not available on
+      0.5.0 or later.
-      PyPI.  If you want to use a released recommonmark version, follow the
-      instructions in the `Sphinx 1.8 documentation`__.
-
-__ https://www.sphinx-doc.org/en/1.8/usage/markdown.html
 
 #. Add *recommonmark* to the
    :confval:`list of configured extensions <extensions>`::

doc/usage/restructuredtext/domains.rst

@@ -541,8 +541,8 @@ The C++ Domain
 
 The C++ domain (name **cpp**) supports documenting C++ projects.
 
-Directives
+Directives for Declaring Entities
-~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following directives are available. All declarations can start with a
 visibility statement (``public``, ``private`` or ``protected``).
@@ -794,6 +794,41 @@ This will be rendered as:
 Explicit ref: :cpp:var:`Data::@data::a`. Short-hand ref: :cpp:var:`Data::a`.
 
 
+Aliasing Declarations
+~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes it may be helpful list declarations elsewhere than their main documentation,
+e.g., when creating a synopsis of a class interface.
+The following directive can be used for this purpose.
+
+.. rst:directive:: .. cpp:alias:: name or function signature
+
+   Insert one or more alias declarations. Each entity can be specified
+   as they can in the :rst:role:`cpp:any` role.
+   If the name of a function is given (as opposed to the complete signature),
+   then all overloads of the function will be listed.
+
+   For example::
+
+       .. cpp:alias:: Data::a
+                      overload_example::C::f
+
+   becomes
+
+   .. cpp:alias:: Data::a
+                  overload_example::C::f
+
+   whereas::
+
+       .. cpp:alias:: void overload_example::C::f(double d) const
+                      void overload_example::C::f(double d)
+
+   becomes
+
+    .. cpp:alias:: void overload_example::C::f(double d) const
+                   void overload_example::C::f(double d)
+
+
 Constrained Templates
 ~~~~~~~~~~~~~~~~~~~~~
 

sphinx/builders/__init__.py

@@ -403,7 +403,7 @@ class Builder:
         Store all environment docnames in the canonical format (ie using SEP as
         a separator in place of os.path.sep).
         """
-        logger.info(bold('updating environment: '), nonl=True)
+        logger.info(bold(__('updating environment: ')), nonl=True)
 
         self.env.find_files(self.config, self)
         updated = (self.env.config_status != CONFIG_OK)
@@ -422,7 +422,7 @@ class Builder:
         if changed:
             reason = CONFIG_CHANGED_REASON.get(self.env.config_status, '')
             logger.info('[%s] ', reason, nonl=True)
-        logger.info('%s added, %s changed, %s removed',
+        logger.info(__('%s added, %s changed, %s removed'),
                     len(added), len(changed), len(removed))
 
         # clear all files no longer present
@@ -461,7 +461,7 @@ class Builder:
 
     def _read_serial(self, docnames):
         # type: (List[str]) -> None
-        for docname in status_iterator(docnames, 'reading sources... ', "purple",
+        for docname in status_iterator(docnames, __('reading sources... '), "purple",
                                        len(docnames), self.app.verbosity):
             # remove all inventory entries for that file
             self.app.emit('env-purge-doc', self.env, docname)
@@ -491,12 +491,12 @@ class Builder:
         tasks = ParallelTasks(nproc)
         chunks = make_chunks(docnames, nproc)
 
-        for chunk in status_iterator(chunks, 'reading sources... ', "purple",
+        for chunk in status_iterator(chunks, __('reading sources... '), "purple",
                                      len(chunks), self.app.verbosity):
             tasks.add_task(read_process, chunk, merge)
 
         # make sure all threads have finished
-        logger.info(bold('waiting for workers...'))
+        logger.info(bold(__('waiting for workers...')))
         tasks.join()
 
     def read_doc(self, docname):

sphinx/builders/_epub_base.py

@@ -10,6 +10,7 @@
 
 import os
 import re
+import warnings
 from collections import namedtuple
 from os import path
 from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile
@@ -19,6 +20,7 @@ from docutils.utils import smartquotes
 
 from sphinx import addnodes
 from sphinx.builders.html import BuildInfo, StandaloneHTMLBuilder
+from sphinx.deprecation import RemovedInSphinx40Warning
 from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util import status_iterator
@@ -403,7 +405,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
         the format and resizing the image if necessary/possible.
         """
         ensuredir(path.join(self.outdir, self.imagedir))
-        for src in status_iterator(self.images, 'copying images... ', "brown",
+        for src in status_iterator(self.images, __('copying images... '), "brown",
                                    len(self.images), self.app.verbosity):
             dest = self.images[src]
             try:
@@ -470,16 +472,28 @@ class EpubBuilder(StandaloneHTMLBuilder):
         addctx['doctype'] = self.doctype
         super().handle_page(pagename, addctx, templatename, outfilename, event_arg)
 
-    def build_mimetype(self, outdir, outname):
+    def build_mimetype(self, outdir=None, outname='mimetype'):
         # type: (str, str) -> None
         """Write the metainfo file mimetype."""
+        if outdir:
+            warnings.warn('The arguments of EpubBuilder.build_mimetype() is deprecated.',
+                          RemovedInSphinx40Warning, stacklevel=2)
+        else:
+            outdir = self.outdir
+
         logger.info(__('writing %s file...'), outname)
         copy_asset_file(path.join(self.template_dir, 'mimetype'),
                         path.join(outdir, outname))
 
-    def build_container(self, outdir, outname):
+    def build_container(self, outdir=None, outname='META-INF/container.xml'):
         # type: (str, str) -> None
         """Write the metainfo file META-INF/container.xml."""
+        if outdir:
+            warnings.warn('The arguments of EpubBuilder.build_container() is deprecated.',
+                          RemovedInSphinx40Warning, stacklevel=2)
+        else:
+            outdir = self.outdir
+
         logger.info(__('writing %s file...'), outname)
         filename = path.join(outdir, outname)
         ensuredir(path.dirname(filename))
@@ -505,11 +519,17 @@ class EpubBuilder(StandaloneHTMLBuilder):
         metadata['guides'] = []
         return metadata
 
-    def build_content(self, outdir, outname):
+    def build_content(self, outdir=None, outname='content.opf'):
         # type: (str, str) -> None
         """Write the metainfo file content.opf It contains bibliographic data,
         a file list and the spine (the reading order).
         """
+        if outdir:
+            warnings.warn('The arguments of EpubBuilder.build_content() is deprecated.',
+                          RemovedInSphinx40Warning, stacklevel=2)
+        else:
+            outdir = self.outdir
+
         logger.info(__('writing %s file...'), outname)
         metadata = self.content_metadata()
 
@@ -686,9 +706,15 @@ class EpubBuilder(StandaloneHTMLBuilder):
         metadata['navpoints'] = navpoints
         return metadata
 
-    def build_toc(self, outdir, outname):
+    def build_toc(self, outdir=None, outname='toc.ncx'):
         # type: (str, str) -> None
         """Write the metainfo file toc.ncx."""
+        if outdir:
+            warnings.warn('The arguments of EpubBuilder.build_toc() is deprecated.',
+                          RemovedInSphinx40Warning, stacklevel=2)
+        else:
+            outdir = self.outdir
+
         logger.info(__('writing %s file...'), outname)
 
         if self.config.epub_tocscope == 'default':
@@ -707,13 +733,20 @@ class EpubBuilder(StandaloneHTMLBuilder):
                         path.join(outdir, outname),
                         self.toc_metadata(level, navpoints))
 
-    def build_epub(self, outdir, outname):
+    def build_epub(self, outdir=None, outname=None):
         # type: (str, str) -> None
         """Write the epub file.
 
         It is a zip file with the mimetype file stored uncompressed as the first
         entry.
         """
+        if outdir:
+            warnings.warn('The arguments of EpubBuilder.build_epub() is deprecated.',
+                          RemovedInSphinx40Warning, stacklevel=2)
+        else:
+            outdir = self.outdir
+            outname = self.config.epub_basename + '.epub'
+
         logger.info(__('writing %s file...'), outname)
         epub_filename = path.join(outdir, outname)
         with ZipFile(epub_filename, 'w', ZIP_DEFLATED) as epub:

sphinx/builders/applehelp.py

@@ -8,21 +8,21 @@
     :license: BSD, see LICENSE for details.
 """
 
-import html
-import pipes
 import plistlib
 import shlex
 import subprocess
 from os import path, environ
+from subprocess import CalledProcessError, PIPE, STDOUT
 
+from sphinx import package_dir
 from sphinx.builders.html import StandaloneHTMLBuilder
 from sphinx.errors import SphinxError
 from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util.console import bold  # type: ignore
-from sphinx.util.fileutil import copy_asset
+from sphinx.util.fileutil import copy_asset, copy_asset_file
 from sphinx.util.matching import Matcher
-from sphinx.util.osutil import copyfile, ensuredir, make_filename
+from sphinx.util.osutil import ensuredir, make_filename
 
 if False:
     # For type annotation
@@ -31,22 +31,7 @@ if False:
 
 
 logger = logging.getLogger(__name__)
-
+template_dir = path.join(package_dir, 'templates', 'applehelp')
-# False access page (used because helpd expects strict XHTML)
-access_page_template = '''\
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\
- "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <head>
-    <title>%(title)s</title>
-    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-    <meta name="robots" content="noindex" />
-    <meta http-equiv="refresh" content="0;url=%(toc)s" />
-  </head>
-  <body>
-  </body>
-</html>
-'''
 
 
 class AppleHelpIndexerFailed(SphinxError):
@@ -128,13 +113,17 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
         resources_dir = path.join(contents_dir, 'Resources')
         language_dir = path.join(resources_dir,
                                  self.config.applehelp_locale + '.lproj')
+        ensuredir(language_dir)
 
-        for d in [contents_dir, resources_dir, language_dir]:
+        self.build_info_plist(contents_dir)
-            ensuredir(d)
+        self.copy_applehelp_icon(resources_dir)
-
+        self.build_access_page(language_dir)
-        # Construct the Info.plist file
+        self.build_helpindex(language_dir)
-        toc = self.config.master_doc + self.out_suffix
+        self.do_codesign()
 
+    def build_info_plist(self, contents_dir):
+        # type: (str) -> None
+        """Construct the Info.plist file."""
         info_plist = {
             'CFBundleDevelopmentRegion': self.config.applehelp_dev_region,
             'CFBundleIdentifier': self.config.applehelp_bundle_id,
@@ -151,8 +140,7 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
         }
 
         if self.config.applehelp_icon is not None:
-            info_plist['HPDBookIconPath'] \
+            info_plist['HPDBookIconPath'] = path.basename(self.config.applehelp_icon)
-                = path.basename(self.config.applehelp_icon)
 
         if self.config.applehelp_kb_url is not None:
             info_plist['HPDBookKBProduct'] = self.config.applehelp_kb_product
@@ -162,34 +150,37 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
             info_plist['HPDBookRemoteURL'] = self.config.applehelp_remote_url
 
         logger.info(bold(__('writing Info.plist... ')), nonl=True)
-        with open(path.join(contents_dir, 'Info.plist'), 'wb') as fb:
+        with open(path.join(contents_dir, 'Info.plist'), 'wb') as f:
-            plistlib.dump(info_plist, fb)
+            plistlib.dump(info_plist, f)
         logger.info(__('done'))
 
-        # Copy the icon, if one is supplied
+    def copy_applehelp_icon(self, resources_dir):
+        # type: (str) -> None
+        """Copy the icon, if one is supplied."""
         if self.config.applehelp_icon:
             logger.info(bold(__('copying icon... ')), nonl=True)
 
             try:
-                copyfile(path.join(self.srcdir, self.config.applehelp_icon),
+                applehelp_icon = path.join(self.srcdir, self.config.applehelp_icon)
-                         path.join(resources_dir, info_plist['HPDBookIconPath']))
+                copy_asset_file(applehelp_icon, resources_dir)
-
                 logger.info(__('done'))
             except Exception as err:
-                logger.warning(__('cannot copy icon file %r: %s'),
+                logger.warning(__('cannot copy icon file %r: %s'), applehelp_icon, err)
-                               path.join(self.srcdir, self.config.applehelp_icon), err)
-                del info_plist['HPDBookIconPath']
 
-        # Build the access page
+    def build_access_page(self, language_dir):
+        # type: (str) -> None
+        """Build the access page."""
         logger.info(bold(__('building access page...')), nonl=True)
-        with open(path.join(language_dir, '_access.html'), 'w') as ft:
+        context = {
-            ft.write(access_page_template % {
+            'toc': self.config.master_doc + self.out_suffix,
-                'toc': html.escape(toc, quote=True),
+            'title': self.config.applehelp_title,
-                'title': html.escape(self.config.applehelp_title)
+        }
-            })
+        copy_asset_file(path.join(template_dir, '_access.html_t'), language_dir, context)
         logger.info(__('done'))
 
-        # Generate the help index
+    def build_helpindex(self, language_dir):
+        # type: (str) -> None
+        """Generate the help index."""
         logger.info(bold(__('generating help index... ')), nonl=True)
 
         args = [
@@ -213,25 +204,20 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
 
         if self.config.applehelp_disable_external_tools:
             logger.info(__('skipping'))
-
             logger.warning(__('you will need to index this help book with:\n  %s'),
-                           ' '.join([pipes.quote(arg) for arg in args]))
+                           ' '.join([shlex.quote(arg) for arg in args]))
         else:
             try:
-                p = subprocess.Popen(args,
+                subprocess.run(args, stdout=PIPE, stderr=STDOUT, check=True)
-                                     stdout=subprocess.PIPE,
+                logger.info(__('done'))
-                                     stderr=subprocess.STDOUT)
-
-                output = p.communicate()[0]
-
-                if p.returncode != 0:
-                    raise AppleHelpIndexerFailed(output)
-                else:
-                    logger.info(__('done'))
             except OSError:
                 raise AppleHelpIndexerFailed(__('Command not found: %s') % args[0])
+            except CalledProcessError as exc:
+                raise AppleHelpIndexerFailed(exc.stdout)
 
-        # If we've been asked to, sign the bundle
+    def do_codesign(self):
+        # type: () -> None
+        """If we've been asked to, sign the bundle."""
         if self.config.applehelp_codesign_identity:
             logger.info(bold(__('signing help book... ')), nonl=True)
 
@@ -248,21 +234,15 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
             if self.config.applehelp_disable_external_tools:
                 logger.info(__('skipping'))
                 logger.warning(__('you will need to sign this help book with:\n  %s'),
-                               ' '.join([pipes.quote(arg) for arg in args]))
+                               ' '.join([shlex.quote(arg) for arg in args]))
             else:
                 try:
-                    p = subprocess.Popen(args,
+                    subprocess.run(args, stdout=PIPE, stderr=STDOUT, check=True)
-                                         stdout=subprocess.PIPE,
+                    logger.info(__('done'))
-                                         stderr=subprocess.STDOUT)
-
-                    output = p.communicate()[0]
-
-                    if p.returncode != 0:
-                        raise AppleHelpCodeSigningFailed(output)
-                    else:
-                        logger.info(__('done'))
                 except OSError:
                     raise AppleHelpCodeSigningFailed(__('Command not found: %s') % args[0])
+                except CalledProcessError as exc:
+                    raise AppleHelpCodeSigningFailed(exc.stdout)
 
 
 def setup(app):

sphinx/builders/changes.py

@@ -67,7 +67,7 @@ class ChangesBuilder(Builder):
         if not changesets:
             logger.info(bold(__('no changes in version %s.') % version))
             return
-        logger.info(bold('writing summary file...'))
+        logger.info(bold(__('writing summary file...')))
         for changeset in changesets:
             if isinstance(changeset.descname, tuple):
                 descname = changeset.descname[0]

sphinx/builders/epub3.py

@@ -9,12 +9,14 @@
     :license: BSD, see LICENSE for details.
 """
 
+import warnings
 from collections import namedtuple
 from os import path
 
 from sphinx import package_dir
 from sphinx.builders import _epub_base
 from sphinx.config import ENUM
+from sphinx.deprecation import RemovedInSphinx40Warning
 from sphinx.locale import __
 from sphinx.util import logging, xmlname_checker
 from sphinx.util.fileutil import copy_asset_file
@@ -76,50 +78,18 @@ class Epub3Builder(_epub_base.EpubBuilder):
     def handle_finish(self):
         # type: () -> None
         """Create the metainfo files and finally the epub."""
-        self.validate_config_value()
         self.get_toc()
-        self.build_mimetype(self.outdir, 'mimetype')
+        self.build_mimetype()
-        self.build_container(self.outdir, 'META-INF/container.xml')
+        self.build_container()
-        self.build_content(self.outdir, 'content.opf')
+        self.build_content()
-        self.build_navigation_doc(self.outdir, 'nav.xhtml')
+        self.build_navigation_doc()
-        self.build_toc(self.outdir, 'toc.ncx')
+        self.build_toc()
-        self.build_epub(self.outdir, self.config.epub_basename + '.epub')
+        self.build_epub()
 
     def validate_config_value(self):
         # type: () -> None
-        # <package> lang attribute, dc:language
+        warnings.warn('Epub3Builder.validate_config_value() is deprecated.',
-        if not self.app.config.epub_language:
+                      RemovedInSphinx40Warning, stacklevel=2)
-            logger.warning(__('conf value "epub_language" (or "language") '
-                              'should not be empty for EPUB3'))
-        # <package> unique-identifier attribute
-        if not xmlname_checker().match(self.app.config.epub_uid):
-            logger.warning(__('conf value "epub_uid" should be XML NAME for EPUB3'))
-        # dc:title
-        if not self.app.config.epub_title:
-            logger.warning(__('conf value "epub_title" (or "html_title") '
-                              'should not be empty for EPUB3'))
-        # dc:creator
-        if not self.app.config.epub_author:
-            logger.warning(__('conf value "epub_author" should not be empty for EPUB3'))
-        # dc:contributor
-        if not self.app.config.epub_contributor:
-            logger.warning(__('conf value "epub_contributor" should not be empty for EPUB3'))
-        # dc:description
-        if not self.app.config.epub_description:
-            logger.warning(__('conf value "epub_description" should not be empty for EPUB3'))
-        # dc:publisher
-        if not self.app.config.epub_publisher:
-            logger.warning(__('conf value "epub_publisher" should not be empty for EPUB3'))
-        # dc:rights
-        if not self.app.config.epub_copyright:
-            logger.warning(__('conf value "epub_copyright" (or "copyright")'
-                              'should not be empty for EPUB3'))
-        # dc:identifier
-        if not self.app.config.epub_identifier:
-            logger.warning(__('conf value "epub_identifier" should not be empty for EPUB3'))
-        # meta ibooks:version
-        if not self.app.config.version:
-            logger.warning(__('conf value "version" should not be empty for EPUB3'))
 
     def content_metadata(self):
         # type: () -> Dict
@@ -202,9 +172,15 @@ class Epub3Builder(_epub_base.EpubBuilder):
         metadata['navlist'] = navlist
         return metadata
 
-    def build_navigation_doc(self, outdir, outname):
+    def build_navigation_doc(self, outdir=None, outname='nav.xhtml'):
         # type: (str, str) -> None
         """Write the metainfo file nav.xhtml."""
+        if outdir:
+            warnings.warn('The arguments of Epub3Builder.build_navigation_doc() '
+                          'is deprecated.', RemovedInSphinx40Warning, stacklevel=2)
+        else:
+            outdir = self.outdir
+
         logger.info(__('writing %s file...'), outname)
 
         if self.config.epub_tocscope == 'default':
@@ -226,6 +202,46 @@ class Epub3Builder(_epub_base.EpubBuilder):
             self.files.append(outname)
 
 
+def validate_config_values(app):
+    # type: (Sphinx) -> None
+    if app.builder.name != 'epub':
+        return
+
+    # <package> lang attribute, dc:language
+    if not app.config.epub_language:
+        logger.warning(__('conf value "epub_language" (or "language") '
+                          'should not be empty for EPUB3'))
+    # <package> unique-identifier attribute
+    if not xmlname_checker().match(app.config.epub_uid):
+        logger.warning(__('conf value "epub_uid" should be XML NAME for EPUB3'))
+    # dc:title
+    if not app.config.epub_title:
+        logger.warning(__('conf value "epub_title" (or "html_title") '
+                          'should not be empty for EPUB3'))
+    # dc:creator
+    if not app.config.epub_author:
+        logger.warning(__('conf value "epub_author" should not be empty for EPUB3'))
+    # dc:contributor
+    if not app.config.epub_contributor:
+        logger.warning(__('conf value "epub_contributor" should not be empty for EPUB3'))
+    # dc:description
+    if not app.config.epub_description:
+        logger.warning(__('conf value "epub_description" should not be empty for EPUB3'))
+    # dc:publisher
+    if not app.config.epub_publisher:
+        logger.warning(__('conf value "epub_publisher" should not be empty for EPUB3'))
+    # dc:rights
+    if not app.config.epub_copyright:
+        logger.warning(__('conf value "epub_copyright" (or "copyright")'
+                          'should not be empty for EPUB3'))
+    # dc:identifier
+    if not app.config.epub_identifier:
+        logger.warning(__('conf value "epub_identifier" should not be empty for EPUB3'))
+    # meta ibooks:version
+    if not app.config.version:
+        logger.warning(__('conf value "version" should not be empty for EPUB3'))
+
+
 def convert_epub_css_files(app, config):
     # type: (Sphinx, Config) -> None
     """This converts string styled epub_css_files to tuple styled one."""
@@ -281,6 +297,7 @@ def setup(app):
 
     # event handlers
     app.connect('config-inited', convert_epub_css_files)
+    app.connect('builder-inited', validate_config_values)
 
     return {
         'version': 'builtin',

sphinx/builders/html.py

@@ -882,7 +882,7 @@ class StandaloneHTMLBuilder(Builder):
                 elif not path.isfile(icontarget):
                     copyfile(path.join(self.confdir, self.config.html_favicon),
                              icontarget)
-            logger.info('done')
+            logger.info(__('done'))
         except OSError as err:
             logger.warning(__('cannot copy static file %r'), err)
 

sphinx/builders/latex/__init__.py

@@ -276,7 +276,7 @@ class LaTeXBuilder(Builder):
 
             doctree.settings = docsettings
             docwriter.write(doctree, destination)
-            logger.info("done")
+            logger.info(__("done"))
 
     def get_contentsname(self, indexfile):
         # type: (str) -> str

sphinx/builders/latex/compat.py

@@ -1,31 +0,0 @@
-"""
-    sphinx.builders.latex.compat
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-    Compatibility module for LaTeX writer.
-    This module will be removed after deprecation period.
-    Don't use components in this modules directly.
-
-    :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
-
-from sphinx.builders.latex.transforms import URI_SCHEMES, ShowUrlsTransform
-from sphinx.builders.latex.util import ExtBabel
-from sphinx.deprecation import (
-    RemovedInSphinx30Warning, RemovedInSphinx40Warning, deprecated_alias
-)
-
-
-deprecated_alias('sphinx.writers.latex',
-                 {
-                     'ShowUrlsTransform': ShowUrlsTransform,
-                     'URI_SCHEMES': URI_SCHEMES,
-                 },
-                 RemovedInSphinx30Warning)
-
-deprecated_alias('sphinx.writers.latex',
-                 {
-                     'ExtBabel': ExtBabel,
-                 },
-                 RemovedInSphinx40Warning)

sphinx/domains/cpp.py

@@ -22,6 +22,8 @@ from sphinx.domains import Domain, ObjType
 from sphinx.environment import NoUri
 from sphinx.locale import _, __
 from sphinx.roles import XRefRole
+from sphinx.transforms import SphinxTransform
+from sphinx.transforms.post_transforms import ReferencesResolver
 from sphinx.util import logging
 from sphinx.util.docfields import Field, GroupedField
 from sphinx.util.docutils import SphinxDirective
@@ -642,12 +644,12 @@ class ASTBase:
 
     def __repr__(self):
         # type: () -> str
-        return '<%s %s>' % (self.__class__.__name__, self)
+        return '<%s>' % self.__class__.__name__
 
 
 def _verify_description_mode(mode):
     # type: (str) -> None
-    if mode not in ('lastIsName', 'noneIsName', 'markType', 'param'):
+    if mode not in ('lastIsName', 'noneIsName', 'markType', 'markName', 'param'):
         raise Exception("Description mode '%s' is invalid." % mode)
 
 
@@ -2226,7 +2228,7 @@ class ASTNestedName(ASTBase):
         elif mode == 'param':
             name = str(self)
             signode += nodes.emphasis(name, name)
-        elif mode == 'markType' or mode == 'lastIsName':
+        elif mode == 'markType' or mode == 'lastIsName' or mode == 'markName':
             # Each element should be a pending xref targeting the complete
             # prefix. however, only the identifier part should be a link, such
             # that template args can be a link as well.
@@ -3720,6 +3722,14 @@ class ASTNamespace(ASTBase):
         self.nestedName = nestedName
         self.templatePrefix = templatePrefix
 
+    def _stringify(self, transform):
+        # type: (Callable[[Any], str]) -> str
+        res = []
+        if self.templatePrefix:
+            res.append(transform(self.templatePrefix))
+        res.append(transform(self.nestedName))
+        return ''.join(res)
+
 
 class SymbolLookupResult:
     def __init__(self, symbols, parentSymbol, identOrOp, templateParams, templateArgs):
@@ -4312,7 +4322,7 @@ class Symbol:
 
     def find_name(self, nestedName, templateDecls, typ, templateShorthand,
                   matchSelf, recurseInAnon):
-        # type: (ASTNestedName, List[Any], str, bool, bool, bool) -> Symbol
+        # type: (ASTNestedName, List[Any], str, bool, bool, bool) -> List[Symbol]
         # templateShorthand: missing template parameter lists for templates is ok
 
         def onMissingQualifiedSymbol(parentSymbol, identOrOp, templateParams, templateArgs):
@@ -4335,18 +4345,19 @@ class Symbol:
             # if it was a part of the qualification that could not be found
             return None
 
-        # TODO: hmm, what if multiple symbols match?
+        res = list(lookupResult.symbols)
-        try:
+        if len(res) != 0:
-            return next(lookupResult.symbols)
+            return res
-        except StopIteration:
-            pass
 
         # try without template params and args
         symbol = lookupResult.parentSymbol._find_first_named_symbol(
             lookupResult.identOrOp, None, None,
             templateShorthand=templateShorthand, matchSelf=matchSelf,
             recurseInAnon=recurseInAnon, correctPrimaryTemplateArgs=False)
-        return symbol
+        if symbol is not None:
+            return [symbol]
+        else:
+            return None
 
     def find_declaration(self, declaration, typ, templateShorthand,
                          matchSelf, recurseInAnon):
@@ -4386,6 +4397,8 @@ class Symbol:
                              docname='fakeDocnameForQuery')
         queryId = declaration.get_newest_id()
         for symbol in symbols:
+            if symbol.declaration is None:
+                continue
             candId = symbol.declaration.get_newest_id()
             if candId == queryId:
                 querySymbol.remove()
@@ -6695,6 +6708,143 @@ class CPPNamespacePopObject(SphinxDirective):
         return []
 
 
+class AliasNode(nodes.Element):
+    def __init__(self, sig, warnEnv):
+        """
+        :param sig: The name or function signature to alias.
+        :param warnEnv: An object which must have the following attributes:
+            env: a Sphinx environment
+            whatever DefinitionParser requires of warnEnv
+        """
+        super().__init__()
+        self.sig = sig
+        env = warnEnv.env
+        if 'cpp:parent_symbol' not in env.temp_data:
+            root = env.domaindata['cpp']['root_symbol']
+            env.temp_data['cpp:parent_symbol'] = root
+        self.parentKey = env.temp_data['cpp:parent_symbol'].get_lookup_key()
+        try:
+            parser = DefinitionParser(sig, warnEnv, warnEnv.env.config)
+            self.ast, self.isShorthand = parser.parse_xref_object()
+            parser.assert_end()
+        except DefinitionError as e:
+            warnEnv.warn(e)
+            self.ast = None
+
+
+class AliasTransform(SphinxTransform):
+    default_priority = ReferencesResolver.default_priority - 1
+
+    def apply(self, **kwargs):
+        # type: (Any) -> None
+        for node in self.document.traverse(AliasNode):
+            sig = node.sig
+            ast = node.ast
+            if ast is None:
+                # could not be parsed, so stop here
+                signode = addnodes.desc_signature(sig, '')
+                signode['first'] = False
+                signode.clear()
+                signode += addnodes.desc_name(sig, sig)
+                node.replace_self(signode)
+                continue
+
+            isShorthand = node.isShorthand
+            parentKey = node.parentKey
+            rootSymbol = self.env.domains['cpp'].data['root_symbol']
+            parentSymbol = rootSymbol.direct_lookup(parentKey)
+            if not parentSymbol:
+                print("Target: ", sig)
+                print("ParentKey: ", parentKey)
+                print(rootSymbol.dump(1))
+            assert parentSymbol  # should be there
+
+            symbols = []  # type: List[Symbol]
+            if isShorthand:
+                ns = ast  # type: ASTNamespace
+                name = ns.nestedName
+                if ns.templatePrefix:
+                    templateDecls = ns.templatePrefix.templates
+                else:
+                    templateDecls = []
+                symbols = parentSymbol.find_name(name, templateDecls, 'any',
+                                                 templateShorthand=True,
+                                                 matchSelf=True, recurseInAnon=True)
+                if symbols is None:
+                    symbols = []
+            else:
+                decl = ast  # type: ASTDeclaration
+                name = decl.name
+                s = parentSymbol.find_declaration(decl, 'any',
+                                                  templateShorthand=True,
+                                                  matchSelf=True, recurseInAnon=True)
+                if s is not None:
+                    symbols.append(s)
+
+            symbols = [s for s in symbols if s.declaration is not None]
+
+            if len(symbols) == 0:
+                signode = addnodes.desc_signature(sig, '')
+                signode['first'] = False
+                node.append(signode)
+                signode.clear()
+                signode += addnodes.desc_name(sig, sig)
+
+                logger.warning("Could not find C++ declaration for alias '%s'." % ast,
+                               location=node)
+                node.replace_self(signode)
+            else:
+                nodes = []
+                options = dict()
+                options['tparam-line-spec'] = False
+                for s in symbols:
+                    signode = addnodes.desc_signature(sig, '')
+                    signode['first'] = False
+                    nodes.append(signode)
+                    s.declaration.describe_signature(signode, 'markName', self.env, options)
+                node.replace_self(nodes)
+
+
+class CPPAliasObject(ObjectDescription):
+    option_spec = {}  # type: Dict
+
+    def warn(self, msg):
+        # type: (Union[str, Exception]) -> None
+        self.state_machine.reporter.warning(msg, line=self.lineno)
+
+    def run(self):
+        # type: () -> List[nodes.Node]
+        """
+        On purpose this doesn't call the ObjectDescription version, but is based on it.
+        Each alias signature may expand into multiple real signatures (an overload set).
+        The code is therefore based on the ObjectDescription version.
+        """
+        if ':' in self.name:
+            self.domain, self.objtype = self.name.split(':', 1)
+        else:
+            self.domain, self.objtype = '', self.name
+
+        node = addnodes.desc()
+        node.document = self.state.document
+        node['domain'] = self.domain
+        # 'desctype' is a backwards compatible attribute
+        node['objtype'] = node['desctype'] = self.objtype
+        node['noindex'] = True
+
+        self.names = []  # type: List[str]
+        signatures = self.get_signatures()
+        for i, sig in enumerate(signatures):
+            node.append(AliasNode(sig, self))
+
+        contentnode = addnodes.desc_content()
+        node.append(contentnode)
+        self.before_content()
+        self.state.nested_parse(self.content, self.content_offset, contentnode)
+        self.env.temp_data['object'] = None
+        self.after_content()
+        return [node]
+
+
 class CPPXRefRole(XRefRole):
     def process_link(self, env, refnode, has_explicit_title, title, target):
         # type: (BuildEnvironment, nodes.Element, bool, str, str) -> Tuple[str, str]
@@ -6790,7 +6940,8 @@ class CPPDomain(Domain):
         'enumerator': CPPEnumeratorObject,
         'namespace': CPPNamespaceObject,
         'namespace-push': CPPNamespacePushObject,
-        'namespace-pop': CPPNamespacePopObject
+        'namespace-pop': CPPNamespacePopObject,
+        'alias': CPPAliasObject
     }
     roles = {
         'any': CPPXRefRole(),
@@ -6917,9 +7068,11 @@ class CPPDomain(Domain):
                 templateDecls = ns.templatePrefix.templates
             else:
                 templateDecls = []
-            s = parentSymbol.find_name(name, templateDecls, typ,
+            symbols = parentSymbol.find_name(name, templateDecls, typ,
-                                       templateShorthand=True,
+                                             templateShorthand=True,
-                                       matchSelf=True, recurseInAnon=True)
+                                             matchSelf=True, recurseInAnon=True)
+            # just refer to the arbitrarily first symbol
+            s = None if symbols is None else symbols[0]
         else:
             decl = ast  # type: ASTDeclaration
             name = decl.name
@@ -7058,6 +7211,7 @@ def setup(app):
     app.add_config_value("cpp_index_common_prefix", [], 'env')
     app.add_config_value("cpp_id_attributes", [], 'env')
     app.add_config_value("cpp_paren_attributes", [], 'env')
+    app.add_post_transform(AliasTransform)
 
     return {
         'version': 'builtin',

sphinx/ext/autosummary/__init__.py

@@ -253,9 +253,9 @@ class Autosummary(SphinxDirective):
                 docname = posixpath.normpath(posixpath.join(dirname, docname))
                 if docname not in self.env.found_docs:
                     if excluded(self.env.doc2path(docname, None)):
-                        logger.warning('toctree references excluded document %r' % docname)
+                        logger.warning(__('toctree references excluded document %r'), docname)
                     else:
-                        logger.warning('toctree references unknown document %r' % docname)
+                        logger.warning(__('toctree references unknown document %r'), docname)
                 docnames.append(docname)
 
             tocnode = addnodes.toctree()
@@ -288,7 +288,7 @@ class Autosummary(SphinxDirective):
             try:
                 real_name, obj, parent, modname = import_by_name(name, prefixes=prefixes)
             except ImportError:
-                logger.warning('failed to import %s' % name)
+                logger.warning(__('failed to import %s'), name)
                 items.append((name, '', '', name))
                 continue
 
@@ -303,11 +303,11 @@ class Autosummary(SphinxDirective):
             doccls = get_documenter(self.env.app, obj, parent)
             documenter = doccls(self.bridge, full_name)
             if not documenter.parse_name():
-                logger.warning('failed to parse name %s' % real_name)
+                logger.warning(__('failed to parse name %s'), real_name)
                 items.append((display_name, '', '', real_name))
                 continue
             if not documenter.import_object():
-                logger.warning('failed to import object %s' % real_name)
+                logger.warning(__('failed to import object %s'), real_name)
                 items.append((display_name, '', '', real_name))
                 continue
             if documenter.options.members and not documenter.check_module():

sphinx/ext/intersphinx.py

@@ -179,7 +179,7 @@ def fetch_inventory(app, uri, inv):
         if hasattr(f, 'url'):
             newinv = f.url  # type: ignore
             if inv != newinv:
-                logger.info('intersphinx inventory has moved: %s -> %s', inv, newinv)
+                logger.info(__('intersphinx inventory has moved: %s -> %s'), inv, newinv)
 
                 if uri in (inv, path.dirname(inv), path.dirname(inv) + '/'):
                     uri = path.dirname(newinv)
@@ -214,7 +214,7 @@ def load_mappings(app):
             if '://' not in inv or uri not in inventories.cache \
                     or inventories.cache[uri][1] < cache_time:
                 safe_inv_url = _get_safe_url(inv)
-                logger.info('loading intersphinx inventory from %s...', safe_inv_url)
+                logger.info(__('loading intersphinx inventory from %s...'), safe_inv_url)
                 try:
                     invdata = fetch_inventory(app, uri, inv)
                 except Exception as err:
@@ -229,8 +229,8 @@ def load_mappings(app):
         if failures == []:
             pass
         elif len(failures) < len(invs):
-            logger.info("encountered some issues with some of the inventories,"
+            logger.info(__("encountered some issues with some of the inventories,"
-                        " but they had working alternatives:")
+                           " but they had working alternatives:"))
             for fail in failures:
                 logger.info(*fail)
         else:

sphinx/ext/viewcode.py

@@ -16,7 +16,7 @@ from docutils import nodes
 import sphinx
 from sphinx import addnodes
 from sphinx.deprecation import RemovedInSphinx30Warning
-from sphinx.locale import _
+from sphinx.locale import _, __
 from sphinx.pycode import ModuleAnalyzer
 from sphinx.util import get_full_modname, logging, status_iterator
 from sphinx.util.nodes import make_refnode
@@ -158,7 +158,7 @@ def collect_pages(app):
 
     for modname, entry in status_iterator(
             sorted(env._viewcode_modules.items()),  # type: ignore
-            'highlighting module code... ', "blue",
+            __('highlighting module code... '), "blue",
             len(env._viewcode_modules),  # type: ignore
             app.verbosity, lambda x: x[0]):
         if not entry:

sphinx/templates/applehelp/_access.html_t

@@ -0,0 +1,12 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <title>{{ title|e }}</title>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    <meta name="robots" content="noindex" />
+    <meta http-equiv="refresh" content="0;url={{ toc|e }}" />
+  </head>
+  <body>
+  </body>
+</html>

sphinx/texinputs/sphinx.sty

@@ -1059,8 +1059,6 @@
   \let\normalsize\footnotesize\let\@parboxrestore\relax
   \def\spx@abovecaptionskip{\sphinxverbatimsmallskipamount}%
 }
-% needed to create wrapper environments of fancyvrb's Verbatim
-\newcommand*{\sphinxVerbatimEnvironment}{\gdef\FV@EnvironName{sphinxVerbatim}}
 \newcommand*{\sphinxverbatimsmallskipamount}{\smallskipamount}
 % serves to implement line highlighting and line wrapping
 \newcommand\sphinxFancyVerbFormatLine[1]{%
@@ -1165,8 +1163,7 @@
     \let\sphinxVerbatimFormatLine\sphinxVerbatimFormatLineNoWrap
   \fi
   \let\FancyVerbFormatLine\sphinxFancyVerbFormatLine
-  % workaround to fancyvrb's check of \@currenvir
+  \VerbatimEnvironment
-  \let\VerbatimEnvironment\sphinxVerbatimEnvironment
   % workaround to fancyvrb's check of current list depth
   \def\@toodeep {\advance\@listdepth\@ne}%
   % The list environment is needed to control perfectly the vertical space.
@@ -1213,8 +1210,7 @@
 }
 \newenvironment {sphinxVerbatimNoFrame}
   {\spx@opt@verbatimwithframefalse
-   % needed for fancyvrb as literal code will end in \end{sphinxVerbatimNoFrame}
+   \VerbatimEnvironment
-   \def\sphinxVerbatimEnvironment{\gdef\FV@EnvironName{sphinxVerbatimNoFrame}}%
    \begin{sphinxVerbatim}}
   {\end{sphinxVerbatim}}
 \newenvironment {sphinxVerbatimintable}
@@ -1227,7 +1223,7 @@
    \let\caption\sphinxfigcaption
    % reduce above caption skip
    \def\spx@abovecaptionskip{\sphinxverbatimsmallskipamount}%
-   \def\sphinxVerbatimEnvironment{\gdef\FV@EnvironName{sphinxVerbatimintable}}%
+   \VerbatimEnvironment
    \begin{sphinxVerbatim}}
   {\end{sphinxVerbatim}}
 

sphinx/writers/latex.py

@@ -22,10 +22,9 @@ from docutils import nodes, writers
 
 from sphinx import addnodes
 from sphinx import highlighting
-from sphinx.builders.latex.nodes import (
+from sphinx.deprecation import (
-    HYPERLINK_SUPPORT_NODES, captioned_literal_block, footnotetext
+    RemovedInSphinx30Warning, RemovedInSphinx40Warning, deprecated_alias
 )
-from sphinx.deprecation import RemovedInSphinx30Warning, RemovedInSphinx40Warning
 from sphinx.domains.std import StandardDomain
 from sphinx.errors import SphinxError
 from sphinx.locale import admonitionlabels, _, __
@@ -1137,8 +1136,8 @@ class LaTeXTranslator(SphinxTranslator):
         if self.next_table_colspec:
             self.table.colspec = '{%s}\n' % self.next_table_colspec
             if 'colwidths-given' in node.get('classes', []):
-                logger.info('both tabularcolumns and :widths: option are given. '
+                logger.info(__('both tabularcolumns and :widths: option are given. '
-                            ':widths: is ignored.', location=node)
+                               ':widths: is ignored.'), location=node)
         self.next_table_colspec = None
 
     def depart_table(self, node):
@@ -2603,4 +2602,22 @@ class LaTeXTranslator(SphinxTranslator):
 
 
 # Import old modules here for compatibility
-import sphinx.builders.latex.compat  # NOQA
+from sphinx.builders.latex.transforms import URI_SCHEMES, ShowUrlsTransform  # NOQA
+from sphinx.builders.latex.util import ExtBabel  # NOQA
+
+
+deprecated_alias('sphinx.writers.latex',
+                 {
+                     'ShowUrlsTransform': ShowUrlsTransform,
+                     'URI_SCHEMES': URI_SCHEMES,
+                 },
+                 RemovedInSphinx30Warning)
+deprecated_alias('sphinx.writers.latex',
+                 {
+                     'ExtBabel': ExtBabel,
+                 },
+                 RemovedInSphinx40Warning)
+
+# FIXME: Workaround to avoid circular import
+# refs: https://github.com/sphinx-doc/sphinx/issues/5433
+from sphinx.builders.latex.nodes import HYPERLINK_SUPPORT_NODES, captioned_literal_block, footnotetext  # NOQA