Merge branch '3.x'

CHANGES

@@ -122,6 +122,7 @@ Features added
   :event:`html-page-context` event
 * #6550: html: Allow to use HTML permalink texts via
   :confval:`html_permalinks_icon`
+* #1638: html: Add permalink icons to glossary terms
 * #8649: imgconverter: Skip availability check if builder supports the image
   type
 * #8573: napoleon: Allow to change the style of custom sections using
@@ -130,6 +131,7 @@ Features added
   references when :confval:`napoleon_preprocess_types` enabled
 * #6241: mathjax: Include mathjax.js only on the document using equations
 * #8651: std domain: cross-reference for a rubric having inline item is broken
+* #7642: std domain: Optimize case-insensitive match of term
 * #8681: viewcode: Support incremental build
 * #8132: Add :confval:`project_copyright` as an alias of :confval:`copyright`
 * #207: Now :confval:`highlight_language` supports multiple languages
@@ -150,28 +152,41 @@ Bugs fixed
 * #8652: autodoc: All variable comments in the module are ignored if the module
   contains invalid type comments
 * #8693: autodoc: Default values for overloaded functions are rendered as string
+* #8134: autodoc: crashes when mocked decorator takes arguments
 * #8306: autosummary: mocked modules are documented as empty page when using
   :recursive: option
 * #8618: html: kbd role produces incorrect HTML when compound-key separators (-,
   + or ^) are used as keystrokes
 * #8629: html: A type warning for html_use_opensearch is shown twice
 * #8714: html: kbd role with "Caps Lock" rendered incorrectly
+* #8123: html search: fix searching for terms containing + (Requires a custom
+  search language that does not split on +)
 * #8665: html theme: Could not override globaltoc_maxdepth in theme.conf
+* #8745: i18n: crashes with KeyError when translation message adds a new auto
+  footnote reference
 * #4304: linkcheck: Fix race condition that could lead to checking the
   availability of the same URL twice
+* #7118: sphinx-quickstart: questionare got Mojibake if libreadline unavailable
 * #8094: texinfo: image files on the different directory with document are not
   copied
 * #8720: viewcode: module pages are generated for epub on incremental build
 * #8704: viewcode: anchors are generated in incremental build after singlehtml
+* #8756: viewcode: highlighted code is generated even if not referenced
 * #8671: :confval:`highlight_options` is not working
 * #8341: C, fix intersphinx lookup types for names in declarations.
 * C, C++: in general fix intersphinx and role lookup types.
 * #8683: :confval:`html_last_updated_fmt` does not support UTC offset (%z)
 * #8683: :confval:`html_last_updated_fmt` generates wrong time zone for %Z
 * #1112: ``download`` role creates duplicated copies when relative path is
   specified
+* #7576: LaTeX with French babel and memoir crash: "Illegal parameter number
+  in definition of ``\FNH@prefntext``"
+* #8214: LaTeX: The :rst:role:`index` role and the glossary generate duplicate
+  entries in the LaTeX index (if both used for same term)
 * #8735: LaTeX: wrong internal links in pdf to captioned code-blocks when
   :confval:`numfig` is not True
+* #8442: LaTeX: some indexed terms are ignored when using xelatex engine
+  (or pdflatex and :confval:`latex_use_xindy` set to True) with memoir class
 
 Testing
 --------

doc/changes.rst

@@ -8,4 +8,9 @@
 Changelog
 =========
 
+.. raw:: latex
+
+   \hypersetup{bookmarksdepth=1}% pdf bookmarks
+   \addtocontents{toc}{\protect\setcounter{tocdepth}{1}}%
+
 .. include:: ../CHANGES

doc/conf.py

