Merge branch '3.x' into 8103_cached_property

.github/ISSUE_TEMPLATE/config.yml

@@ -2,5 +2,8 @@
 blank_issues_enabled: false  # default: true
 contact_links:
 - name: Question
+  url: https://stackoverflow.com/questions/tagged/python-sphinx
+  about: For Q&A purpose, please use Stackoverflow with the tag python-sphinx
+- name: Discussion
   url: https://groups.google.com/forum/#!forum/sphinx-users
-  about: For Q&A purpose, please use sphinx-users mailing list.
+  about: For general discussion, please use sphinx-users mailing list.

CHANGES

@@ -13,17 +13,24 @@ Deprecated
 Features added
 --------------
 
+* #8100: html: Show a better error message for failures on copying
+  html_static_files
+
 Bugs fixed
 ----------
 
+* #8085: i18n: Add support for having single text domain
+* #8143: autodoc: AttributeError is raised when False value is passed to
+  autodoc_default_options
 * #8103: autodoc: functools.cached_property is not considered as a property
+* #8192: napoleon: description is disappeared when it contains inline literals
 * #8093: The highlight warning has wrong location in some builders (LaTeX,
   singlehtml and so on)
 
 Testing
 --------
 
-Release 3.2.1 (in development)
+Release 3.2.2 (in development)
 ==============================
 
 Dependencies
@@ -41,13 +48,36 @@ Features added
 Bugs fixed
 ----------
 
-* #8074: napoleon: Crashes during processing C-ext module
-* #8084: autodoc: KeyError is raised on documenting an attribute of the broken
-  class
+* #8188: C, add missing items to internal object types dictionary,
+  e.g., preventing intersphinx from resolving them.
+
 
 Testing
 --------
 
+Release 3.2.1 (released Aug 14, 2020)
+=====================================
+
+Features added
+--------------
+
+* #8095: napoleon: Add :confval:`napoleon_preprocess_types` to enable the type
+  preprocessor for numpy style docstrings
+* #8114: C and C++, parse function attributes after parameters and qualifiers.
+
+Bugs fixed
+----------
+
+* #8074: napoleon: Crashes during processing C-ext module
+* #8088: napoleon: "Inline literal start-string without end-string" warning in
+  Numpy style Parameters section
+* #8084: autodoc: KeyError is raised on documenting an attribute of the broken
+  class
+* #8091: autodoc: AttributeError is raised on documenting an attribute on Python
+  3.5.2
+* #8099: autodoc: NameError is raised when target code uses ``TYPE_CHECKING``
+* C++, fix parsing of template template paramters, broken by the fix of #7944
+
 Release 3.2.0 (released Aug 08, 2020)
 =====================================
 

Makefile

@@ -64,10 +64,6 @@ type-check:
 doclinter:
 	python utils/doclinter.py CHANGES *.rst doc/
 
-.PHONY: pylint
-pylint:
-	@pylint --rcfile utils/pylintrc sphinx
-
 .PHONY: test
 test:
 	@$(PYTHON) -m pytest -v $(TEST)

doc/develop.rst

@@ -140,14 +140,14 @@ started with writing your own extensions.
 .. _slideshare: https://www.slideshare.net/
 .. _TikZ/PGF LaTeX package: https://sourceforge.net/projects/pgf/
 .. _MATLAB: https://www.mathworks.com/products/matlab.html
-.. _swf: https://bitbucket.org/klorenz/sphinxcontrib-swf
-.. _findanything: https://bitbucket.org/klorenz/sphinxcontrib-findanything
-.. _cmakedomain: https://bitbucket.org/klorenz/sphinxcontrib-cmakedomain
+.. _swf: https://github.com/sphinx-contrib/swf
+.. _findanything: https://github.com/sphinx-contrib/findanything
+.. _cmakedomain: https://github.com/sphinx-contrib/cmakedomain
 .. _GNU Make: https://www.gnu.org/software/make/
-.. _makedomain: https://bitbucket.org/klorenz/sphinxcontrib-makedomain
+.. _makedomain: https://github.com/sphinx-contrib/makedomain
 .. _inlinesyntaxhighlight: https://sphinxcontrib-inlinesyntaxhighlight.readthedocs.io/
 .. _CMake: https://cmake.org
-.. _domaintools: https://bitbucket.org/klorenz/sphinxcontrib-domaintools
+.. _domaintools: https://github.com/sphinx-contrib/domaintools
 .. _restbuilder: https://pypi.org/project/sphinxcontrib-restbuilder/
 .. _Lasso: http://www.lassosoft.com/
 .. _beamer: https://pypi.org/project/sphinxcontrib-beamer/

