Merge branch '3.x' into 8183

.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.

.travis.yml

@@ -24,9 +24,6 @@ jobs:
       env:
         - TOXENV=du15
         - PYTEST_ADDOPTS="--cov ./ --cov-append --cov-config setup.cfg"
-    - python: 'nightly'
-      env:
-        - TOXENV=du16
 
     - language: node_js
       node_js: '10.7'

CHANGES

@@ -1,3 +1,86 @@
+Release 3.3.0 (in development)
+==============================
+
+Dependencies
+------------
+
+Incompatible changes
+--------------------
+
+Deprecated
+----------
+
+* ``sphinx.builders.latex.LaTeXBuilder.usepackages``
+* ``sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref``
+* ``sphinx.ext.autodoc.SingledispatchFunctionDocumenter``
+* ``sphinx.ext.autodoc.SingledispatchMethodDocumenter``
+
+Features added
+--------------
+
+* #8100: html: Show a better error message for failures on copying
+  html_static_files
+* #8141: C: added a ``maxdepth`` option to :rst:dir:`c:alias` to insert
+  nested declarations.
+* #8081: LaTeX: Allow to add LaTeX package via ``app.add_latex_package()`` until
+  just before writing .tex file
+* #7996: manpage: Add :confval:`man_make_section_directory` to make a section
+  directory on build man page
+* #8289: epub: Allow to suppress "duplicated ToC entry found" warnings from epub
+  builder using :confval:`suppress_warnings`.
+* #8298: sphinx-quickstart: Add :option:`sphinx-quickstart --no-sep` option
+* #8304: sphinx.testing: Register public markers in sphinx.testing.fixtures
+* #8051: napoleon: use the obj role for all See Also items
+* #8050: napoleon: Apply :confval:`napoleon_preprocess_types` to every field
+
+Bugs fixed
+----------
+
+* #8085: i18n: Add support for having single text domain
+* #6640: i18n: Failed to override system message translation
+* #8143: autodoc: AttributeError is raised when False value is passed to
+  autodoc_default_options
+* #8103: autodoc: functools.cached_property is not considered as a property
+* #8190: autodoc: parsing error is raised if some extension replaces docstring
+  by string not ending with blank lines
+* #8142: autodoc: Wrong constructor signature for the class derived from
+  typing.Generic
+* #8157: autodoc: TypeError is raised when annotation has invalid __args__
+* #7964: autodoc: Tuple in default value is wrongly rendered
+* #8200: autodoc: type aliases break type formatting of autoattribute
+* #7786: autodoc: can't detect overloaded methods defined in other file
+* #8294: autodoc: single-string __slots__ is not handled correctly
+* #7785: autodoc: autodoc_typehints='none' does not effect to overloaded functions
+* #8192: napoleon: description is disappeared when it contains inline literals
+* #8142: napoleon: Potential of regex denial of service in google style docs
+* #8169: LaTeX: pxjahyper loaded even when latex_engine is not platex
+* #8215: LaTeX: 'oneside' classoption causes build warning
+* #8175: intersphinx: Potential of regex denial of service by broken inventory
+* #8277: sphinx-build: missing and redundant spacing (and etc) for console
+  output on building
+* #7973: imgconverter: Check availability of imagemagick many times
+* #8255: py domain: number in default argument value is changed from hexadecimal
+  to decimal
+* #8316: html: Prevent arrow keys changing page when button elements are focused
+* #8343: html search: Fix unnecessary load of images when parsing the document
+* #8254: html theme: Line numbers misalign with code lines
+* #8093: The highlight warning has wrong location in some builders (LaTeX,
+  singlehtml and so on)
+* #8215: Eliminate Fancyhdr build warnings for oneside documents
+* #8239: Failed to refer a token in productionlist if it is indented
+* #8268: linkcheck: Report HTTP errors when ``linkcheck_anchors`` is ``True``
+* #8245: linkcheck: take source directory into account for local files
+* #8321: linkcheck: ``tel:`` schema hyperlinks are detected as errors
+* #8323: linkcheck: An exit status is incorrect when links having unsupported
+  schema found
+* #6914: figure numbers are unexpectedly assigned to uncaptioned items
+* #8320: make "inline" line numbers un-selectable
+
+Testing
+--------
+
+* #8257: Support parallel build in sphinx.testing
+
 Release 3.2.2 (in development)
 ==============================
 
@@ -16,6 +99,15 @@ Features added
 Bugs fixed
 ----------
 
+* #8188: C, add missing items to internal object types dictionary,
+  e.g., preventing intersphinx from resolving them.
+* C, fix anon objects in intersphinx.
+* #8270, C++, properly reject functions as duplicate declarations if a
+  non-function declaration of the same name already exists.
+* C, fix references to function parameters.
+  Link to the function instead of a non-existing anchor.
+
+
 Testing
 --------
 
@@ -118,7 +210,7 @@ Bugs fixed
   contains a hyperlink target
 * #7469: autosummary: "Module attributes" header is not translatable
 * #7940: apidoc: An extra newline is generated at the end of the rst file if a
-  module has submodules 
+  module has submodules
 * #4258: napoleon: decorated special methods are not shown
 * #7799: napoleon: parameters are not escaped for combined params in numpydoc
 * #7780: napoleon: multiple paramaters declaration in numpydoc was wrongly