@@ -58,8 +58,27 @@
 latex_logo = '_static/sphinx.png'
 latex_elements = {
     'fontenc': r'\usepackage[LGR,X2,T1]{fontenc}',
-    'passoptionstopackages': '\\PassOptionsToPackage{svgnames}{xcolor}',
-    'preamble': '\\DeclareUnicodeCharacter{229E}{\\ensuremath{\\boxplus}}',
+    'fontpkg': r'''
+\usepackage[sc]{mathpazo}
+\usepackage[scaled]{helvet}
+\usepackage{courier}
+\substitutefont{LGR}{\rmdefault}{cmr}
+\substitutefont{LGR}{\sfdefault}{cmss}
+\substitutefont{LGR}{\ttdefault}{cmtt}
+\substitutefont{X2}{\rmdefault}{cmr}
+\substitutefont{X2}{\sfdefault}{cmss}
+\substitutefont{X2}{\ttdefault}{cmtt}
+''',
+    'passoptionstopackages': r'''
+\PassOptionsToPackage{svgnames}{xcolor}
+\PassOptionsToPackage{bookmarksdepth=3}{hyperref}% depth of pdf bookmarks
+''',
+    'preamble': r'''
+\DeclareUnicodeCharacter{229E}{\ensuremath{\boxplus}}
+\setcounter{tocdepth}{3}%    depth of what is kept from toc file
+\setcounter{secnumdepth}{1}% depth of section numbering
+''',
+    'fvset': '\\fvset{fontsize=auto}',
     # fix missing index entry due to RTD doing only once pdflatex after makeindex
     'printindex': r'''
 \IfFileExists{\jobname.ind}

doc/usage/extensions/index.rst

@@ -46,14 +46,15 @@ organization. If you wish to include your extension in this organization,
 simply follow the instructions provided in the `github-administration`__
 project. This is optional and there are several extensions hosted elsewhere.
 The `awesome-sphinxdoc`__ project contains a curated list of Sphinx packages,
-and many packages use the ``Framework :: Sphinx :: Extension`` and
-``Framework :: Sphinx :: Theme`` `trove classifiers`__ for Sphinx extensions
-and themes, respectively.
+and many packages use the `Framework :: Sphinx :: Extension`__ and
+`Framework :: Sphinx :: Theme`__ trove classifiers for Sphinx extensions and
+themes, respectively.
 
 .. __: https://github.com/sphinx-contrib/
 .. __: https://github.com/sphinx-contrib/github-administration
 .. __: https://github.com/yoloseem/awesome-sphinxdoc
-.. __: https://pypi.org/classifiers/
+.. __: https://pypi.org/search/?c=Framework+%3A%3A+Sphinx+%3A%3A+Extension
+.. __: https://pypi.org/search/?c=Framework+%3A%3A+Sphinx+%3A%3A+Theme
 
 Where to put your own extensions?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

karma.conf.js

@@ -18,6 +18,7 @@ module.exports = function(config) {
       'sphinx/themes/basic/static/underscore.js',
       'sphinx/themes/basic/static/jquery.js',
       'sphinx/themes/basic/static/doctools.js',
+      'sphinx/themes/basic/static/searchtools.js',
       'tests/js/*.js'
     ],
 

sphinx/application.py

@@ -494,31 +494,34 @@ def add_config_value(self, name: str, default: Any, rebuild: Union[bool, str],
         """Register a configuration value.
 
         This is necessary for Sphinx to recognize new values and set default
-        values accordingly.  The *name* should be prefixed with the extension
-        name, to avoid clashes.  The *default* value can be any Python object.
-        The string value *rebuild* must be one of those values:
+        values accordingly.
 
-        * ``'env'`` if a change in the setting only takes effect when a
-          document is parsed -- this means that the whole environment must be
-          rebuilt.
-        * ``'html'`` if a change in the setting needs a full rebuild of HTML
-          documents.
-        * ``''`` if a change in the setting will not need any special rebuild.
 
-        The *types* value takes a list of types that describes the type of
-        configuration value.  For example, ``[str]`` is used to describe a
-        configuration that takes string value.
+        :param name: The name of configuration value.  It is recommended to be prefixed
+                     with the extension name (ex. ``html_logo``, ``epub_title``)
+        :param default: The default value of the configuration.
+        :param rebuild: The condition of rebuild.  It must be one of those values:
 
-        .. versionchanged:: 0.6
-           Changed *rebuild* from a simple boolean (equivalent to ``''`` or
-           ``'env'``) to a string.  However, booleans are still accepted and
-           converted internally.
+                        * ``'env'`` if a change in the setting only takes effect when a
+                          document is parsed -- this means that the whole environment must be
+                          rebuilt.
+                        * ``'html'`` if a change in the setting needs a full rebuild of HTML
+                          documents.
+                        * ``''`` if a change in the setting will not need any special rebuild.
+        :param types: The type of configuration value.  A list of types can be specified.  For
+                      example, ``[str]`` is used to describe a configuration that takes string
+                      value.
 
         .. versionchanged:: 0.4
            If the *default* value is a callable, it will be called with the
            config object as its argument in order to get the default value.
            This can be used to implement config values whose default depends on
            other values.
+
+        .. versionchanged:: 0.6
+           Changed *rebuild* from a simple boolean (equivalent to ``''`` or
+           ``'env'``) to a string.  However, booleans are still accepted and
+           converted internally.
         """
         logger.debug('[app] adding config value: %r',
                      (name, default, rebuild) + ((types,) if types else ()))
@@ -530,6 +533,8 @@ def add_event(self, name: str) -> None:
         """Register an event called *name*.
 
         This is needed to be able to emit it.
+
+        :param name: The name of the event
         """
         logger.debug('[app] adding event: %r', name)
         self.events.add(name)
@@ -560,6 +565,11 @@ def add_node(self, node: "Type[Element]", override: bool = False,
         This is necessary for Docutils internals.  It may also be used in the
         future to validate nodes in the parsed documents.
 
+        :param node: A node class
+        :param kwargs: Visitor functions for each builder (see below)
+        :param override: If true, install the node forcedly even if another node is already
+                         installed as the same name
+
         Node visitor functions for the Sphinx HTML, LaTeX, text and manpage
         writers can be given as keyword arguments: the keyword should be one or
         more of ``'html'``, ``'latex'``, ``'text'``, ``'man'``, ``'texinfo'``
@@ -581,9 +591,6 @@ def depart_math_html(self, node):
         Obviously, translators for which you don't specify visitor methods will
         choke on the node when encountered in a document to translate.
 
-        If *override* is True, the given *node* is forcedly installed even if
-        a node having the same name is already installed.
-
         .. versionchanged:: 0.5
            Added the support for keyword arguments giving visit functions.
         """
@@ -603,24 +610,21 @@ def add_enumerable_node(self, node: "Type[Element]", figtype: str,
         Sphinx numbers the node automatically. And then the users can refer it
         using :rst:role:`numref`.
 
-        *figtype* is a type of enumerable nodes.  Each figtypes have individual
-        numbering sequences.  As a system figtypes, ``figure``, ``table`` and
-        ``code-block`` are defined.  It is able to add custom nodes to these
-        default figtypes.  It is also able to define new custom figtype if new
-        figtype is given.
-
-        *title_getter* is a getter function to obtain the title of node.  It
-        takes an instance of the enumerable node, and it must return its title
-        as string.  The title is used to the default title of references for
-        :rst:role:`ref`.  By default, Sphinx searches
-        ``docutils.nodes.caption`` or ``docutils.nodes.title`` from the node as
-        a title.
-
-        Other keyword arguments are used for node visitor functions. See the
-        :meth:`.Sphinx.add_node` for details.
-
-        If *override* is True, the given *node* is forcedly installed even if
-        a node having the same name is already installed.
+        :param node: A node class
+        :param figtype: The type of enumerable nodes.  Each figtypes have individual numbering
+                        sequences.  As a system figtypes, ``figure``, ``table`` and
+                        ``code-block`` are defined.  It is able to add custom nodes to these
+                        default figtypes.  It is also able to define new custom figtype if new
+                        figtype is given.
+        :param title_getter: A getter function to obtain the title of node.  It takes an
+                             instance of the enumerable node, and it must return its title as
+                             string.  The title is used to the default title of references for
+                             :rst:role:`ref`.  By default, Sphinx searches
+                             ``docutils.nodes.caption`` or ``docutils.nodes.title`` from the
+                             node as a title.
+        :param kwargs: Visitor functions for each builder (same as :meth:`add_node`)
+        :param override: If true, install the node forcedly even if another node is already
+                         installed as the same name
 
         .. versionadded:: 1.4
         """
@@ -679,7 +683,7 @@ def add_role(self, name: str, role: Any, override: bool = False) -> None:
         """Register a Docutils role.
 
         :param name: The name of role
-        :param cls: A role function
+        :param role: A role function
         :param override: If true, install the role forcedly even if another role is already
                          installed as the same name
 
@@ -720,11 +724,9 @@ def add_generic_role(self, name: str, nodeclass: Any, override: bool = False) ->
     def add_domain(self, domain: "Type[Domain]", override: bool = False) -> None:
         """Register a domain.
 
-        Make the given *domain* (which must be a class; more precisely, a
-        subclass of :class:`~sphinx.domains.Domain`) known to Sphinx.
-
-        If *override* is True, the given *domain* is forcedly installed even if
-        a domain having the same name is already installed.
+        :param domain: A domain class
+        :param override: If true, install the domain forcedly even if another domain
+                         is already installed as the same name
 
         .. versionadded:: 1.0
         .. versionchanged:: 1.8
@@ -739,8 +741,11 @@ def add_directive_to_domain(self, domain: str, name: str,
         Like :meth:`add_directive`, but the directive is added to the domain
         named *domain*.
 
-        If *override* is True, the given *directive* is forcedly installed even if
-        a directive named as *name* is already installed.
+        :param domain: The name of target domain
+        :param name: A name of directive
+        :param cls: A directive class
+        :param override: If true, install the directive forcedly even if another directive
+                         is already installed as the same name
 
         .. versionadded:: 1.0
         .. versionchanged:: 1.8
@@ -755,8 +760,11 @@ def add_role_to_domain(self, domain: str, name: str, role: Union[RoleFunction, X
         Like :meth:`add_role`, but the role is added to the domain named
         *domain*.
 
-        If *override* is True, the given *role* is forcedly installed even if
-        a role named as *name* is already installed.
+        :param domain: The name of target domain
+        :param name: A name of role
+        :param role: A role function
+        :param override: If true, install the role forcedly even if another role is already
+                         installed as the same name
 
         .. versionadded:: 1.0
         .. versionchanged:: 1.8
@@ -768,11 +776,12 @@ def add_index_to_domain(self, domain: str, index: "Type[Index]", override: bool
                             ) -> None:
         """Register a custom index for a domain.
 
-        Add a custom *index* class to the domain named *domain*.  *index* must
-        be a subclass of :class:`~sphinx.domains.Index`.
+        Add a custom *index* class to the domain named *domain*.
 
-        If *override* is True, the given *index* is forcedly installed even if
-        an index having the same name is already installed.
+        :param domain: The name of target domain
+        :param index: A index class
+        :param override: If true, install the index forcedly even if another index is
+                         already installed as the same name
 
         .. versionadded:: 1.0
         .. versionchanged:: 1.8
@@ -893,6 +902,8 @@ def add_transform(self, transform: "Type[Transform]") -> None:
         the list of transforms that are applied after Sphinx parses a reST
         document.
 
+        :param transform: A transform class
+
         .. list-table:: priority range categories for Sphinx transforms
            :widths: 20,80
 
@@ -925,6 +936,8 @@ def add_post_transform(self, transform: "Type[Transform]") -> None:
         Add the standard docutils :class:`Transform` subclass *transform* to
         the list of transforms that are applied before Sphinx writes a
         document.
+
+        :param transform: A transform class
         """
         self.registry.add_post_transform(transform)
 
@@ -1196,9 +1209,10 @@ def add_html_math_renderer(self, name: str,
     def add_message_catalog(self, catalog: str, locale_dir: str) -> None:
         """Register a message catalog.
 
-        The *catalog* is a name of catalog, and *locale_dir* is a base path
-        of message catalog.  For more details, see
-        :func:`sphinx.locale.get_translation()`.
+        :param catalog: A name of catalog
+        :param locale_dir: The base path of message catalog
+
+        For more details, see :func:`sphinx.locale.get_translation()`.
 
         .. versionadded:: 1.8
         """
@@ -1209,7 +1223,7 @@ def add_message_catalog(self, catalog: str, locale_dir: str) -> None:
     def is_parallel_allowed(self, typ: str) -> bool:
         """Check parallel processing is allowed or not.
 
-        ``typ`` is a type of processing; ``'read'`` or ``'write'``.
+        :param typ: A type of processing; ``'read'`` or ``'write'``.
         """
         if typ == 'read':
             attrname = 'parallel_read_safe'