doc/extdev/appapi.rst

@@ -177,17 +177,18 @@ type for that event::
    9. (if running in parallel mode, for each process) event.env-merged-info(app, env, docnames, other)
    10. event.env-updated(app, env)
    11. event.env-get-updated(app, env)
-   11. event.env-check-consistency(app, env)
+   12. event.env-check-consistency(app, env)
 
+   # The updated-docs list can be builder dependent, but generally includes all new/changed documents,
+   # plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
    # For builders that output a single page, they are first joined into a single doctree before post-transforms/doctree-resolved
-   for docname in docnames:
-      12. apply post-transforms (by priority): docutils.document -> docutils.document
-      13. event.doctree-resolved(app, doctree, docname)
+   for docname in updated-docs:
+      13. apply post-transforms (by priority): docutils.document -> docutils.document
+      14. event.doctree-resolved(app, doctree, docname)
           - (for any reference node that fails to resolve) event.missing-reference(env, node, contnode)
 
-   14. Generate output files
-
-   15. event.build-finished(app, exception)
+   15. Generate output files
+   16. event.build-finished(app, exception)
 
 Here is a more detailed list of these events.
 

doc/internals/contributing.rst

@@ -12,6 +12,9 @@ Getting help
 
 The Sphinx community maintains a number of mailing lists and IRC channels.
 
+Stack Overflow with tag `python-sphinx`_
+    Questions and answers about use and development.
+
 sphinx-users <sphinx-users@googlegroups.com>
     Mailing list for user support.
 
@@ -21,6 +24,7 @@ sphinx-dev <sphinx-dev@googlegroups.com>
 #sphinx-doc on irc.freenode.net
     IRC channel for development questions and user support.
 
+.. _python-sphinx: https://stackoverflow.com/questions/tagged/python-sphinx
 
 Bug Reports and Feature Requests
 --------------------------------

doc/usage/configuration.rst

@@ -756,9 +756,15 @@ documentation on :ref:`intl` for details.
    If true, a document's text domain is its docname if it is a top-level
    project file and its very base directory otherwise.
 
+   If set to string, all document's text domain is this string, making all
+   documents use single text domain.
+
    By default, the document ``markup/code.rst`` ends up in the ``markup`` text
    domain.  With this option set to ``False``, it is ``markup/code``.
 
+   .. versionchanged:: 3.3
+      The string value is now accepted.
+
 .. confval:: gettext_uuid
 
    If true, Sphinx generates uuid information for version tracking in message

doc/usage/quickstart.rst

@@ -15,7 +15,7 @@ Much of Sphinx's power comes from the richness of its default plain-text markup
 format, :doc:`reStructuredText </usage/restructuredtext/index>`, along with
 it's :doc:`significant extensibility capabilities </development/index>`.
 
-The goal of this document is to give you a quick taste of what Sphinx it is and
+The goal of this document is to give you a quick taste of what Sphinx is and
 how you might use it. When you're done here, you can check out the
 :doc:`installation guide </usage/installation>` followed by the intro to the
 default markup format used by Sphinx, :doc:`reStucturedText

sphinx/application.py

@@ -1004,7 +1004,7 @@ def add_lexer(self, alias: str, lexer: Union[Lexer, "Type[Lexer]"]) -> None:
         logger.debug('[app] adding lexer: %r', (alias, lexer))
         if isinstance(lexer, Lexer):
             warnings.warn('app.add_lexer() API changed; '
-                          'Please give lexer class instead instance',
+                          'Please give lexer class instead of instance',
                           RemovedInSphinx40Warning, stacklevel=2)
             lexers[alias] = lexer
         else:

sphinx/builders/gettext.py

@@ -316,7 +316,7 @@ def finish(self) -> None:
 def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_builder(MessageCatalogBuilder)
 
-    app.add_config_value('gettext_compact', True, 'gettext')
+    app.add_config_value('gettext_compact', True, 'gettext', Any)
     app.add_config_value('gettext_location', True, 'gettext')
     app.add_config_value('gettext_uuid', False, 'gettext')
     app.add_config_value('gettext_auto_build', True, 'env')

sphinx/builders/html/__init__.py

@@ -751,18 +751,27 @@ def copy_stemmer_js(self) -> None:
                 copyfile(jsfile, path.join(self.outdir, '_static', '_stemmer.js'))
 
     def copy_theme_static_files(self, context: Dict) -> None:
+        def onerror(filename: str, error: Exception) -> None:
+            logger.warning(__('Failed to copy a file in html_static_file: %s: %r'),
+                           filename, error)
+
         if self.theme:
             for entry in self.theme.get_theme_dirs()[::-1]:
                 copy_asset(path.join(entry, 'static'),
                            path.join(self.outdir, '_static'),
-                           excluded=DOTFILES, context=context, renderer=self.templates)
+                           excluded=DOTFILES, context=context,
+                           renderer=self.templates, onerror=onerror)
 
     def copy_html_static_files(self, context: Dict) -> None:
+        def onerror(filename: str, error: Exception) -> None:
+            logger.warning(__('Failed to copy a file in html_static_file: %s: %r'),
+                           filename, error)
+
         excluded = Matcher(self.config.exclude_patterns + ["**/.*"])
         for entry in self.config.html_static_path:
             copy_asset(path.join(self.confdir, entry),
                        path.join(self.outdir, '_static'),
-                       excluded, context=context, renderer=self.templates)
+                       excluded, context=context, renderer=self.templates, onerror=onerror)
 
     def copy_html_logo(self) -> None:
         if self.config.html_logo:

sphinx/directives/code.py

@@ -72,7 +72,7 @@ def dedent_lines(lines: List[str], dedent: int, location: Tuple[str, int] = None
         return lines
 
     if any(s[:dedent].strip() for s in lines):
-        logger.warning(__('Over dedent has detected'), location=location)
+        logger.warning(__('non-whitespace stripped by dedent'), location=location)
 
     new_lines = []
     for line in lines:

sphinx/domains/c.py

@@ -32,7 +32,7 @@
 from sphinx.transforms.post_transforms import ReferencesResolver
 from sphinx.util import logging
 from sphinx.util.cfamily import (
-    NoOldIdError, ASTBaseBase, ASTBaseParenExprList,
+    NoOldIdError, ASTBaseBase, ASTAttribute, ASTBaseParenExprList,
     verify_description_mode, StringifyTransform,
     BaseParser, DefinitionError, UnsupportedMultiCharacterCharLiteral,
     identifier_re, anon_identifier_re, integer_literal_re, octal_literal_re,
@@ -652,8 +652,9 @@ def describe_signature(self, signode: Any, mode: str,
 
 
 class ASTParameters(ASTBase):
-    def __init__(self, args: List[ASTFunctionParameter]) -> None:
+    def __init__(self, args: List[ASTFunctionParameter], attrs: List[ASTAttribute]) -> None:
         self.args = args
+        self.attrs = attrs
 
     @property
     def function_params(self) -> List[ASTFunctionParameter]:
@@ -669,6 +670,9 @@ def _stringify(self, transform: StringifyTransform) -> str:
             first = False
             res.append(str(a))
         res.append(')')
+        for attr in self.attrs:
+            res.append(' ')
+            res.append(transform(attr))
         return ''.join(res)
 
     def describe_signature(self, signode: TextElement, mode: str,
@@ -683,6 +687,9 @@ def describe_signature(self, signode: TextElement, mode: str,
                 arg.describe_signature(param, 'markType', env, symbol=symbol)
             paramlist += param
         signode += paramlist
+        for attr in self.attrs:
+            signode += nodes.Text(' ')
+            attr.describe_signature(signode)
 
 
 class ASTDeclSpecsSimple(ASTBaseBase):
@@ -1785,7 +1792,7 @@ def onMissingQualifiedSymbol(parentSymbol: "Symbol", ident: ASTIdentifier) -> "S
 
         if not declaration:
             if Symbol.debug_lookup:
-                Symbol.debug_print("no delcaration")
+                Symbol.debug_print("no declaration")
                 Symbol.debug_indent -= 2
             # good, just a scope creation
             # TODO: what if we have more than one symbol?
@@ -2572,7 +2579,15 @@ def _parse_parameters(self, paramMode: str) -> ASTParameters:
                     self.fail(
                         'Expecting "," or ")" in parameters, '
                         'got "%s".' % self.current_char)
-        return ASTParameters(args)
+
+        attrs = []
+        while True:
+            attr = self._parse_attribute()
+            if attr is None:
+                break
+            attrs.append(attr)
+
+        return ASTParameters(args, attrs)
 
     def _parse_decl_specs_simple(self, outer: str, typed: bool) -> ASTDeclSpecsSimple:
         """Just parse the simple ones."""
@@ -3592,6 +3607,10 @@ class CDomain(Domain):
         'macro': ObjType(_('macro'), 'macro'),
         'type': ObjType(_('type'), 'type'),
         'var': ObjType(_('variable'), 'data'),
+        'enum': ObjType(_('enum'), 'enum'),
+        'enumerator': ObjType(_('enumerator'), 'enumerator'),
+        'struct': ObjType(_('struct'), 'struct'),
+        'union': ObjType(_('union'), 'union'),
     }
 
     directives = {