@@ -285,7 +377,7 @@ Features added
 * #7543: html theme: Add top and bottom margins to tables
 * #7695: html theme: Add viewport meta tag for basic theme
 * #7721: html theme: classic: default codetextcolor/codebgcolor doesn't override
-  Pygments 
+  Pygments
 * C and C++: allow semicolon in the end of declarations.
 * C++, parse parameterized noexcept specifiers.
 * #7294: C++, parse expressions with user-defined literals.

EXAMPLES

@@ -230,6 +230,7 @@ Documentation using sphinx_rtd_theme
 * `MyHDL <http://docs.myhdl.org/>`__
 * `Nextflow <https://www.nextflow.io/docs/latest/index.html>`__
 * `NICOS <https://forge.frm2.tum.de/nicos/doc/nicos-master/>`__ (customized)
+* `OpenFAST <https://openfast.readthedocs.io/>`__ 
 * `Pelican <http://docs.getpelican.com/>`__
 * `picamera <https://picamera.readthedocs.io/>`__
 * `Pillow <https://pillow.readthedocs.io/>`__
@@ -330,6 +331,7 @@ Documentation using a custom theme or integrated in a website
 * `Lasso <http://lassoguide.com/>`__
 * `Mako <http://docs.makotemplates.org/>`__
 * `MirrorBrain <http://mirrorbrain.org/docs/>`__
+* `Mitiq <https://mitiq.readthedocs.io/>`__
 * `MongoDB <https://docs.mongodb.com/>`__
 * `Music21 <https://web.mit.edu/music21/doc/>`__
 * `MyHDL <http://docs.myhdl.org/>`__

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/_themes/sphinx13/static/sphinx13.css

@@ -239,7 +239,7 @@ div.footer a {
 
 /* -- body styles ----------------------------------------------------------- */
 
-p {    
+p {
     margin: 0.8em 0 0.5em 0;
 }
 

doc/conf.py

@@ -28,6 +28,7 @@
 html_additional_pages = {'index': 'index.html'}
 html_use_opensearch = 'https://www.sphinx-doc.org/en/master'
 html_baseurl = 'https://www.sphinx-doc.org/en/master/'
+html_favicon = '_static/favicon.svg'
 
 htmlhelp_basename = 'Sphinxdoc'
 
@@ -110,8 +111,6 @@
      1),
 ]
 
-# We're not using intersphinx right now, but if we did, this would be part of
-# the mapping:
 intersphinx_mapping = {'python': ('https://docs.python.org/3/', None)}
 
 # Sphinx document translation with sphinx gettext feature uses these settings:

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/extdev/deprecated.rst

@@ -26,6 +26,26 @@ The following is a list of deprecated interfaces.
      - (will be) Removed
      - Alternatives
 
+   * - ``sphinx.builders.latex.LaTeXBuilder.usepackages``
+     - 3.3
+     - 5.0
+     - N/A
+
+   * - ``sphinx.builders.latex.LaTeXBuilder.usepackages_afger_hyperref``
+     - 3.3
+     - 5.0
+     - N/A
+
+   * - ``sphinx.ext.autodoc.SingledispatchFunctionDocumenter``
+     - 3.3
+     - 5.0
+     - ``sphinx.ext.autodoc.FunctionDocumenter``
+
+   * - ``sphinx.ext.autodoc.SingledispatchMethodDocumenter``
+     - 3.3
+     - 5.0
+     - ``sphinx.ext.autodoc.MethodDocumenter``
+
    * - ``sphinx.ext.autodoc.members_set_option()``
      - 3.2
      - 5.0

doc/glossary.rst

@@ -9,8 +9,8 @@ Glossary
       A class (inheriting from :class:`~sphinx.builders.Builder`) that takes
       parsed documents and performs an action on them.  Normally, builders
       translate the documents to an output format, but it is also possible to
-      use the builder builders that e.g. check for broken links in the
-      documentation, or build coverage information.
+      use builders that e.g. check for broken links in the documentation, or
+      build coverage information.
 
       See :doc:`/usage/builders/index` for an overview over Sphinx's built-in
       builders.

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/man/sphinx-quickstart.rst

@@ -33,6 +33,10 @@ Options
 
    If specified, separate source and build directories.
 
+.. option:: --no-sep
+
+   If specified, create build directroy under source directroy.
+
 .. option:: --dot=DOT
 
    Inside the root directory, two more directories will be created;

doc/usage/configuration.rst

@@ -316,6 +316,7 @@ General configuration
    * ``toc.circular``
    * ``toc.secnum``
    * ``epub.unknown_project_files``
+   * ``epub.duplicated_toc_entry``
    * ``autosectionlabel.*``
 
    You can choose from these types.
@@ -340,6 +341,10 @@ General configuration
 
       Added ``autosectionlabel.*``
 
+   .. versionchanged:: 3.3.0
+
+      Added ``epub.duplicated_toc_entry``
+
 .. confval:: needs_sphinx
 
    If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will
@@ -756,9 +761,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
@@ -2239,6 +2250,12 @@ These options influence manual page output.
 
    .. versionadded:: 1.1
 
+.. confval:: man_make_section_directory
+
+   If true, make a section directory on build man page.  Default is False.
+
+   .. versionadded:: 3.3
+
 
 .. _texinfo-options: