Merge branch 'sphinx-doc:4.x' into container-latex

2025-02-25 18:55:22 -06:00 · 2021-07-04 20:24:49 +01:00
parent 52aac40148 2100722b70
commit c218cf2192
227 changed files with 23752 additions and 18310 deletions
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -8,9 +8,9 @@ jobs:
    working_directory: /sphinx
    steps:
      - checkout
-      - run: /python3.6/bin/pip install -U pip setuptools
-      - run: /python3.6/bin/pip install -U .[test]
+      - run: /python3.8/bin/pip install -U pip setuptools
+      - run: /python3.8/bin/pip install -U .[test]
      - run: mkdir -p test-reports/pytest
-      - run: make test PYTHON=/python3.6/bin/python TEST="--junitxml=test-reports/pytest/results.xml -vv"
+      - run: make test PYTHON=/python3.8/bin/python TEST="--junitxml=test-reports/pytest/results.xml -vv"
      - store_test_results:
          path: test-reports
--- a/94
+++ b/94
@@ -12,7 +12,10 @@ Incompatible changes
 Deprecated
 ----------

+* The ``app`` argument of ``sphinx.environment.BuildEnvironment`` becomes
+  required
 * ``sphinx.application.Sphinx.html_theme``
+* ``sphinx.ext.autosummary._app``
 * ``sphinx.util.docstrings.extract_metadata()``

 Features added
@@ -28,15 +31,45 @@ Features added
 * #9195: autodoc: The arguments of ``typing.Literal`` are wrongly rendered
 * #9185: autodoc: :confval:`autodoc_typehints` allows ``'both'`` setting to
  allow typehints to be included both in the signature and description
+* #4257: autodoc: Add :confval:`autodoc_class_signature` to separate the class
+  entry and the definition of ``__init__()`` method
+* #8061, #9218: autodoc: Support variable comment for alias classes
+* #3014: autodoc: Add :event:`autodoc-process-bases` to modify the base classes
+  of the class definitions
+* #9272: autodoc: Render enum values for the default argument value better
+* #9384: autodoc: ``autodoc_typehints='none'`` now erases typehints for
+  variables, attributes and properties
 * #3257: autosummary: Support instance attributes for classes
 * #9129: html search: Show search summaries when html_copy_source = False
+* #9307: html search: Prevent corrections and completions in search field
 * #9120: html theme: Eliminate prompt characters of code-block from copyable
  text
 * #9176: i18n: Emit a debug message if message catalog file not found under
  :confval:`locale_dirs`
+* #9016: linkcheck: Support checking anchors on github.com
+* #9016: linkcheck: Add a new event :event:`linkcheck-process-uri` to modify
+  URIs before checking hyperlinks
+* #1874: py domain: Support union types using ``|`` in info-field-list
+* #9268: py domain: :confval:`python_use_unqualified_type_names` supports type
+  field in info-field-list
 * #9097: Optimize the paralell build
 * #9131: Add :confval:`nitpick_ignore_regex` to ignore nitpicky warnings using
  regular expressions
+* #9174: Add ``Sphinx.set_html_assets_policy`` to tell extensions to include
+  HTML assets in all the pages. Extensions can check this via
+  ``Sphinx.registry.html_assets_policy``
+* C++, add support for
+
+  - ``inline`` variables,
+  - ``consteval`` functions,
+  - ``constinit`` variables,
+  - ``char8_t``,
+  - ``explicit(<constant expression>)`` specifier,
+  - digit separators in literals, and
+  - constraints in placeholder type specifiers, aka. adjective syntax
+    (e.g., ``Sortable auto &v``).
+
+* C, add support for digit separators in literals.


 Bugs fixed
@@ -46,11 +79,29 @@ Bugs fixed
 * #8597: autodoc: a docsting having metadata only should be treated as
  undocumented
 * #9185: autodoc: typehints for overloaded functions and methods are inaccurate
+* #9250: autodoc: The inherited method not having docstring is wrongly parsed
+* #9283: autodoc: autoattribute directive failed to generate document for an
+  attribute not having any comment
+* #9364: autodoc: single element tuple on the default argument value is wrongly
+  rendered
+* #9317: html: Pushing left key causes visiting the next page at the first page
+* #9381: html: URL for html_favicon and html_log does not work
+* #9270: html theme : pyramid theme generates incorrect logo links
+* #9217: manpage: The name of manpage directory that is generated by
+  :confval:`man_make_section_directory` is not correct
+* #9350: manpage: Fix font isn't reset after keyword at the top of samp role
+* #9306: Linkcheck reports broken link when remote server closes the connection
+  on HEAD request
+* #9280: py domain: "exceptions" module is not displayed
+* #9224: ``:param:`` and ``:type:`` fields does not support a type containing
+  whitespace (ex. ``Dict[str, str]``)
+* #8945: when transforming typed fields, call the specified role instead of
+  making an single xref. For C and C++, use the ``expr`` role for typed fields.

 Testing
 --------

-Release 4.0.2 (in development)
+Release 4.0.3 (in development)
 ==============================

 Dependencies
@@ -65,13 +116,48 @@ Deprecated
 Features added
 --------------

+* C, add C23 keywords ``_Decimal32``, ``_Decimal64``, and ``_Decimal128``.
+* #9354: C, add :confval:`c_extra_keywords` to allow user-defined keywords
+  during parsing.
+* Revert the removal of ``sphinx.util:force_decode()`` to become some 3rd party
+  extensions available again during 5.0
+
+Bugs fixed
+----------
+
+* #9330: changeset domain: :rst:dir:`versionchanged` with contents being a list
+  will cause error during pdf build
+* #9313: LaTeX: complex table with merged cells broken since 4.0
+* #9305: LaTeX: backslash may cause Improper discretionary list pdf build error
+  with Japanese engines
+* #9354: C, remove special macro names from the keyword list.
+  See also :confval:`c_extra_keywords`.
+* #9322: KeyError is raised on PropagateDescDomain transform
+
+Testing
+--------
+
+Release 4.0.2 (released May 20, 2021)
+=====================================
+
+Dependencies
+------------
+
+* #9216: Support jinja2-3.0
+
+Incompatible changes
+--------------------
+
+* #9222: Update Underscore.js to 1.13.1
+* #9217: manpage: Stop creating a section directory on build manpage by default
+  (see :confval:`man_make_section_directory`)
+
 Bugs fixed
 ----------

 * #9210: viewcode: crashed if non importable modules found on parallel build
-
-Testing
--------
+* #9240: Unknown node error for pending_xref_condition is raised if an extension
+  that does not support the node installs a missing-reference handler

 Release 4.0.1 (released May 11, 2021)
 =====================================
--- a/133
+++ b/133
@@ -25,14 +25,14 @@ Documentation using the alabaster theme
 * `Flask-OpenID <https://pythonhosted.org/Flask-OpenID/>`__
 * `Invoke <https://docs.pyinvoke.org/>`__
 * `Jinja <https://jinja.palletsprojects.com/>`__
-* `Lino <http://www.lino-framework.org/>`__ (customized)
+* `Lino <https://www.lino-framework.org/>`__ (customized)
 * `marbl <https://getmarbl.readthedocs.io/>`__
 * `MDAnalysis <https://www.mdanalysis.org/docs/>`__ (customized)
 * `MeshPy <https://documen.tician.de/meshpy/>`__
 * `Molecule <https://molecule.readthedocs.io/>`__
 * `PyCUDA <https://documen.tician.de/pycuda/>`__
 * `PyOpenCL <https://documen.tician.de/pyopencl/>`__
-* `PyLangAcq <http://pylangacq.org/>`__
+* `PyLangAcq <https://pylangacq.org/>`__
 * `pytest <https://docs.pytest.org/>`__ (customized)
 * `python-apt <https://apt.alioth.debian.org/python-apt-doc/>`__
 * `PyVisfile <https://documen.tician.de/pyvisfile/>`__
@@ -47,10 +47,10 @@ Documentation using the alabaster theme
 Documentation using the classic theme
 -------------------------------------

-* `Advanced Generic Widgets <http://xoomer.virgilio.it/infinity77/AGW_Docs/>`__ (customized)
-* `Apache CouchDB <http://docs.couchdb.org/>`__ (customized)
+* `Advanced Generic Widgets <https://xoomer.virgilio.it/infinity77/AGW_Docs/>`__ (customized)
+* `Apache CouchDB <https://docs.couchdb.org/>`__ (customized)
 * `APSW <https://rogerbinns.github.io/apsw/>`__
-* `Arb <http://arblib.org/>`__
+* `Arb <https://arblib.org/>`__
 * `Bazaar <http://doc.bazaar.canonical.com/>`__ (customized)
 * `Beautiful Soup <https://www.crummy.com/software/BeautifulSoup/bs4/doc/>`__
 * `Blender API <https://docs.blender.org/api/current/>`__
@@ -70,7 +70,7 @@ Documentation using the classic theme
 * `GetFEM++ <http://getfem.org/>`__ (customized)
 * `Glasgow Haskell Compiler <https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/>`__ (customized)
 * `Grok <http://grok.zope.org/doc/current/>`__ (customized)
-* `GROMACS <http://manual.gromacs.org/documentation/>`__
+* `GROMACS <https://manual.gromacs.org/documentation/>`__
 * `GSL Shell <https://www.nongnu.org/gsl-shell/>`__
 * `Hands-on Python Tutorial <https://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/>`__
 * `Kaa <https://api.freevo.org/kaa-base/>`__ (customized)
@@ -78,9 +78,9 @@ Documentation using the classic theme
 * `LEPL <http://www.acooke.org/lepl/>`__ (customized)
 * `Mayavi <https://docs.enthought.com/mayavi/mayavi/>`__ (customized)
 * `MediaGoblin <https://mediagoblin.readthedocs.io/>`__ (customized)
-* `mpmath <http://mpmath.org/doc/current/>`__
+* `mpmath <https://mpmath.org/doc/current/>`__
 * `OpenCV <https://docs.opencv.org/>`__ (customized)
-* `OpenEXR <http://excamera.com/articles/26/doc/index.html>`__
+* `OpenEXR <https://excamera.com/articles/26/doc/index.html>`__
 * `OpenGDA <http://www.opengda.org/gdadoc/html/>`__
 * `Peach^3 <https://peach3.nl/doc/latest/userdoc/>`__ (customized)
 * `Plone <https://docs.plone.org/>`__ (customized)
@@ -119,8 +119,8 @@ Documentation using the sphinxdoc theme
 * `Matplotlib <https://matplotlib.org/>`__
 * `MDAnalysis Tutorial <https://www.mdanalysis.org/MDAnalysisTutorial/>`__
 * `NetworkX <https://networkx.github.io/>`__
-* `PyCantonese <http://pycantonese.org/>`__
-* `Pyre <http://docs.danse.us/pyre/sphinx/>`__
+* `PyCantonese <https://pycantonese.org/>`__
+* `Pyre <https://docs.danse.us/pyre/sphinx/>`__
 * `pySPACE <https://pyspace.github.io/pyspace/>`__
 * `Pysparse <http://pysparse.sourceforge.net/>`__
 * `PyTango <https://www.esrf.eu/computing/cs/tango/tango_doc/kernel_doc/pytango/latest/>`__
@@ -134,7 +134,7 @@ Documentation using the nature theme
 ------------------------------------

 * `Alembic <https://alembic.sqlalchemy.org/>`__
-* `Cython <http://docs.cython.org/>`__
+* `Cython <https://docs.cython.org/>`__
 * `easybuild <https://easybuild.readthedocs.io/>`__
 * `jsFiddle <http://doc.jsfiddle.net/>`__
 * `libLAS <https://www.liblas.org/>`__ (customized)
@@ -159,18 +159,19 @@ Documentation using another builtin theme
 * `Pylons <https://docs.pylonsproject.org/projects/pylons-webframework/>`__ (pyramid)
 * `Pyramid web framework <https://docs.pylonsproject.org/projects/pyramid/>`__ (pyramid)
 * `RxDock <https://www.rxdock.org/documentation/html/devel/>`__
-* `Sphinx <http://www.sphinx-doc.org/>`__ (sphinx13) :-)
+* `Sphinx <https://www.sphinx-doc.org/>`__ (sphinx13) :-)
 * `Valence <https://docs.valence.desire2learn.com/>`__ (haiku, customized)

 Documentation using sphinx_rtd_theme
 ------------------------------------

-* `Annotator <http://docs.annotatorjs.org/>`__
+* `Annotator <https://docs.annotatorjs.org/>`__
 * `Ansible <https://docs.ansible.com/>`__ (customized)
-* `Arcade <http://arcade.academy/>`__
+* `Arcade <https://arcade.academy/>`__
 * `aria2 <https://aria2.github.io/manual/en/html/>`__
 * `ASE <https://wiki.fysik.dtu.dk/ase/>`__
-* `Autofac <http://docs.autofac.org/>`__
+* `asvin <https://asvin.readthedocs.io/>`__
+* `Autofac <https://docs.autofac.org/>`__
 * `BigchainDB <https://docs.bigchaindb.com/>`__
 * `Blender Reference Manual <https://docs.blender.org/manual/>`__
 * `Blocks <https://blocks.readthedocs.io/>`__
@@ -188,28 +189,28 @@ Documentation using sphinx_rtd_theme
 * `DNF <https://dnf.readthedocs.io/>`__
 * `Django-cas-ng <https://djangocas.dev/docs/>`__
 * `edX <https://docs.edx.org/>`__
-* `Electrum <http://docs.electrum.org/>`__
-* `Elemental <http://libelemental.org/documentation/dev/>`__
+* `Electrum <https://docs.electrum.org/>`__
+* `Elemental <https://libelemental.org/documentation/dev/>`__
 * `ESWP3 <https://eswp3.readthedocs.io/>`__
-* `Ethereum Homestead <http://www.ethdocs.org/>`__
+* `Ethereum Homestead <https://www.ethdocs.org/>`__
 * `Exhale <https://exhale.readthedocs.io/>`__
 * `Faker <https://faker.readthedocs.io/>`__
 * `Fidimag <https://fidimag.readthedocs.io/>`__
-* `Flake8 <http://flake8.pycqa.org/>`__
-* `Flatpak <http://docs.flatpak.org/>`__
+* `Flake8 <https://flake8.pycqa.org/>`__
+* `Flatpak <https://docs.flatpak.org/>`__
 * `FluidDyn <https://fluiddyn.readthedocs.io/>`__
 * `Fluidsim <https://fluidsim.readthedocs.io/>`__
 * `Gallium <https://gallium.readthedocs.io/>`__
-* `GeoNode <http://docs.geonode.org/>`__
+* `GeoNode <https://docs.geonode.org/>`__
 * `Glances <https://glances.readthedocs.io/>`__
 * `Godot <https://godot.readthedocs.io/>`__
-* `Graylog <http://docs.graylog.org/>`__
+* `Graylog <https://docs.graylog.org/>`__
 * `GPAW <https://wiki.fysik.dtu.dk/gpaw/>`__ (customized)
-* `HDF5 for Python (h5py) <http://docs.h5py.org/>`__
+* `HDF5 for Python (h5py) <https://docs.h5py.org/>`__
 * `Hyperledger Fabric <https://hyperledger-fabric.readthedocs.io/>`__
 * `Hyperledger Sawtooth <https://intelledger.github.io/>`__
-* `IdentityServer <http://docs.identityserver.io/>`__
-* `Idris <http://docs.idris-lang.org/>`__
+* `IdentityServer <https://docs.identityserver.io/>`__
+* `Idris <https://docs.idris-lang.org/>`__
 * `javasphinx <https://bronto-javasphinx.readthedocs.io/>`__
 * `Julia <https://julia.readthedocs.io/>`__
 * `Jupyter Notebook <https://jupyter-notebook.readthedocs.io/>`__
@@ -219,45 +220,45 @@ Documentation using sphinx_rtd_theme
 * `LibCEED <https://libceed.readthedocs.io/>`__
 * `Linguistica <https://linguistica-uchicago.github.io/lxa5/>`__
 * `Linux kernel <https://www.kernel.org/doc/html/latest/index.html>`__
-* `Mailman <http://docs.list.org/>`__
+* `Mailman <https://docs.list.org/>`__
 * `MathJax <https://docs.mathjax.org/>`__
 * `MDTraj <http://mdtraj.org/latest/>`__ (customized)
 * `Mesa 3D <https://docs.mesa3d.org/>`__
 * `micca - MICrobial Community Analysis <https://micca.readthedocs.io/>`__
 * `MicroPython <https://docs.micropython.org/>`__
 * `Minds <https://www.minds.org/docs/>`__ (customized)
-* `Mink <http://mink.behat.org/>`__
-* `Mockery <http://docs.mockery.io/>`__
+* `Mink <https://mink.behat.org/>`__
+* `Mockery <https://docs.mockery.io/>`__
 * `mod_wsgi <https://modwsgi.readthedocs.io/>`__
 * `MoinMoin <https://moin-20.readthedocs.io/>`__
 * `Mopidy <https://docs.mopidy.com/>`__
 * `mpi4py <https://mpi4py.readthedocs.io/>`__
-* `MyHDL <http://docs.myhdl.org/>`__
+* `MyHDL <https://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/>`__
+* `Pelican <https://docs.getpelican.com/>`__
 * `picamera <https://picamera.readthedocs.io/>`__
 * `Pillow <https://pillow.readthedocs.io/>`__
 * `pip <https://pip.pypa.io/>`__
 * `Paver <https://paver.readthedocs.io/>`__
-* `peewee <http://docs.peewee-orm.com/>`__
-* `Phinx <http://docs.phinx.org/>`__
+* `peewee <https://docs.peewee-orm.com/>`__
+* `Phinx <https://docs.phinx.org/>`__
 * `phpMyAdmin <https://docs.phpmyadmin.net/>`__
 * `PROS <https://pros.cs.purdue.edu/v5/>`__ (customized)
 * `Pushkin <http://docs.pushkin.io/>`__
-* `Pweave <http://mpastell.com/pweave/>`__
-* `PyPy <http://doc.pypy.org/>`__
+* `Pweave <https://mpastell.com/pweave/>`__
+* `PyPy <https://doc.pypy.org/>`__
 * `python-sqlparse <https://sqlparse.readthedocs.io/>`__
 * `PyVISA <https://pyvisa.readthedocs.io/>`__
 * `pyvista <https://docs.pyvista.org/>`__
 * `Read The Docs <https://docs.readthedocs.io/>`__
 * `ROCm Platform <https://rocm-documentation.readthedocs.io/>`__
-* `Free your information from their silos (French) <http://redaction-technique.org/>`__ (customized)
+* `Free your information from their silos (French) <https://redaction-technique.org/>`__ (customized)
 * `Releases Sphinx extension <https://releases.readthedocs.io/>`__
-* `Qtile <http://docs.qtile.org/>`__
+* `Qtile <https://docs.qtile.org/>`__
 * `Quex <http://quex.sourceforge.net/doc/html/main.html>`__
-* `QuTiP <http://qutip.org/docs/latest/>`__
+* `QuTiP <https://qutip.org/docs/latest/>`__
 * `Satchmo <http://docs.satchmoproject.com/>`__
 * `Scapy <https://scapy.readthedocs.io/>`__
 * `SimGrid <https://simgrid.org/doc/latest/>`__
@@ -265,7 +266,7 @@ Documentation using sphinx_rtd_theme
 * `six <https://six.readthedocs.io/>`__
 * `SlamData <https://newdocs.slamdata.com>`__
 * `Solidity <https://solidity.readthedocs.io/>`__
-* `Sonos Controller (SoCo) <http://docs.python-soco.com/>`__
+* `Sonos Controller (SoCo) <https://docs.python-soco.com/>`__
 * `Sphinx AutoAPI <https://sphinx-autoapi.readthedocs.io/>`__
 * `sphinx-argparse <https://sphinx-argparse.readthedocs.io/>`__
 * `Sphinx-Gallery <https://sphinx-gallery.readthedocs.io/>`__ (customized)
@@ -277,7 +278,7 @@ Documentation using sphinx_rtd_theme
 * `Sylius <http://docs.sylius.org/>`__
 * `Syncthing <https://docs.syncthing.net/>`__
 * `Tango Controls <https://tango-controls.readthedocs.io/>`__ (customized)
-* `Topshelf <http://docs.topshelf-project.com/>`__
+* `Topshelf <https://docs.topshelf-project.com/>`__
 * `Theano <http://www.deeplearning.net/software/theano/>`__
 * `ThreatConnect <https://docs.threatconnect.com/>`__
 * `Tuleap <https://tuleap.net/doc/en/>`__
@@ -286,7 +287,7 @@ Documentation using sphinx_rtd_theme
 * `uWSGI <https://uwsgi-docs.readthedocs.io/>`__
 * `virtualenv <https://virtualenv.readthedocs.io/>`__
 * `Wagtail <https://docs.wagtail.io/>`__
-* `Web Application Attack and Audit Framework (w3af) <http://docs.w3af.org/>`__
+* `Web Application Attack and Audit Framework (w3af) <https://docs.w3af.org/>`__
 * `Weblate <https://docs.weblate.org/>`__
 * `x265 <https://x265.readthedocs.io/>`__
 * `Zulip <https://zulip.readthedocs.io/>`__
@@ -296,14 +297,14 @@ Documentation using sphinx_bootstrap_theme

 * `Bootstrap Theme <https://ryan-roemer.github.io/sphinx-bootstrap-theme/>`__
 * `C/C++ Software Development with Eclipse <https://eclipsebook.in/>`__
-* `Dataverse <http://guides.dataverse.org/>`__
+* `Dataverse <https://guides.dataverse.org/>`__
 * `e-cidadania <https://e-cidadania.readthedocs.io/>`__
-* `Hangfire <http://docs.hangfire.io/>`__
+* `Hangfire <https://docs.hangfire.io/>`__
 * `Hedge <https://documen.tician.de/hedge/>`__
 * `ObsPy <https://docs.obspy.org/>`__
 * `Open Dylan <https://opendylan.org/documentation/>`__
 * `OPNFV <https://docs.opnfv.org/>`__
-* `Pootle <http://docs.translatehouse.org/projects/pootle/>`__
+* `Pootle <https://docs.translatehouse.org/projects/pootle/>`__
 * `PyUblas <https://documen.tician.de/pyublas/>`__
 * `seaborn <https://seaborn.pydata.org/>`__

@@ -312,12 +313,12 @@ Documentation using a custom theme or integrated in a website

 * `AIOHTTP <https://docs.aiohttp.org/>`__
 * `Apache Cassandra <https://cassandra.apache.org/doc/>`__
-* `Astropy <http://docs.astropy.org/>`__
+* `Astropy <https://docs.astropy.org/>`__
 * `Bokeh <https://bokeh.pydata.org/>`__
 * `Boto 3 <https://boto3.readthedocs.io/>`__
 * `CakePHP <https://book.cakephp.org/>`__
 * `CasperJS <http://docs.casperjs.org/>`__
-* `Ceph <http://docs.ceph.com/docs/master/>`__
+* `Ceph <https://docs.ceph.com/docs/master/>`__
 * `Chef <https://docs.chef.io/>`__
 * `CKAN <https://docs.ckan.org/>`__
 * `Confluent Platform <https://docs.confluent.io/>`__
@@ -326,24 +327,24 @@ Documentation using a custom theme or integrated in a website
 * `Enterprise Toolkit for Acrobat products <https://www.adobe.com/devnet-docs/acrobatetk/>`__
 * `FreeFEM <https://doc.freefem.org/introduction/>`__
 * `fmt <https://fmt.dev/>`__
-* `Gameduino <http://excamera.com/sphinx/gameduino/>`__
+* `Gameduino <https://excamera.com/sphinx/gameduino/>`__
 * `gensim <https://radimrehurek.com/gensim/>`__
-* `GeoServer <http://docs.geoserver.org/>`__
-* `gevent <http://www.gevent.org/>`__
+* `GeoServer <https://docs.geoserver.org/>`__
+* `gevent <https://www.gevent.org/>`__
 * `GHC - Glasgow Haskell Compiler <https://downloads.haskell.org/~ghc/master/users-guide/>`__
-* `Guzzle <http://docs.guzzlephp.org/>`__
-* `H2O.ai <http://docs.h2o.ai/>`__
+* `Guzzle <https://docs.guzzlephp.org/>`__
+* `H2O.ai <https://docs.h2o.ai/>`__
 * `Heka <https://hekad.readthedocs.io/>`__
 * `Istihza (Turkish Python documentation project) <https://belgeler.yazbel.com/python-istihza/>`__
 * `JupyterHub <https://jupyterhub.readthedocs.io/>`__
 * `Kombu <http://docs.kombu.me/>`__
-* `Lasso <http://lassoguide.com/>`__
-* `Mako <http://docs.makotemplates.org/>`__
-* `MirrorBrain <http://mirrorbrain.org/docs/>`__
+* `Lasso <https://lassoguide.com/>`__
+* `Mako <https://docs.makotemplates.org/>`__
+* `MirrorBrain <https://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/>`__
+* `MyHDL <https://docs.myhdl.org/>`__
 * `ndnSIM <https://ndnsim.net/current/>`__
 * `nose <https://nose.readthedocs.io/>`__
 * `ns-3 <https://www.nsnam.org/documentation/>`__
@@ -353,30 +354,30 @@ Documentation using a custom theme or integrated in a website
 * `OpenCV <https://docs.opencv.org/>`__
 * `OpenLayers <http://docs.openlayers.org/>`__
 * `OpenTURNS <https://openturns.github.io/openturns/master/>`__
-* `Open vSwitch <http://docs.openvswitch.org/>`__
+* `Open vSwitch <https://docs.openvswitch.org/>`__
 * `PlatformIO <https://docs.platformio.org/>`__
-* `PyEphem <http://rhodesmill.org/pyephem/>`__
-* `Pygments <http://pygments.org/docs/>`__
+* `PyEphem <https://rhodesmill.org/pyephem/>`__
+* `Pygments <https://pygments.org/docs/>`__
 * `Plone User Manual (German) <https://www.hasecke.com/plone-benutzerhandbuch/4.0/>`__
-* `PSI4 <http://www.psicode.org/psi4manual/master/index.html>`__
+* `PSI4 <https://www.psicode.org/psi4manual/master/index.html>`__
 * `PyMOTW <https://pymotw.com/2/>`__
 * `python-aspectlib <https://python-aspectlib.readthedocs.io/>`__ (`sphinx_py3doc_enhanced_theme <https://pypi.org/project/sphinx_py3doc_enhanced_theme/>`__)
 * `QGIS <https://qgis.org/en/docs/index.html>`__
 * `qooxdoo <https://www.qooxdoo.org/current/>`__
-* `Roundup <http://www.roundup-tracker.org/>`__
+* `Roundup <https://www.roundup-tracker.org/>`__
 * `SaltStack <https://docs.saltstack.com/>`__
-* `scikit-learn <http://scikit-learn.org/stable/>`__
+* `scikit-learn <https://scikit-learn.org/stable/>`__
 * `SciPy <https://docs.scipy.org/doc/scipy/reference/>`__
 * `Scrapy <https://doc.scrapy.org/>`__
 * `Seaborn <https://seaborn.pydata.org/>`__
 * `Selenium <https://docs.seleniumhq.org/docs/>`__
-* `Self <http://www.selflanguage.org/>`__
+* `Self <https://www.selflanguage.org/>`__
 * `Substance D <https://docs.pylonsproject.org/projects/substanced/>`__
-* `Sulu <http://docs.sulu.io/>`__
+* `Sulu <https://docs.sulu.io/>`__
 * `SQLAlchemy <https://docs.sqlalchemy.org/>`__
 * `tinyTiM <http://tinytim.sourceforge.net/docs/2.0/>`__
 * `Twisted <https://twistedmatrix.com/documents/current/>`__
-* `Ubuntu Packaging Guide <http://packaging.ubuntu.com/html/>`__
+* `Ubuntu Packaging Guide <https://packaging.ubuntu.com/html/>`__
 * `WebFaction <https://docs.webfaction.com/>`__
 * `WTForms <https://wtforms.readthedocs.io/>`__

@@ -387,7 +388,7 @@ Homepages and other non-documentation sites
 * `Benoit Boissinot <https://bboissin.appspot.com/>`__ (classic, customized)
 * `Computer Networks, Parallelization, and Simulation Laboratory (CNPSLab) <https://lab.miletic.net/>`__ (sphinx_rtd_theme)
 * `Deep Learning Tutorials <http://www.deeplearning.net/tutorial/>`__ (sphinxdoc)
-* `Eric Holscher <http://ericholscher.com/>`__ (alabaster)
+* `Eric Holscher <https://ericholscher.com/>`__ (alabaster)
 * `Lei Ma's Statistical Mechanics lecture notes <http://statisticalphysics.openmetric.org/>`__ (sphinx_bootstrap_theme)
 * `Loyola University Chicago COMP 339-439 Distributed Systems course <https://books.cs.luc.edu/distributedsystems/>`__ (sphinx_bootstrap_theme)
 * `Pylearn2 <http://www.deeplearning.net/software/pylearn2/>`__ (sphinxdoc, customized)
@@ -408,7 +409,7 @@ Books produced using Sphinx
 * `"Expert Python Programming" (Japanese translation) <https://www.amazon.co.jp/dp/4048686291/>`__
 * `"Expert Python Programming 2nd Edition" (Japanese translation) <https://www.amazon.co.jp/dp/4048930613/>`__
 * `"The Hitchhiker's Guide to Python" <https://docs.python-guide.org/>`__
-* `"LassoGuide" <http://www.lassosoft.com/Lasso-Documentation>`__
+* `"LassoGuide" <https://www.lassosoft.com/Lasso-Documentation>`__
 * `"Learning Sphinx" (in Japanese) <https://www.oreilly.co.jp/books/9784873116488/>`__
 * `"Learning System Programming with Go (Japanese)" <https://www.lambdanote.com/products/go>`__
 * `"Mercurial: the definitive guide (Second edition)" <https://book.mercurial-scm.org/>`__
@@ -416,7 +417,7 @@ Books produced using Sphinx
 * `"Pioneers and Prominent Men of Utah" <http://pioneers.rstebbing.com/>`__
 * `"Pomodoro Technique Illustrated" (Japanese translation) <https://www.amazon.co.jp/dp/4048689525/>`__
 * `"Professional Software Development" <https://mixmastamyk.bitbucket.io/pro_soft_dev/>`__
-* `"Python Professional Programming" (in Japanese) <http://www.amazon.co.jp/dp/4798032948/>`__
+* `"Python Professional Programming" (in Japanese) <https://www.amazon.co.jp/dp/4798032948/>`__
 * `"Python Professional Programming 2nd Edition" (in Japanese) <https://www.amazon.co.jp/dp/479804315X/>`__
 * `"Python Professional Programming 3rd Edition" (in Japanese) <https://www.amazon.co.jp/dp/4798053821/>`__
 * `Python Course by Yuri Petrov (Russian) <https://www.yuripetrov.ru/edu/python>`__
--- a/babel.cfg
+++ b/babel.cfg
@@ -1,7 +1,7 @@
 # How to setup this file
-# http://babel.pocoo.org/en/latest/installation.html
+# https://babel.pocoo.org/en/latest/installation.html
 # this file description:
-# http://babel.pocoo.org/en/latest/messages.html
+# https://babel.pocoo.org/en/latest/messages.html

 # Extraction from Python source files
 [python: **.py]
--- a/doc/_static/tutorial/lumache-first-light.png
+++ b/doc/_static/tutorial/lumache-first-light.png
--- a/doc/_templates/index.html
+++ b/doc/_templates/index.html
@@ -29,19 +29,19 @@
    <li>{%trans%}<b>Automatic indices:</b> general index as well as a language-specific
      module indices{%endtrans%}</li>
    <li>{%trans%}<b>Code handling:</b> automatic highlighting using the <a
-      href="http://pygments.org">Pygments</a> highlighter{%endtrans%}</li>
+      href="https://pygments.org">Pygments</a> highlighter{%endtrans%}</li>
    <li>{%trans path=pathto('ext/builtins')%}<b>Extensions:</b> automatic testing of code snippets, inclusion of
      docstrings from Python modules (API docs), and
      <a href="{{ path }}#builtin-sphinx-extensions">more</a>{%endtrans%}</li>
-    <li>{%trans path=pathto("usage/extensions")%}<b>Contributed extensions:</b> dozens of
+    <li>{%trans path=pathto("usage/extensions/index")%}<b>Contributed extensions:</b> dozens of
      extensions <a href="{{ path }}#third-party-extensions">contributed by users</a>;
      most of them installable from PyPI{%endtrans%}</li>
  </ul>
  <p>{%trans%}
-    Sphinx uses <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>
+    Sphinx uses <a href="https://docutils.sourceforge.io/rst.html">reStructuredText</a>
    as its markup language, and many of its strengths come from the power and
    straightforwardness of reStructuredText and its parsing and translating
-    suite, the <a href="http://docutils.sourceforge.net/">Docutils</a>.{%endtrans%}
+    suite, the <a href="https://docutils.sourceforge.io/">Docutils</a>.{%endtrans%}
  </p>

  <h2 style="margin-bottom: 0">{%trans%}Documentation{%endtrans%}</h2>
@@ -52,23 +52,25 @@
        <p class="biglink"><a class="biglink" href="{{ pathto("usage/quickstart") }}">{%trans%}First steps with Sphinx{%endtrans%}</a><br/>
           <span class="linkdescr">{%trans%}overview of basic tasks{%endtrans%}</span></p>
      </td><td>
-        {%- if hasdoc('search') %}<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{%trans%}Search page{%endtrans%}</a><br/>
-           <span class="linkdescr">{%trans%}search the documentation{%endtrans%}</span></p>{%- endif %}
+        <p class="biglink"><a class="biglink" href="{{ pathto("tutorial/index") }}">{%trans%}Tutorial{%endtrans%}</a><br/>
+           <span class="linkdescr">{%trans%}beginners tutorial{%endtrans%}</span></p>
      </td>
    </tr><tr>
      <td>
        <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{%trans%}Contents{%endtrans%}</a><br/>
           <span class="linkdescr">{%trans%}for a complete overview{%endtrans%}</span></p>
      </td><td>
-        {%- if hasdoc('genindex') %}<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{%trans%}General Index{%endtrans%}</a><br/>
-           <span class="linkdescr">{%trans%}all functions, classes, terms{%endtrans%}</span></p>{%- endif %}
+        {%- if hasdoc('search') %}<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{%trans%}Search page{%endtrans%}</a><br/>
+           <span class="linkdescr">{%trans%}search the documentation{%endtrans%}</span></p>{%- endif %}
      </td>
    </tr><tr>
      <td>
        <p class="biglink"><a class="biglink" href="{{ pathto("changes") }}">{%trans%}Changes{%endtrans%}</a><br/>
           <span class="linkdescr">{%trans%}release history{%endtrans%}</span></p>
      </td><td>
-      </td>
+        {%- if hasdoc('genindex') %}<p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{%trans%}General Index{%endtrans%}</a><br/>
+           <span class="linkdescr">{%trans%}all functions, classes, terms{%endtrans%}</span></p>{%- endif %}
+      </td><td>
    </tr>
  </table>

--- a/doc/conf.py
+++ b/doc/conf.py
@@ -35,7 +35,7 @@ htmlhelp_basename = 'Sphinxdoc'
 epub_theme = 'epub'
 epub_basename = 'sphinx'
 epub_author = 'Georg Brandl'
-epub_publisher = 'http://sphinx-doc.org/'
+epub_publisher = 'https://sphinx-doc.org/'
 epub_uid = 'web-site'
 epub_scheme = 'url'
 epub_identifier = epub_publisher
@@ -80,11 +80,11 @@ latex_use_xindy = True
 autodoc_member_order = 'groupwise'
 autosummary_generate = False
 todo_include_todos = True
-extlinks = {'duref': ('http://docutils.sourceforge.net/docs/ref/rst/'
+extlinks = {'duref': ('https://docutils.sourceforge.io/docs/ref/rst/'
                      'restructuredtext.html#%s', ''),
-            'durole': ('http://docutils.sourceforge.net/docs/ref/rst/'
+            'durole': ('https://docutils.sourceforge.io/docs/ref/rst/'
                       'roles.html#%s', ''),
-            'dudir': ('http://docutils.sourceforge.net/docs/ref/rst/'
+            'dudir': ('https://docutils.sourceforge.io/docs/ref/rst/'
                      'directives.html#%s', '')}

 man_pages = [
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -7,6 +7,7 @@ Sphinx documentation contents
   :maxdepth: 2

   usage/index
+   tutorial/index
   development/index
   man/index

--- a/doc/development/theming.rst
+++ b/doc/development/theming.rst
@@ -207,9 +207,9 @@ inside your module:
 First, define the registration function, which accepts the arguments for
 :event:`html-page-context`.

-Within the registration function, define the template function that you'd like to use
-within Jinja. The template function should return a string or Python objects (lists,
-dictionaries) with strings inside that Jinja uses in the templating process
+Within the registration function, define the template function that you'd like to
+use within Jinja. The template function should return a string or Python objects
+(lists, dictionaries) with strings inside that Jinja uses in the templating process

 .. note::

@@ -256,6 +256,9 @@ Here is some sample code to accomplish this:

 .. code-block:: python

+   from os import path
+   from sphinx.util.fileutil import copy_asset_file
+
   def copy_custom_files(app, exc):
       if app.builder.format == 'html' and not exc:
           staticdir = path.join(app.builder.outdir, '_static')
--- a/doc/development/tutorials/helloworld.rst
+++ b/doc/development/tutorials/helloworld.rst
@@ -181,9 +181,9 @@ This is the very basic principle of an extension that creates a new directive.
 For a more advanced example, refer to :doc:`todo`.


-.. _docutils: http://docutils.sourceforge.net/
-.. _docutils directives: http://docutils.sourceforge.net/docs/howto/rst-directives.html
-.. _docutils nodes: http://docutils.sourceforge.net/docs/ref/doctree.html
+.. _docutils: https://docutils.sourceforge.io/
+.. _docutils directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html
+.. _docutils nodes: https://docutils.sourceforge.io/docs/ref/doctree.html
 .. _PyPI: https://pypi.org/
 .. _Python package: https://packaging.python.org/
 .. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
--- a/doc/development/tutorials/recipe.rst
+++ b/doc/development/tutorials/recipe.rst
@@ -223,4 +223,4 @@ Further reading
 For more information, refer to the `docutils`_ documentation and
 :doc:`/extdev/index`.

-.. _docutils: http://docutils.sourceforge.net/docs/
+.. _docutils: https://docutils.sourceforge.io/docs/
--- a/doc/development/tutorials/todo.rst
+++ b/doc/development/tutorials/todo.rst
@@ -105,7 +105,7 @@ is just a "general" node.

   Many extensions will not have to create their own node classes and work fine
   with the nodes already provided by `docutils
-   <http://docutils.sourceforge.net/docs/ref/doctree.html>`__ and :ref:`Sphinx
+   <https://docutils.sourceforge.io/docs/ref/doctree.html>`__ and :ref:`Sphinx
   <nodes>`.

 .. attention::
@@ -362,6 +362,6 @@ For more information, refer to the `docutils`_ documentation and
 :doc:`/extdev/index`.


-.. _docutils: http://docutils.sourceforge.net/docs/
+.. _docutils: https://docutils.sourceforge.io/docs/
 .. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
-.. _docutils documentation: http://docutils.sourceforge.net/docs/ref/rst/directives.html
+.. _docutils documentation: https://docutils.sourceforge.io/docs/ref/rst/directives.html
--- a/doc/extdev/appapi.rst
+++ b/doc/extdev/appapi.rst
@@ -159,7 +159,9 @@ connect handlers to the events.  Example:

 Below is an overview of each event that happens during a build. In the list
 below, we include the event name, its callback parameters, and the input and output
-type for that event::
+type for that event:
+
+.. code-block:: none

   1. event.config-inited(app,config)
   2. event.builder-inited(app)
@@ -168,7 +170,7 @@ type for that event::

   for docname in docnames:
      5. event.env-purge-doc(app, env, docname)
-      
+
      if doc changed and not removed:
         6. source-read(app, docname, source)
         7. run source parsers: text -> docutils.document
@@ -176,10 +178,10 @@ type for that event::
         8. apply transforms based on priority: docutils.document -> docutils.document
            - event.doctree-read(app, doctree) is called in the middle of transforms,
              transforms come before/after this event depending on their priority.
-   
+
   9. event.env-merge-info(app, env, docnames, other)
      - if running in parallel mode, this event will be emitted for each process
-   
+
   10. event.env-updated(app, env)
   11. event.env-get-updated(app, env)
   12. event.env-check-consistency(app, env)
@@ -377,13 +379,22 @@ Here is a more detailed list of these events.
   ``'page.html'`` as the HTML template for this page.

   .. note:: You can install JS/CSS files for the specific page via
-             :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since v3.5.0.
+             :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since
+             v3.5.0.

   .. versionadded:: 0.4

   .. versionchanged:: 1.3
      The return value can now specify a template name.

+.. event:: linkcheck-process-uri (app, uri)
+
+   Emitted when the linkcheck builder collects hyperlinks from document.  *uri*
+   is a collected URI.  The event handlers can modify the URI by returning a
+   string.
+
+   .. versionadded:: 4.1
+
 .. event:: build-finished (app, exception)

   Emitted when a build has finished, before Sphinx exits, usually used for
--- a/doc/extdev/deprecated.rst
+++ b/doc/extdev/deprecated.rst
@@ -22,11 +22,21 @@ The following is a list of deprecated interfaces.
     - (will be) Removed
     - Alternatives

+   * - The optional argument ``app`` for ``sphinx.environment.BuildEnvironment``
+     - 4.1
+     - 6.0
+     - The required argument
+
   * - ``sphinx.application.Sphinx.html_theme``
     - 4.1
     - 6.0
     - ``sphinx.registry.SphinxComponentRegistry.html_themes``

+   * - ``sphinx.ext.autosummary._app``
+     - 4.1
+     - 6.0
+     - N/A
+
   * - ``sphinx.util.docstrings.extract_metadata()``
     - 4.1
     - 6.0
@@ -740,8 +750,9 @@ The following is a list of deprecated interfaces.

   * - ``sphinx.environment.NoUri``
     - 2.1
-     - 4.0
+     - 3.0
     - ``sphinx.errors.NoUri``
+
   * - ``sphinx.ext.apidoc.format_directive()``
     - 2.1
     - 4.0
@@ -1025,7 +1036,7 @@ The following is a list of deprecated interfaces.

   * - ``sphinx.util.force_decode()``
     - 2.0
-     - 4.0
+     - 5.0
     - N/A

   * - ``sphinx.util.get_matching_docs()``
--- a/doc/extdev/i18n.rst
+++ b/doc/extdev/i18n.rst
@@ -94,4 +94,4 @@ message catalog template and message catalogs, for example via `Babel`_:
   $ pybabel extract --output=src/locale/myextension.pot src/
   $ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale

-.. _Babel: http://babel.pocoo.org/
+.. _Babel: https://babel.pocoo.org/
--- a/doc/extdev/index.rst
+++ b/doc/extdev/index.rst
@@ -112,7 +112,7 @@ in which a Sphinx project is built: this works in several phases.
   existing files are read, temporary nodes are created.

   There are nodes provided by docutils, which are documented `in the docutils
-   documentation <http://docutils.sourceforge.net/docs/ref/doctree.html>`__.
+   documentation <https://docutils.sourceforge.io/docs/ref/doctree.html>`__.
   Additional nodes are provided by Sphinx and :ref:`documented here <nodes>`.

   During reading, the build environment is updated with all meta- and cross
--- a/doc/extdev/markupapi.rst
+++ b/doc/extdev/markupapi.rst
@@ -149,4 +149,4 @@ return ``node.children`` from the Directive.

   `Creating directives`_ HOWTO of the Docutils documentation

-.. _Creating directives: http://docutils.sourceforge.net/docs/howto/rst-directives.html
+.. _Creating directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html
--- a/doc/extdev/parserapi.rst
+++ b/doc/extdev/parserapi.rst
@@ -8,7 +8,7 @@ Parser API
    The Parser analyzes the input document and creates a node tree
    representation.

-__ http://docutils.sourceforge.net/docs/dev/hacking.html#parsing-the-document
+__ https://docutils.sourceforge.io/docs/dev/hacking.html#parsing-the-document

 In Sphinx, the parser modules works as same as docutils.  The parsers are
 registered to Sphinx by extensions using Application APIs;
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -145,7 +145,7 @@ Google Search

 .. _Getting Started: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
 .. _api role: https://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
-.. _xhtml to reST: http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py
+.. _xhtml to reST: https://docutils.sourceforge.io/sandbox/xhtml2rest/xhtml2rest.py


 Sphinx vs. Docutils
@@ -179,10 +179,10 @@ of the *writers* provided by docutils. This allows Sphinx to provide many
 features that would simply not be possible with docutils, such as those
 outlined above.

-__ http://docutils.sourceforge.io/
-__ http://docutils.sourceforge.io/docs/dev/hacking.html
-__ http://docutils.sourceforge.io/rst.html
-__ http://docutils.sourceforge.net/docs/user/tools.html
+__ https://docutils.sourceforge.io/
+__ https://docutils.sourceforge.io/docs/dev/hacking.html
+__ https://docutils.sourceforge.io/rst.html
+__ https://docutils.sourceforge.io/docs/user/tools.html


 .. _epub-faq:
@@ -259,7 +259,9 @@ The following list gives some hints for the creation of epub files:

     ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``

-  If you get the following error, fix your document structure::
+  If you get the following error, fix your document structure:
+
+  .. code-block:: none

     Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
     Error(prcgen):E24001: The table of content could not be built.
--- a/doc/internals/contributing.rst
+++ b/doc/internals/contributing.rst
@@ -251,7 +251,7 @@ The parts of messages in Sphinx that go into builds are translated into several
 locales.  The translations are kept as gettext ``.po`` files translated from the
 master template :file:`sphinx/locale/sphinx.pot`.

-Sphinx uses `Babel <http://babel.pocoo.org/en/latest/>`_ to extract messages
+Sphinx uses `Babel <https://babel.pocoo.org/en/latest/>`_ to extract messages
 and maintain the catalog files.  It is integrated in ``setup.py``:

 * Use ``python setup.py extract_messages`` to update the ``.pot`` template.
@@ -297,7 +297,7 @@ Debugging tips
  will complain about references without a known target.

 * Set the debugging options in the `Docutils configuration file
-  <http://docutils.sourceforge.net/docs/user/config.html>`_.
+  <https://docutils.sourceforge.io/docs/user/config.html>`_.

 * JavaScript stemming algorithms in ``sphinx/search/*.py`` (except ``en.py``)
  are generated by this `modified snowballcode generator
--- a/doc/latex.rst
+++ b/doc/latex.rst
@@ -282,7 +282,29 @@ Keys that don't need to be overridden unless in special cases are:
   "inputenc" package inclusion.

   Default: ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex, else
-   ``''``
+   ``''``.
+
+   .. note::
+
+      If using ``utf8x`` in place of ``utf8`` it is mandatory to extend the
+      LaTeX preamble with suitable ``\PreloadUnicodePage{<number>}`` commands,
+      as per the ``utf8x`` documentation (``texdoc ucs`` on a TeXLive based
+      TeX installation).  Else, unexpected and possibly hard-to-spot problems
+      (i.e. not causing a build crash) may arise in the PDF, in particular
+      regarding hyperlinks.
+
+      Even if these precautions are taken, PDF build via ``pdflatex`` engine
+      may crash due to upstream LaTeX not being fully compatible with
+      ``utf8x``.  For example, in certain circumstances related to
+      code-blocks, or attempting to include images whose filenames contain
+      Unicode characters.  Indeed, starting in 2015, upstream LaTeX with
+      ``pdflatex`` engine has somewhat enhanced native support for Unicode and
+      is becoming more and more incompatible with ``utf8x``.  In particular,
+      since the October 2019 LaTeX release, filenames can use Unicode
+      characters, and even spaces.  At Sphinx level this means e.g. that the
+      :dudir:`image` and :dudir:`figure` directives are now compatible with
+      such filenames for PDF via LaTeX output.  But this is broken if
+      ``utf8x`` is in use.

   .. versionchanged:: 1.4.3
      Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all
--- a/doc/make.bat
+++ b/doc/make.bat
@@ -19,7 +19,7 @@ if errorlevel 9009 (
 	echo.may add the Sphinx directory to PATH.
 	echo.
 	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
+	echo.https://sphinx-doc.org/
 	exit /b 1
 )

--- a/doc/templating.rst
+++ b/doc/templating.rst
@@ -6,10 +6,11 @@
 Templating
 ==========

-Sphinx uses the `Jinja <http://jinja.pocoo.org>`_ templating engine for its HTML
-templates.  Jinja is a text-based engine, inspired by Django templates, so
-anyone having used Django will already be familiar with it.  It also has
-excellent documentation for those who need to make themselves familiar with it.
+Sphinx uses the `Jinja <https://jinja.palletsprojects.com/>`_ templating engine
+for its HTML templates.  Jinja is a text-based engine, inspired by Django
+templates, so anyone having used Django will already be familiar with it. It
+also has excellent documentation for those who need to make themselves familiar
+with it.


 Do I need to use Sphinx's templates to produce HTML?
--- a/doc/tutorial/index.rst
+++ b/doc/tutorial/index.rst
@@ -0,0 +1,192 @@
+.. _tutorial:
+
+===============
+Sphinx tutorial
+===============
+
+In this tutorial you will build a simple documentation project using Sphinx, and
+view it in your browser as HTML.  The project will include narrative,
+handwritten documentation, as well as autogenerated API documentation.
+
+The tutorial is aimed towards Sphinx newcomers willing to learn the fundamentals
+of how projects are created and structured.  You will create a fictional
+software library to generate random food recipes that will serve as a guide
+throughout the process, with the objective of properly documenting it.
+
+To showcase Sphinx capabilities for code documentation you will use Python,
+which also supports *automatic* documentation generation.
+
+.. note::
+
+   Several other languages are natively supported in Sphinx for *manual* code
+   documentation, however they require extensions for *automatic* code
+   documentation, like `Breathe <https://breathe.readthedocs.io/>`_.
+
+To follow the instructions you will need access to a Linux-like command line and
+a basic understanding of how it works, as well as a working Python installation
+for development, since you will use *Python virtual environments* to create the
+project.
+
+Getting started
+---------------
+
+Setting up your project and development environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In a new directory, create a file called ``README.rst`` with the following
+content.
+
+.. code-block:: rest
+
+   Lumache
+   =======
+
+   **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
+   creates recipes mixing random ingredients.
+
+It is a good moment to create a Python virtual environment and install the
+required tools.  For that, open a command line terminal, ``cd`` into the
+directory you just created, and run the following commands:
+
+.. code-block:: console
+
+   $ python -m venv .venv
+   $ source .venv/bin/activate
+   (.venv) $ python -m pip install sphinx
+
+.. note::
+
+   The installation method used above is described in more detail in
+   :ref:`install-pypi`.  For the rest of this tutorial, the instructions will
+   assume a Python virtual environment.
+
+If you executed these instructions correctly, you should have the Sphinx command
+line tools available.  You can do a basic verification running this command:
+
+.. code-block:: console
+
+   (.venv) $ sphinx-build --version
+   sphinx-build 4.0.2
+
+If you see a similar output, you are on the right path!
+
+Creating the documentation layout
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Then from the command line, run the following command:
+
+.. code-block:: console
+
+   (.venv) $ sphinx-quickstart docs
+
+This will present to you a series of questions required to create the basic
+directory and configuration layout for your project inside the ``docs`` folder.
+To proceed, answer each question as follows:
+
+- ``> Separate source and build directories (y/n) [n]``: Write "``y``" (without
+  quotes) and press :kbd:`Enter`.
+- ``> Project name``: Write "``Lumache``" (without quotes) and press
+  :kbd:`Enter`.
+- ``> Author name(s)``: Write "``Graziella``" (without quotes) and press
+  :kbd:`Enter`.
+- ``> Project release []``: Write "``0.1``" (without quotes) and press
+  :kbd:`Enter`.
+- ``> Project language [en]``: Leave it empty (the default, English) and press
+  :kbd:`Enter`.
+
+After the last question, you will see the new ``docs`` directory with the
+following content.
+
+.. code-block:: text
+
+   docs
+   ├── build
+   ├── make.bat
+   ├── Makefile
+   └── source
+      ├── conf.py
+      ├── index.rst
+      ├── _static
+      └── _templates
+
+The purpose of each of these files is:
+
+``build/``
+  An empty directory (for now) that will hold the rendered documentation.
+
+``make.bat`` and ``Makefile``
+  Convenience scripts to simplify some common Sphinx operations, such as
+  rendering the content.
+
+``source/conf.py``
+  A Python script holding the configuration of the Sphinx project.  It contains
+  the project name and release you specified to ``sphinx-quickstart``, as well
+  as some extra configuration keys.
+
+``source/index.rst``
+  The :term:`master document` of the project, which serves as welcome page and
+  contains the root of the "table of contents tree" (or *toctree*).
+
+Thanks to this bootstrapping step, you already have everything needed to render
+the documentation as HTML for the first time.  To do that, run this command:
+
+.. code-block:: console
+
+   (.venv) $ sphinx-build -b html docs/source/ docs/build/html
+
+And finally, open `docs/build/html/index.html` in your browser.  You should see
+something like this:
+
+.. image:: /_static/tutorial/lumache-first-light.png
+
+There we go! You created your first HTML documentation using Sphinx.
+
+Making some tweaks to the index
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``index.rst`` file that ``sphinx-quickstart`` created has some content
+already, and it gets rendered as the front page of our HTML documentation.  It
+is written in reStructuredText, a powerful markup language.
+
+Modify the file as follows:
+
+.. code-block:: rest
+
+   Welcome to Lumache's documentation!
+   ===================================
+
+   **Lumache** (/lu'make/) is a Python library for cooks and food lovers that
+   creates recipes mixing random ingredients.  It pulls data from the `Open Food
+   Facts database <https://world.openfoodfacts.org/>`_ and offers a *simple* and
+   *intuitive* API.
+
+   .. note::
+
+      This project is under active development.
+
+This showcases several features of the reStructuredText syntax, including:
+
+- a **section header** using ``===`` for the underline,
+- two examples of :ref:`rst-inline-markup`: ``**strong emphasis**`` (typically
+  bold) and ``*emphasis*`` (typically italics),
+- an **inline external link**,
+- and a ``note`` **admonition** (one of the available :ref:`directives
+  <rst-directives>`)
+
+Now to render it with the new content, you can use the ``sphinx-build`` command
+as before, or leverage the convenience script as follows:
+
+.. code-block:: console
+
+   (.venv) $ cd docs
+   (.venv) $ make html
+
+After running this command, you will see that ``index.html`` reflects the new
+changes!
+
+Where to go from here
+---------------------
+
+This tutorial covered the very first steps to create a documentation project
+with Sphinx.  To continue learning more about Sphinx, check out the :ref:`rest
+of the documentation <contents>`.
--- a/doc/usage/advanced/intl.rst
+++ b/doc/usage/advanced/intl.rst
@@ -13,7 +13,7 @@ navigation bars, Sphinx provides mechanisms facilitating the translation of
   :width: 100%

   Workflow visualization of translations in Sphinx.  (The figure is created by
-   `plantuml <http://plantuml.com>`_.)
+   `plantuml <https://plantuml.com>`_.)

 .. contents::
   :local:
@@ -118,7 +118,7 @@ section describe an easy way to translate with *sphinx-intl*.

 #. Translate po files.

-   AS noted above, these are located in the ``./locale/<lang>/LC_MESSAGES``
+   As noted above, these are located in the ``./locale/<lang>/LC_MESSAGES``
   directory.  An example of one such file, from Sphinx, ``builders.po``, is
   given below.

@@ -193,7 +193,7 @@ pot file to the po file, use the :command:`sphinx-intl update` command.

 .. code-block:: console

-   $ sphinx-intl update -p _build/locale
+   $ sphinx-intl update -p _build/gettext


 Using Transifex service for team translation
--- a/doc/usage/advanced/websupport/quickstart.rst
+++ b/doc/usage/advanced/websupport/quickstart.rst
@@ -61,7 +61,7 @@ This will return a dictionary containing the following items:

 This dict can then be used as context for templates.  The goal is to be easy to
 integrate with your existing templating system.  An example using `Jinja2
-<http://jinja.pocoo.org/>`_ is:
+<https://jinja.palletsprojects.com/>`_ is:

 .. code-block:: html+jinja

@@ -112,8 +112,8 @@ must update the websupport package's data::
 should be a boolean representing whether the user has moderation privileges.
 The default value for *moderator* is ``False``.

-An example `Flask <http://flask.pocoo.org/>`_ function that checks whether a
-user is logged in and then retrieves a document is::
+An example `Flask <https://flask.palletsprojects.com/>`_ function that checks
+whether a user is logged in and then retrieves a document is::

   from sphinxcontrib.websupport.errors import *

@@ -152,8 +152,8 @@ To use the search form built-in to the Sphinx sidebar, create a function to
 handle requests to the URL 'search' relative to the documentation root.  The
 user's search query will be in the GET parameters, with the key `q`.  Then use
 the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to
-retrieve search results. In `Flask <http://flask.pocoo.org/>`_ that would be
-like this::
+retrieve search results. In `Flask <https://flask.palletsprojects.com/>`_ that
+would be like this::

   @app.route('/search')
   def search():
--- a/doc/usage/configuration.rst
+++ b/doc/usage/configuration.rst
@@ -18,8 +18,8 @@ and output behavior.
  directory to adjust `Docutils`_ configuration if not otherwise overridden or
  set by Sphinx.

-  .. _`docutils`: http://docutils.sourceforge.net/
-  .. _`docutils.conf`: http://docutils.sourceforge.net/docs/user/config.html
+  .. _`docutils`: https://docutils.sourceforge.io/
+  .. _`docutils.conf`: https://docutils.sourceforge.io/docs/user/config.html

 The configuration file is executed as Python code at build time (using
 :func:`execfile`, and with the current directory set to its containing
@@ -484,7 +484,7 @@ General configuration
   languages, will be used to convert quotes and dashes to typographically
   correct entities.  Default: ``True``.

-   __ http://docutils.sourceforge.net/docs/user/smartquotes.html
+   __ https://docutils.sourceforge.io/docs/user/smartquotes.html
   __ https://daringfireball.net/projects/smartypants/

   .. versionadded:: 1.6.6
@@ -497,8 +497,8 @@ General configuration
   *deactivates* smart quotes via the corresponding `Docutils option`__.  But
   if it *activates* them, then :confval:`smartquotes` does prevail.

-   __ http://docutils.sourceforge.net/docs/user/config.html
-   __ http://docutils.sourceforge.net/docs/user/config.html#smart-quotes
+   __ https://docutils.sourceforge.io/docs/user/config.html
+   __ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes

 .. confval:: smartquotes_action

@@ -591,17 +591,18 @@ General configuration
 .. confval:: highlight_language

   The default language to highlight source code in.  The default is
-   ``'python3'``.  The value should be a valid Pygments lexer name, see
+   ``'default'``.  It is similar to ``'python3'``; it is mostly a superset of
+   ``'python'`` but it fallbacks to ``'none'`` without warning if failed.
+   ``'python3'`` and other languages will emit warning if failed.
+
+   The value should be a valid Pygments lexer name, see
   :ref:`code-examples` for more details.

   .. versionadded:: 0.5

   .. versionchanged:: 1.4
-      The default is now ``'default'``. It is similar to ``'python3'``;
-      it is mostly a superset of ``'python'`` but it fallbacks to
-      ``'none'`` without warning if failed.  ``'python3'`` and other
-      languages will emit warning if failed.  If you prefer Python 2
-      only highlighting, you can set it back to ``'python'``.
+      The default is now ``'default'``.  If you prefer Python 2 only
+      highlighting, you can set it back to ``'python'``.

 .. confval:: highlight_options

@@ -1051,7 +1052,7 @@ that use Sphinx's HTMLWriter class.
   A list of CSS files.  The entry must be a *filename* string or a tuple
   containing the *filename* string and the *attributes* dictionary.  The
   *filename* must be relative to the :confval:`html_static_path`, or a full URI
-   with scheme like ``http://example.org/style.css``.  The *attributes* is used
+   with scheme like ``https://example.org/style.css``.  The *attributes* is used
   for attributes of ``<link>`` tag.  It defaults to an empty list.

   Example::
@@ -1074,7 +1075,7 @@ that use Sphinx's HTMLWriter class.
   A list of JavaScript *filename*.  The entry must be a *filename* string or a
   tuple containing the *filename* string and the *attributes* dictionary.  The
   *filename* must be relative to the :confval:`html_static_path`, or a full
-   URI with scheme like ``http://example.org/script.js``.  The *attributes* is
+   URI with scheme like ``https://example.org/script.js``.  The *attributes* is
   used for attributes of ``<script>`` tag.  It defaults to an empty list.

   Example::
@@ -1308,7 +1309,7 @@ that use Sphinx's HTMLWriter class.

 .. confval:: html_use_opensearch

-   If nonempty, an `OpenSearch <http://www.opensearch.org/Home>`_ description
+   If nonempty, an `OpenSearch <https://www.opensearch.org/>`_ description
   file will be output, and all pages will contain a ``<link>`` tag referring
   to it.  Since OpenSearch doesn't support relative URLs for its search page
   location, the value of this option must be the base URL from which these
@@ -1735,7 +1736,7 @@ Options for epub output
 These options influence the epub output.  As this builder derives from the HTML
 builder, the HTML options also apply where appropriate.  The actual values for
 some of the options is not really important, they just have to be entered into
-the `Dublin Core metadata <http://dublincore.org/>`_.
+the `Dublin Core metadata <https://dublincore.org/>`_.

 .. confval:: epub_basename

@@ -2357,6 +2358,10 @@ These options influence manual page output.

      The default is changed to ``False`` from ``True``.

+   .. versionchanged:: 4.0.2
+
+      The default is changed to ``True`` from ``False`` again.
+
 .. _texinfo-options:

 Options for Texinfo output
@@ -2592,7 +2597,7 @@ Options for the linkcheck builder
      as follows::

         linkcheck_ignore = [
-            'http://www.sphinx-doc.org/en/1.7/intro.html#'
+            'https://www.sphinx-doc.org/en/1.7/intro.html#'
         ]

   .. versionadded:: 1.5
@@ -2684,6 +2689,14 @@ Options for the C domain

   .. versionadded:: 3.0

+.. confval:: c_extra_keywords
+
+  A list of identifiers to be recognized as keywords by the C parser.
+  It defaults to ``['alignas', 'alignof', 'bool', 'complex', 'imaginary',
+  'noreturn', 'static_assert', 'thread_local']``.
+
+  .. versionadded:: 4.0.3
+
 .. confval:: c_allow_pre_v3

   A boolean (default ``False``) controlling whether to parse and try to
--- a/doc/usage/extensions/autodoc.rst
+++ b/doc/usage/extensions/autodoc.rst
@@ -463,6 +463,20 @@ There are also config values that you can set:

   .. versionadded:: 1.4

+.. confval:: autodoc_class_signature
+
+   This value selects how the signautre will be displayed for the class defined
+   by :rst:dir:`autoclass` directive.  The possible values are:
+
+   ``"mixed"``
+      Display the signature with the class name.
+   ``"separated"``
+      Display the signature as a method.
+
+   The default is ``"mixed"``.
+
+   .. versionadded:: 4.1
+
 .. confval:: autodoc_member_order

   This value selects if automatically documented members are sorted
@@ -749,6 +763,21 @@ needed docstring processing in event :event:`autodoc-process-docstring`:
 .. autofunction:: cut_lines
 .. autofunction:: between

+.. event:: autodoc-process-bases (app, name, obj, options, bases)
+
+   .. versionadded:: 4.1
+
+   Emitted when autodoc has read and processed a class to determine the
+   base-classes.  *bases* is a list of classes that the event handler can
+   modify **in place** to change what Sphinx puts into the output.  It's
+   emitted only if ``show-inheritance`` option given.
+
+   :param app: the Sphinx application object
+   :param name: the fully qualified name of the object
+   :param obj: the object itself
+   :param options: the options given to the class directive
+   :param bases: the list of base classes signature. see above.
+

 Skipping members
 ----------------
--- a/doc/usage/extensions/autosummary.rst
+++ b/doc/usage/extensions/autosummary.rst
@@ -335,4 +335,4 @@ the title of a page.
   You can use the :rst:dir:`autosummary` directive in the stub pages.
   Stub pages are generated also based on these directives.

-.. _`escape filter`: http://jinja.pocoo.org/docs/2.9/templates/#escape
+.. _`escape filter`: https://jinja.palletsprojects.com/en/3.0.x/templates/#jinja-filters.escape
--- a/doc/usage/extensions/graphviz.rst
+++ b/doc/usage/extensions/graphviz.rst
@@ -230,7 +230,7 @@ There are also these config values:
       .. graphviz::

            digraph example {
-                a [label="sphinx", href="http://sphinx-doc.org", target="_top"];
+                a [label="sphinx", href="https://sphinx-doc.org", target="_top"];
                b [label="other"];
                a -> b;
            }
--- a/doc/usage/extensions/math.rst
+++ b/doc/usage/extensions/math.rst
@@ -220,7 +220,7 @@ Sphinx but is set to automatically include it from a third-party site.
   The value is used as a parameter of ``MathJax.Hub.Config()``.
   For more information, please read `Using in-line configuration options`__.

-   __ http://docs.mathjax.org/en/v2.7-latest/
+   __ https://docs.mathjax.org/en/v2.7-latest/
      configuration.html#using-in-line-configuration-options

   For example::
--- a/doc/usage/extensions/napoleon.rst
+++ b/doc/usage/extensions/napoleon.rst
@@ -49,7 +49,7 @@ parse them. This happens in an intermediate step while Sphinx is processing
 the documentation, so it doesn't modify any of the docstrings in your actual
 source code files.

-.. _ReStructuredText: http://docutils.sourceforge.net/rst.html
+.. _ReStructuredText: https://docutils.sourceforge.io/rst.html
 .. _docstrings: https://www.python.org/dev/peps/pep-0287/
 .. _Google Python Style Guide:
   https://google.github.io/styleguide/pyguide.html
@@ -267,14 +267,9 @@ Google style with types in docstrings::
   `Python 2/3 compatible annotations`_ aren't currently
   supported by Sphinx and won't show up in the docs.

-.. _PEP 484:
-   https://www.python.org/dev/peps/pep-0484/
-
-.. _PEP 526:
-    https://www.python.org/dev/peps/pep-0526/
-
-.. _Python 2/3 compatible annotations:
-   https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
+.. _PEP 484: https://www.python.org/dev/peps/pep-0484/
+.. _PEP 526: https://www.python.org/dev/peps/pep-0526/
+.. _Python 2/3 compatible annotations: https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code


 Configuration
@@ -330,9 +325,9 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
   **If True**::

       def __init__(self):
-           \"\"\"
+           """
           This will be included in the docs because it has a docstring
-           \"\"\"
+           """

       def __init__(self):
           # This will NOT be included in the docs
@@ -514,7 +509,7 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
 .. confval:: napoleon_preprocess_types

   True to convert the type definitions in the docstrings as references.
-   Defaults to *True*.
+   Defaults to *False*.

   .. versionadded:: 3.2.1
   .. versionchanged:: 3.5
--- a/doc/usage/installation.rst
+++ b/doc/usage/installation.rst
@@ -185,30 +185,67 @@ the ``--pre`` flag.

   $ pip install -U --pre sphinx

+Using virtual environments
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When installing Sphinx using pip,
+it is highly recommended to use *virtual environments*,
+which isolate the installed packages from the system packages,
+thus removing the need to use administrator privileges.
+To create a virtual environment in the ``.venv`` directory,
+use the following command.
+
+::
+
+   $ python -m venv .venv
+
+You can read more about them in the `Python Packaging User Guide`_.
+
+.. _Python Packaging User Guide: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment
+
+.. warning::
+
+   Note that in some Linux distributions, such as Debian and Ubuntu,
+   this might require an extra installation step as follows.
+
+    .. code-block:: console
+
+       $ apt-get install python3-venv

 Docker
 ------

-Docker images for Sphinx are published on the `Docker Hub <https://hub.docker.com/>`_. There are two kind of images:
+Docker images for Sphinx are published on the `Docker Hub`_.  There are two kind
+of images:

- `sphinxdoc/sphinx <https://hub.docker.com/repository/docker/sphinxdoc/sphinx>`_
- `sphinxdoc/sphinx-latexpdf <https://hub.docker.com/repository/docker/sphinxdoc/sphinx-latexpdf>`_
+- `sphinxdoc/sphinx`_
+- `sphinxdoc/sphinx-latexpdf`_

-Former one is used for standard usage of Sphinx, and latter one is mainly used for PDF builds using LaTeX.
-Please choose one for your purpose.
+.. _Docker Hub: https://hub.docker.com/
+.. _sphinxdoc/sphinx: https://hub.docker.com/repository/docker/sphinxdoc/sphinx
+.. _sphinxdoc/sphinx-latexpdf: https://hub.docker.com/repository/docker/sphinxdoc/sphinx-latexpdf>
+
+Former one is used for standard usage of Sphinx, and latter one is mainly used for
+PDF builds using LaTeX.  Please choose one for your purpose.

 .. note::

-   sphinxdoc/sphinx-latexpdf contains TeXLive packages. So the image is very large (over 2GB!).
+   sphinxdoc/sphinx-latexpdf contains TeXLive packages. So the image is very large
+   (over 2GB!).

 .. hint::

-   When using docker images, please use ``docker run`` command to invoke sphinx commands.  For example,
-   you can use following command to create a Sphinx project::
+   When using docker images, please use ``docker run`` command to invoke sphinx
+   commands.  For example, you can use following command to create a Sphinx
+   project:
+
+   .. code-block:: bash

      $ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart

-   And you can following command this to build HTML document::
+   And you can following command this to build HTML document:
+
+   .. code-block:: bash

      $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx make html

--- a/doc/usage/quickstart.rst
+++ b/doc/usage/quickstart.rst
@@ -24,7 +24,7 @@ default markup format used by Sphinx, :doc:`reStucturedText
 For a great "introduction" to writing docs in general -- the whys and hows, see
 also `Write the docs`__, written by Eric Holscher.

-.. __: http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
+.. __: https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/


 Setting up the documentation sources
--- a/doc/usage/restructuredtext/basics.rst
+++ b/doc/usage/restructuredtext/basics.rst
@@ -15,7 +15,7 @@ language, this will not take too long.
 .. seealso::

   The authoritative `reStructuredText User Documentation
-   <http://docutils.sourceforge.net/rst.html>`_.  The "ref" links in this
+   <https://docutils.sourceforge.io/rst.html>`_.  The "ref" links in this
   document link to the description of the individual constructs in the reST
   reference.

--- a/doc/usage/restructuredtext/directives.rst
+++ b/doc/usage/restructuredtext/directives.rst
@@ -424,7 +424,7 @@ code blocks using multiple varied syntaxes. Finally, the
 in your documentation.

 In all cases, Syntax highlighting is provided by `Pygments
-<http://pygments.org>`_. When using literal blocks, this is configured using
+<https://pygments.org>`_. When using literal blocks, this is configured using
 any :rst:dir:`highlight` directives in the source file. When a ``highlight``
 directive is encountered, it is used until the next ``highlight`` directive is
 encountered. If there is no ``highlight`` directive in the file, the global
@@ -452,7 +452,7 @@ If highlighting with the selected language fails (i.e. Pygments emits an
   want to ensure consistent highlighting, you should fix your version of
   Pygments.

-__ http://pygments.org/docs/lexers
+__ https://pygments.org/docs/lexers

 .. rst:directive:: .. highlight:: language

--- a/doc/usage/restructuredtext/index.rst
+++ b/doc/usage/restructuredtext/index.rst
@@ -12,7 +12,7 @@ The below guides go through the most important aspects of reST. For the
 authoritative reStructuredText reference, refer to the `docutils
 documentation`__.

-__ http://docutils.sourceforge.net/rst.html
+__ https://docutils.sourceforge.io/rst.html

 .. toctree::
   :maxdepth: 2
--- a/doc/usage/theming.rst
+++ b/doc/usage/theming.rst
@@ -248,7 +248,8 @@ These themes are:

 **scrolls**
  A more lightweight theme, based on `the Jinja documentation
-  <http://jinja.pocoo.org/>`_.  The following color options are available:
+  <https://jinja.palletsprojects.com/>`_.  The following color options are
+  available:

  - **headerbordercolor**
  - **subheadlinecolor**
--- a/package-lock.json
+++ b/package-lock.json
@@ -486,9 +486,9 @@
      }
    },
    "glob-parent": {
-      "version": "5.0.0",
-      "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.0.0.tgz",
-      "integrity": "sha512-Z2RwiujPRGluePM6j699ktJYxmPpJKCfpGA13jz2hmFZC7gKetzrWvg5KN3+OsIFmydGyZ1AVwERCq1w/ZZwRg==",
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz",
+      "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==",
      "dev": true,
      "requires": {
        "is-glob": "^4.0.1"
--- a/setup.py
+++ b/setup.py
@@ -44,8 +44,11 @@ extras_require = {
    'lint': [
        'flake8>=3.5.0',
        'isort',
-        'mypy>=0.800',
+        'mypy>=0.900',
        'docutils-stubs',
+        "types-typed-ast",
+        "types-pkg_resources",
+        "types-requests",
    ],
    'test': [
        'pytest',
@@ -173,7 +176,7 @@ else:
 setup(
    name='Sphinx',
    version=sphinx.__version__,
-    url='http://sphinx-doc.org/',
+    url='https://sphinx-doc.org/',
    download_url='https://pypi.org/project/Sphinx/',
    license='BSD',
    author='Georg Brandl',
--- a/sphinx/application.py
+++ b/sphinx/application.py
@@ -152,12 +152,6 @@ class Sphinx:
        self.srcdir = abspath(srcdir)
        self.outdir = abspath(outdir)
        self.doctreedir = abspath(doctreedir)
-        self.confdir = confdir
-        if self.confdir:  # confdir is optional
-            self.confdir = abspath(self.confdir)
-            if not path.isfile(path.join(self.confdir, 'conf.py')):
-                raise ApplicationError(__("config directory doesn't contain a "
-                                          "conf.py file (%s)") % confdir)

        if not path.isdir(self.srcdir):
            raise ApplicationError(__('Cannot find source directory (%s)') %
@@ -212,9 +206,13 @@ class Sphinx:

        # read config
        self.tags = Tags(tags)
-        if self.confdir is None:
+        if confdir is None:
+            # set confdir to srcdir if -C given (!= no confdir); a few pieces
+            # of code expect a confdir to be set
+            self.confdir = self.srcdir
            self.config = Config({}, confoverrides or {})
        else:
+            self.confdir = abspath(confdir)
            self.config = Config.read(self.confdir, confoverrides or {}, self.tags)

        # initialize some limited config variables before initialize i18n and loading
@@ -230,11 +228,6 @@ class Sphinx:
                __('This project needs at least Sphinx v%s and therefore cannot '
                   'be built with this version.') % self.config.needs_sphinx)

-        # set confdir to srcdir if -C given (!= no confdir); a few pieces
-        # of code expect a confdir to be set
-        if self.confdir is None:
-            self.confdir = self.srcdir
-
        # load all built-in extension modules
        for extension in builtin_extensions:
            self.setup_extension(extension)
@@ -307,8 +300,7 @@ class Sphinx:
    def _init_env(self, freshenv: bool) -> None:
        filename = path.join(self.doctreedir, ENV_PICKLE_FILENAME)
        if freshenv or not os.path.exists(filename):
-            self.env = BuildEnvironment()
-            self.env.setup(self)
+            self.env = BuildEnvironment(self)
            self.env.find_files(self.config, self.builder)
        else:
            try:
@@ -663,10 +655,10 @@ class Sphinx:
                   ...

           def setup(app):
-               add_directive('my-directive', MyDirective)
+               app.add_directive('my-directive', MyDirective)

        For more details, see `the Docutils docs
-        <http://docutils.sourceforge.net/docs/howto/rst-directives.html>`__ .
+        <https://docutils.sourceforge.io/docs/howto/rst-directives.html>`__ .

        .. versionchanged:: 0.6
           Docutils 0.5-style directive classes are now supported.
@@ -691,7 +683,7 @@ class Sphinx:
                         installed as the same name

        For more details about role functions, see `the Docutils docs
-        <http://docutils.sourceforge.net/docs/howto/rst-roles.html>`__ .
+        <https://docutils.sourceforge.io/docs/howto/rst-roles.html>`__ .

        .. versionchanged:: 1.8
           Add *override* keyword.
@@ -929,7 +921,7 @@ class Sphinx:

        refs: `Transform Priority Range Categories`__

-        __ http://docutils.sourceforge.net/docs/ref/transforms.html#transform-priority-range-categories
+        __ https://docutils.sourceforge.io/docs/ref/transforms.html#transform-priority-range-categories
        """  # NOQA
        self.registry.add_transform(transform)

@@ -1258,6 +1250,18 @@ class Sphinx:

        return True

+    def set_html_assets_policy(self, policy):
+        """Set the policy to include assets in HTML pages.
+
+        - always: include the assets in all the pages
+        - per_page: include the assets only in pages where they are used
+
+        .. versionadded: 4.1
+        """
+        if policy not in ('always', 'per_page'):
+            raise ValueError('policy %s is not supported' % policy)
+        self.registry.html_assets_policy = policy
+
    @property
    def html_themes(self) -> Dict[str, str]:
        warnings.warn('app.html_themes is deprecated.',
--- a/sphinx/builders/dirhtml.py
+++ b/sphinx/builders/dirhtml.py
@@ -13,7 +13,6 @@ from typing import Any, Dict

 from sphinx.application import Sphinx
 from sphinx.builders.html import StandaloneHTMLBuilder
-from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias
 from sphinx.util import logging
 from sphinx.util.osutil import SEP, os_path

@@ -46,17 +45,6 @@ class DirectoryHTMLBuilder(StandaloneHTMLBuilder):
        return outfilename


-# for compatibility
-deprecated_alias('sphinx.builders.html',
-                 {
-                     'DirectoryHTMLBuilder':  DirectoryHTMLBuilder,
-                 },
-                 RemovedInSphinx40Warning,
-                 {
-                     'DirectoryHTMLBuilder': 'sphinx.builders.dirhtml.DirectoryHTMLBuilder',
-                 })
-
-
 def setup(app: Sphinx) -> Dict[str, Any]:
    app.setup_extension('sphinx.builders.html')

--- a/sphinx/builders/html/init.py
+++ b/sphinx/builders/html/init.py
@@ -468,9 +468,6 @@ class StandaloneHTMLBuilder(Builder):
        else:
            self.last_updated = None

-        logo = path.basename(self.config.html_logo) if self.config.html_logo else ''
-        favicon = path.basename(self.config.html_favicon) if self.config.html_favicon else ''
-
        self.relations = self.env.collect_relations()

        rellinks: List[Tuple[str, str, str, str]] = []
@@ -513,8 +510,8 @@ class StandaloneHTMLBuilder(Builder):
            'rellinks': rellinks,
            'builder': self.name,
            'parents': [],
-            'logo': logo,
-            'favicon': favicon,
+            'logo': self.config.html_logo or '',
+            'favicon': self.config.html_favicon or '',
            'html5_doctype': html5_ready and not self.config.html4_writer,
        }
        if self.theme:
--- a/sphinx/builders/linkcheck.py
+++ b/sphinx/builders/linkcheck.py
@@ -21,12 +21,12 @@ from queue import PriorityQueue, Queue
 from threading import Thread
 from typing import (Any, Dict, Generator, List, NamedTuple, Optional, Pattern, Set, Tuple,
                    Union, cast)
-from urllib.parse import unquote, urlparse
+from urllib.parse import unquote, urlparse, urlunparse

 from docutils import nodes
 from docutils.nodes import Element
 from requests import Response
-from requests.exceptions import HTTPError, TooManyRedirects
+from requests.exceptions import ConnectionError, HTTPError, TooManyRedirects

 from sphinx.application import Sphinx
 from sphinx.builders.dummy import DummyBuilder
@@ -456,7 +456,9 @@ class HyperlinkAvailabilityCheckWorker(Thread):
                                                 config=self.config, auth=auth_info,
                                                 **kwargs)
                        response.raise_for_status()
-                    except (HTTPError, TooManyRedirects) as err:
+                    # Servers drop the connection on HEAD requests, causing
+                    # ConnectionError.
+                    except (ConnectionError, HTTPError, TooManyRedirects) as err:
                        if isinstance(err, HTTPError) and err.response.status_code == 429:
                            raise
                        # retry with GET request if that fails, some servers
@@ -627,6 +629,10 @@ class HyperlinkCollector(SphinxPostTransform):
            if 'refuri' not in refnode:
                continue
            uri = refnode['refuri']
+            newuri = self.app.emit_firstresult('linkcheck-process-uri', uri)
+            if newuri:
+                uri = newuri
+
            lineno = get_node_line(refnode)
            uri_info = Hyperlink(uri, self.env.docname, lineno)
            if uri not in hyperlinks:
@@ -636,12 +642,31 @@ class HyperlinkCollector(SphinxPostTransform):
        for imgnode in self.document.traverse(nodes.image):
            uri = imgnode['candidates'].get('?')
            if uri and '://' in uri:
+                newuri = self.app.emit_firstresult('linkcheck-process-uri', uri)
+                if newuri:
+                    uri = newuri
+
                lineno = get_node_line(imgnode)
                uri_info = Hyperlink(uri, self.env.docname, lineno)
                if uri not in hyperlinks:
                    hyperlinks[uri] = uri_info


+def rewrite_github_anchor(app: Sphinx, uri: str) -> Optional[str]:
+    """Rewrite anchor name of the hyperlink to github.com
+
+    The hyperlink anchors in github.com are dynamically generated.  This rewrites
+    them before checking and makes them comparable.
+    """
+    parsed = urlparse(uri)
+    if parsed.hostname == "github.com" and parsed.fragment:
+        prefixed = parsed.fragment.startswith('user-content-')
+        if not prefixed:
+            fragment = f'user-content-{parsed.fragment}'
+            return urlunparse(parsed._replace(fragment=fragment))
+    return None
+
+
 def setup(app: Sphinx) -> Dict[str, Any]:
    app.add_builder(CheckExternalLinksBuilder)
    app.add_post_transform(HyperlinkCollector)
@@ -658,6 +683,9 @@ def setup(app: Sphinx) -> Dict[str, Any]:
    app.add_config_value('linkcheck_anchors_ignore', ["^!"], None)
    app.add_config_value('linkcheck_rate_limit_timeout', 300.0, None)

+    app.add_event('linkcheck-process-uri')
+    app.connect('linkcheck-process-uri', rewrite_github_anchor)
+
    return {
        'version': 'builtin',
        'parallel_read_safe': True,
--- a/sphinx/builders/manpage.py
+++ b/sphinx/builders/manpage.py
@@ -79,8 +79,9 @@ class ManualPageBuilder(Builder):
            docsettings.section = section

            if self.config.man_make_section_directory:
-                ensuredir(path.join(self.outdir, str(section)))
-                targetname = '%s/%s.%s' % (section, name, section)
+                dirname = 'man%s' % section
+                ensuredir(path.join(self.outdir, dirname))
+                targetname = '%s/%s.%s' % (dirname, name, section)
            else:
                targetname = '%s.%s' % (name, section)

@@ -118,7 +119,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:

    app.add_config_value('man_pages', default_man_pages, None)
    app.add_config_value('man_show_urls', False, None)
-    app.add_config_value('man_make_section_directory', True, None)
+    app.add_config_value('man_make_section_directory', False, None)

    return {
        'version': 'builtin',
--- a/sphinx/builders/singlehtml.py
+++ b/sphinx/builders/singlehtml.py
@@ -16,7 +16,6 @@ from docutils.nodes import Node

 from sphinx.application import Sphinx
 from sphinx.builders.html import StandaloneHTMLBuilder
-from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias
 from sphinx.environment.adapters.toctree import TocTree
 from sphinx.locale import __
 from sphinx.util import logging, progress_message
@@ -187,18 +186,6 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
            self.handle_page('opensearch', {}, 'opensearch.xml', outfilename=fn)


-# for compatibility
-deprecated_alias('sphinx.builders.html',
-                 {
-                     'SingleFileHTMLBuilder': SingleFileHTMLBuilder,
-                 },
-                 RemovedInSphinx40Warning,
-                 {
-                     'SingleFileHTMLBuilder':
-                     'sphinx.builders.singlehtml.SingleFileHTMLBuilder',
-                 })
-
-
 def setup(app: Sphinx) -> Dict[str, Any]:
    app.setup_extension('sphinx.builders.html')

--- a/sphinx/config.py
+++ b/sphinx/config.py
@@ -166,6 +166,9 @@ class Config:
    def read(cls, confdir: str, overrides: Dict = None, tags: Tags = None) -> "Config":
        """Create a Config object from configuration file."""
        filename = path.join(confdir, CONFIG_FILENAME)
+        if not path.isfile(filename):
+            raise ConfigError(__("config directory doesn't contain a conf.py file (%s)") %
+                              confdir)
        namespace = eval_config_file(filename, tags)
        return cls(namespace, overrides or {})

--- a/sphinx/deprecation.py
+++ b/sphinx/deprecation.py
@@ -14,10 +14,6 @@ from importlib import import_module
 from typing import Any, Dict, Type


-class RemovedInSphinx40Warning(DeprecationWarning):
-    pass
-
-
 class RemovedInSphinx50Warning(DeprecationWarning):
    pass

--- a/sphinx/domains/c.py
+++ b/sphinx/domains/c.py
@@ -55,10 +55,15 @@ _keywords = [
    'else', 'enum', 'extern', 'float', 'for', 'goto', 'if', 'inline', 'int', 'long',
    'register', 'restrict', 'return', 'short', 'signed', 'sizeof', 'static', 'struct',
    'switch', 'typedef', 'union', 'unsigned', 'void', 'volatile', 'while',
-    '_Alignas', 'alignas', '_Alignof', 'alignof', '_Atomic', '_Bool', 'bool',
-    '_Complex', 'complex', '_Generic', '_Imaginary', 'imaginary',
-    '_Noreturn', 'noreturn', '_Static_assert', 'static_assert',
-    '_Thread_local', 'thread_local',
+    '_Alignas', '_Alignof', '_Atomic', '_Bool', '_Complex',
+    '_Decimal32', '_Decimal64', '_Decimal128',
+    '_Generic', '_Imaginary', '_Noreturn', '_Static_assert', '_Thread_local',
+]
+# These are only keyword'y when the corresponding headers are included.
+# They are used as default value for c_extra_keywords.
+_macroKeywords = [
+    'alignas', 'alignof', 'bool', 'complex', 'imaginary', 'noreturn', 'static_assert',
+    'thread_local',
 ]

 # these are ordered by preceedence
@@ -2536,6 +2541,12 @@ class DefinitionParser(BaseParser):
            if identifier in _keywords:
                self.fail("Expected identifier in nested name, "
                          "got keyword: %s" % identifier)
+            if self.matched_text in self.config.c_extra_keywords:
+                msg = "Expected identifier, got user-defined keyword: %s." \
+                      + " Remove it from c_extra_keywords to allow it as identifier.\n" \
+                      + "Currently c_extra_keywords is %s."
+                self.fail(msg % (self.matched_text,
+                                 str(self.config.c_extra_keywords)))
            ident = ASTIdentifier(identifier)
            names.append(ident)

@@ -2712,6 +2723,12 @@ class DefinitionParser(BaseParser):
                if self.matched_text in _keywords:
                    self.fail("Expected identifier, "
                              "got keyword: %s" % self.matched_text)
+                if self.matched_text in self.config.c_extra_keywords:
+                    msg = "Expected identifier, got user-defined keyword: %s." \
+                          + " Remove it from c_extra_keywords to allow it as identifier.\n" \
+                          + "Currently c_extra_keywords is %s."
+                    self.fail(msg % (self.matched_text,
+                                     str(self.config.c_extra_keywords)))
                identifier = ASTIdentifier(self.matched_text)
                declId = ASTNestedName([identifier], rooted=False)
            else:
@@ -3115,7 +3132,7 @@ class CObject(ObjectDescription[ASTDeclaration]):
    doc_field_types = [
        TypedField('parameter', label=_('Parameters'),
                   names=('param', 'parameter', 'arg', 'argument'),
-                   typerolename='type', typenames=('type',)),
+                   typerolename='expr', typenames=('type',)),
        Field('returnvalue', label=_('Returns'), has_arg=False,
              names=('returns', 'return')),
        Field('returntype', label=_('Return type'), has_arg=False,
@@ -3878,6 +3895,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
    app.add_domain(CDomain)
    app.add_config_value("c_id_attributes", [], 'env')
    app.add_config_value("c_paren_attributes", [], 'env')
+    app.add_config_value("c_extra_keywords", _macroKeywords, 'env')
    app.add_post_transform(AliasTransform)

    app.add_config_value("c_allow_pre_v3", False, 'env')
--- a/sphinx/domains/changeset.py
+++ b/sphinx/domains/changeset.py
@@ -74,8 +74,10 @@ class VersionChange(SphinxDirective):
        if self.content:
            self.state.nested_parse(self.content, self.content_offset, node)
        classes = ['versionmodified', versionlabel_classes[self.name]]
-        if len(node):
-            if isinstance(node[0], nodes.paragraph) and node[0].rawsource:
+        if len(node) > 0 and isinstance(node[0], nodes.paragraph):
+            # the contents start with a paragraph
+            if node[0].rawsource:
+                # make the first paragraph translatable
                content = nodes.inline(node[0].rawsource, translatable=True)
                content.source = node[0].source
                content.line = node[0].line
@@ -84,10 +86,16 @@ class VersionChange(SphinxDirective):

            para = cast(nodes.paragraph, node[0])
            para.insert(0, nodes.inline('', '%s: ' % text, classes=classes))
-        else:
+        elif len(node) > 0:
+            # the contents do not starts with a paragraph
            para = nodes.paragraph('', '',
-                                   nodes.inline('', '%s.' % text,
-                                                classes=classes),
+                                   nodes.inline('', '%s: ' % text, classes=classes),
+                                   translatable=False)
+            node.insert(0, para)
+        else:
+            # the contents are empty
+            para = nodes.paragraph('', '',
+                                   nodes.inline('', '%s.' % text, classes=classes),
                                   translatable=False)
            node.append(para)

--- a/sphinx/domains/cpp.py
+++ b/sphinx/domains/cpp.py
@@ -319,8 +319,9 @@ _fold_operator_re = re.compile(r'''(?x)
 # see https://en.cppreference.com/w/cpp/keyword
 _keywords = [
    'alignas', 'alignof', 'and', 'and_eq', 'asm', 'auto', 'bitand', 'bitor',
-    'bool', 'break', 'case', 'catch', 'char', 'char16_t', 'char32_t', 'class',
-    'compl', 'concept', 'const', 'constexpr', 'const_cast', 'continue',
+    'bool', 'break', 'case', 'catch', 'char', 'char8_t', 'char16_t', 'char32_t',
+    'class', 'compl', 'concept', 'const', 'consteval', 'constexpr', 'constinit',
+    'const_cast', 'continue',
    'decltype', 'default', 'delete', 'do', 'double', 'dynamic_cast', 'else',
    'enum', 'explicit', 'export', 'extern', 'false', 'float', 'for', 'friend',
    'goto', 'if', 'inline', 'int', 'long', 'mutable', 'namespace', 'new',
@@ -426,6 +427,7 @@ _id_fundamental_v2 = {
    'wchar_t': 'w',
    'char32_t': 'Di',
    'char16_t': 'Ds',
+    'char8_t': 'Du',
    'short': 's',
    'short int': 's',
    'signed short': 's',
@@ -867,7 +869,7 @@ class ASTNumberLiteral(ASTLiteral):

    def get_id(self, version: int) -> str:
        # TODO: floats should be mangled by writing the hex of the binary representation
-        return "L%sE" % self.data
+        return "L%sE" % self.data.replace("'", "")

    def describe_signature(self, signode: TextElement, mode: str,
                           env: "BuildEnvironment", symbol: "Symbol") -> None:
@@ -1880,9 +1882,11 @@ class ASTTrailingTypeSpecDecltype(ASTTrailingTypeSpec):


 class ASTTrailingTypeSpecName(ASTTrailingTypeSpec):
-    def __init__(self, prefix: str, nestedName: ASTNestedName) -> None:
+    def __init__(self, prefix: str, nestedName: ASTNestedName,
+                 placeholderType: Optional[str]) -> None:
        self.prefix = prefix
        self.nestedName = nestedName
+        self.placeholderType = placeholderType

    @property
    def name(self) -> ASTNestedName:
@@ -1897,6 +1901,9 @@ class ASTTrailingTypeSpecName(ASTTrailingTypeSpec):
            res.append(self.prefix)
            res.append(' ')
        res.append(transform(self.nestedName))
+        if self.placeholderType is not None:
+            res.append(' ')
+            res.append(self.placeholderType)
        return ''.join(res)

    def describe_signature(self, signode: TextElement, mode: str,
@@ -1905,6 +1912,17 @@ class ASTTrailingTypeSpecName(ASTTrailingTypeSpec):
            signode += addnodes.desc_sig_keyword(self.prefix, self.prefix)
            signode += addnodes.desc_sig_space()
        self.nestedName.describe_signature(signode, mode, env, symbol=symbol)
+        if self.placeholderType is not None:
+            signode += addnodes.desc_sig_space()
+            if self.placeholderType == 'auto':
+                signode += addnodes.desc_sig_keyword('auto', 'auto')
+            elif self.placeholderType == 'decltype(auto)':
+                signode += addnodes.desc_sig_keyword('decltype', 'decltype')
+                signode += addnodes.desc_sig_punctuation('(', '(')
+                signode += addnodes.desc_sig_keyword('auto', 'auto')
+                signode += addnodes.desc_sig_punctuation(')', ')')
+            else:
+                assert False, self.placeholderType


 class ASTFunctionParameter(ASTBase):
@@ -2099,16 +2117,41 @@ class ASTParametersQualifiers(ASTBase):
                signode += addnodes.desc_sig_keyword(self.initializer, self.initializer)


+class ASTExplicitSpec(ASTBase):
+    def __init__(self, expr: Optional[ASTExpression]) -> None:
+        self.expr = expr
+
+    def _stringify(self, transform: StringifyTransform) -> str:
+        res = ['explicit']
+        if self.expr is not None:
+            res.append('(')
+            res.append(transform(self.expr))
+            res.append(')')
+        return ''.join(res)
+
+    def describe_signature(self, signode: TextElement,
+                           env: "BuildEnvironment", symbol: "Symbol") -> None:
+        signode += addnodes.desc_sig_keyword('explicit', 'explicit')
+        if self.expr is not None:
+            signode += addnodes.desc_sig_punctuation('(', '(')
+            self.expr.describe_signature(signode, 'markType', env, symbol)
+            signode += addnodes.desc_sig_punctuation(')', ')')
+
+
 class ASTDeclSpecsSimple(ASTBase):
    def __init__(self, storage: str, threadLocal: bool, inline: bool, virtual: bool,
-                 explicit: bool, constexpr: bool, volatile: bool, const: bool,
-                 friend: bool, attrs: List[ASTAttribute]) -> None:
+                 explicitSpec: Optional[ASTExplicitSpec],
+                 consteval: bool, constexpr: bool, constinit: bool,
+                 volatile: bool, const: bool, friend: bool,
+                 attrs: List[ASTAttribute]) -> None:
        self.storage = storage
        self.threadLocal = threadLocal
        self.inline = inline
        self.virtual = virtual
-        self.explicit = explicit
+        self.explicitSpec = explicitSpec
+        self.consteval = consteval
        self.constexpr = constexpr
+        self.constinit = constinit
        self.volatile = volatile
        self.const = const
        self.friend = friend
@@ -2121,8 +2164,10 @@ class ASTDeclSpecsSimple(ASTBase):
                                  self.threadLocal or other.threadLocal,
                                  self.inline or other.inline,
                                  self.virtual or other.virtual,
-                                  self.explicit or other.explicit,
+                                  self.explicitSpec or other.explicitSpec,
+                                  self.consteval or other.consteval,
                                  self.constexpr or other.constexpr,
+                                  self.constinit or other.constinit,
                                  self.volatile or other.volatile,
                                  self.const or other.const,
                                  self.friend or other.friend,
@@ -2141,17 +2186,22 @@ class ASTDeclSpecsSimple(ASTBase):
            res.append('friend')
        if self.virtual:
            res.append('virtual')
-        if self.explicit:
-            res.append('explicit')
+        if self.explicitSpec:
+            res.append(transform(self.explicitSpec))
+        if self.consteval:
+            res.append('consteval')
        if self.constexpr:
            res.append('constexpr')
+        if self.constinit:
+            res.append('constinit')
        if self.volatile:
            res.append('volatile')
        if self.const:
            res.append('const')
        return ' '.join(res)

-    def describe_signature(self, signode: TextElement) -> None:
+    def describe_signature(self, signode: TextElement,
+                           env: "BuildEnvironment", symbol: "Symbol") -> None:
        addSpace = False
        for attr in self.attrs:
            if addSpace:
@@ -2175,10 +2225,17 @@ class ASTDeclSpecsSimple(ASTBase):
            addSpace = _add(signode, 'friend')
        if self.virtual:
            addSpace = _add(signode, 'virtual')
-        if self.explicit:
-            addSpace = _add(signode, 'explicit')
+        if self.explicitSpec:
+            if addSpace:
+                signode += addnodes.desc_sig_space()
+            self.explicitSpec.describe_signature(signode, env, symbol)
+            addSpace = True
+        if self.consteval:
+            addSpace = _add(signode, 'consteval')
        if self.constexpr:
            addSpace = _add(signode, 'constexpr')
+        if self.constinit:
+            addSpace = _add(signode, 'constinit')
        if self.volatile:
            addSpace = _add(signode, 'volatile')
        if self.const:
@@ -2235,7 +2292,7 @@ class ASTDeclSpecs(ASTBase):
                           env: "BuildEnvironment", symbol: "Symbol") -> None:
        verify_description_mode(mode)
        numChildren = len(signode)
-        self.leftSpecs.describe_signature(signode)
+        self.leftSpecs.describe_signature(signode, env, symbol)
        addSpace = len(signode) != numChildren

        if self.trailingTypeSpec:
@@ -2249,7 +2306,7 @@ class ASTDeclSpecs(ASTBase):
            if len(str(self.rightSpecs)) > 0:
                if addSpace:
                    signode += addnodes.desc_sig_space()
-                self.rightSpecs.describe_signature(signode)
+                self.rightSpecs.describe_signature(signode, env, symbol)


 # Declarator
@@ -4942,8 +4999,8 @@ class DefinitionParser(BaseParser):
    # those without signedness and size modifiers
    # see https://en.cppreference.com/w/cpp/language/types
    _simple_fundemental_types = (
-        'void', 'bool', 'char', 'wchar_t', 'char16_t', 'char32_t', 'int',
-        'float', 'double', 'auto'
+        'void', 'bool', 'char', 'wchar_t', 'char8_t', 'char16_t', 'char32_t',
+        'int', 'float', 'double', 'auto'
    )

    _prefix_keys = ('class', 'struct', 'enum', 'union', 'typename')
@@ -5815,7 +5872,19 @@ class DefinitionParser(BaseParser):
                prefix = k
                break
        nestedName = self._parse_nested_name()
-        return ASTTrailingTypeSpecName(prefix, nestedName)
+        self.skip_ws()
+        placeholderType = None
+        if self.skip_word('auto'):
+            placeholderType = 'auto'
+        elif self.skip_word_and_ws('decltype'):
+            if not self.skip_string_and_ws('('):
+                self.fail("Expected '(' after 'decltype' in placeholder type specifier.")
+            if not self.skip_word_and_ws('auto'):
+                self.fail("Expected 'auto' after 'decltype(' in placeholder type specifier.")
+            if not self.skip_string_and_ws(')'):
+                self.fail("Expected ')' after 'decltype(auto' in placeholder type specifier.")
+            placeholderType = 'decltype(auto)'
+        return ASTTrailingTypeSpecName(prefix, nestedName, placeholderType)

    def _parse_parameters_and_qualifiers(self, paramMode: str) -> ASTParametersQualifiers:
        if paramMode == 'new':
@@ -5929,14 +5998,24 @@ class DefinitionParser(BaseParser):
        threadLocal = None
        inline = None
        virtual = None
-        explicit = None
+        explicitSpec = None
+        consteval = None
        constexpr = None
+        constinit = None
        volatile = None
        const = None
        friend = None
        attrs = []
        while 1:  # accept any permutation of a subset of some decl-specs
            self.skip_ws()
+            if not const and typed:
+                const = self.skip_word('const')
+                if const:
+                    continue
+            if not volatile and typed:
+                volatile = self.skip_word('volatile')
+                if volatile:
+                    continue
            if not storage:
                if outer in ('member', 'function'):
                    if self.skip_word('static'):
@@ -5952,16 +6031,28 @@ class DefinitionParser(BaseParser):
                if self.skip_word('register'):
                    storage = 'register'
                    continue
-            if not threadLocal and outer == 'member':
-                threadLocal = self.skip_word('thread_local')
-                if threadLocal:
+            if not inline and outer in ('function', 'member'):
+                inline = self.skip_word('inline')
+                if inline:
+                    continue
+            if not constexpr and outer in ('member', 'function'):
+                constexpr = self.skip_word("constexpr")
+                if constexpr:
                    continue

+            if outer == 'member':
+                if not constinit:
+                    constinit = self.skip_word('constinit')
+                    if constinit:
+                        continue
+                if not threadLocal:
+                    threadLocal = self.skip_word('thread_local')
+                    if threadLocal:
+                        continue
            if outer == 'function':
-                # function-specifiers
-                if not inline:
-                    inline = self.skip_word('inline')
-                    if inline:
+                if not consteval:
+                    consteval = self.skip_word('consteval')
+                    if consteval:
                        continue
                if not friend:
                    friend = self.skip_word('friend')
@@ -5971,31 +6062,28 @@ class DefinitionParser(BaseParser):
                    virtual = self.skip_word('virtual')
                    if virtual:
                        continue
-                if not explicit:
-                    explicit = self.skip_word('explicit')
+                if not explicitSpec:
+                    explicit = self.skip_word_and_ws('explicit')
                    if explicit:
+                        expr: ASTExpression = None
+                        if self.skip_string('('):
+                            expr = self._parse_constant_expression(inTemplate=False)
+                            if not expr:
+                                self.fail("Expected constant expression after '('" +
+                                          " in explicit specifier.")
+                            self.skip_ws()
+                            if not self.skip_string(')'):
+                                self.fail("Expected ')' to end explicit specifier.")
+                        explicitSpec = ASTExplicitSpec(expr)
                        continue
-
-            if not constexpr and outer in ('member', 'function'):
-                constexpr = self.skip_word("constexpr")
-                if constexpr:
-                    continue
-            if not volatile and typed:
-                volatile = self.skip_word('volatile')
-                if volatile:
-                    continue
-            if not const and typed:
-                const = self.skip_word('const')
-                if const:
-                    continue
            attr = self._parse_attribute()
            if attr:
                attrs.append(attr)
                continue
            break
        return ASTDeclSpecsSimple(storage, threadLocal, inline, virtual,
-                                  explicit, constexpr, volatile, const,
-                                  friend, attrs)
+                                  explicitSpec, consteval, constexpr, constinit,
+                                  volatile, const, friend, attrs)

    def _parse_decl_specs(self, outer: str, typed: bool = True) -> ASTDeclSpecs:
        if outer:
@@ -6846,7 +6934,7 @@ class CPPObject(ObjectDescription[ASTDeclaration]):
        GroupedField('template parameter', label=_('Template Parameters'),
                     names=('tparam', 'template parameter'),
                     can_collapse=True),
-        GroupedField('exceptions', label=_('Throws'), rolename='cpp:class',
+        GroupedField('exceptions', label=_('Throws'), rolename='expr',
                     names=('throws', 'throw', 'exception'),
                     can_collapse=True),
        Field('returnvalue', label=_('Returns'), has_arg=False,
@@ -7807,7 +7895,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:

    return {
        'version': 'builtin',
-        'env_version': 3,
+        'env_version': 4,
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }
--- a/sphinx/domains/javascript.py
+++ b/sphinx/domains/javascript.py
@@ -215,7 +215,7 @@ class JSCallable(JSObject):
        TypedField('arguments', label=_('Arguments'),
                   names=('argument', 'arg', 'parameter', 'param'),
                   typerolename='func', typenames=('paramtype', 'type')),
-        GroupedField('errors', label=_('Throws'), rolename='err',
+        GroupedField('errors', label=_('Throws'), rolename='func',
                     names=('throws', ),
                     can_collapse=True),
        Field('returnvalue', label=_('Returns'), has_arg=False,
--- a/sphinx/domains/python.py
+++ b/sphinx/domains/python.py
@@ -20,6 +20,7 @@ from typing import Any, Dict, Iterable, Iterator, List, NamedTuple, Optional, Tu
 from docutils import nodes
 from docutils.nodes import Element, Node
 from docutils.parsers.rst import directives
+from docutils.parsers.rst.states import Inliner

 from sphinx import addnodes
 from sphinx.addnodes import desc_signature, pending_xref, pending_xref_condition
@@ -284,9 +285,13 @@ def _pseudo_parse_arglist(signode: desc_signature, arglist: str) -> None:
 class PyXrefMixin:
    def make_xref(self, rolename: str, domain: str, target: str,
                  innernode: Type[TextlikeNode] = nodes.emphasis,
-                  contnode: Node = None, env: BuildEnvironment = None) -> Node:
+                  contnode: Node = None, env: BuildEnvironment = None,
+                  inliner: Inliner = None, location: Node = None) -> Node:
+        # we use inliner=None to make sure we get the old behaviour with a single
+        # pending_xref node
        result = super().make_xref(rolename, domain, target,  # type: ignore
-                                   innernode, contnode, env)
+                                   innernode, contnode,
+                                   env, inliner=None, location=None)
        result['refspecific'] = True
        result['py:module'] = env.ref_context.get('py:module')
        result['py:class'] = env.ref_context.get('py:class')
@@ -299,12 +304,23 @@ class PyXrefMixin:
            for node in result.traverse(nodes.Text):
                node.parent[node.parent.index(node)] = nodes.Text(text)
                break
+        elif isinstance(result, pending_xref) and env.config.python_use_unqualified_type_names:
+            children = result.children
+            result.clear()
+
+            shortname = target.split('.')[-1]
+            textnode = innernode('', shortname)
+            contnodes = [pending_xref_condition('', '', textnode, condition='resolved'),
+                         pending_xref_condition('', '', *children, condition='*')]
+            result.extend(contnodes)
+
        return result

    def make_xrefs(self, rolename: str, domain: str, target: str,
                   innernode: Type[TextlikeNode] = nodes.emphasis,
-                   contnode: Node = None, env: BuildEnvironment = None) -> List[Node]:
-        delims = r'(\s*[\[\]\(\),](?:\s*or\s)?\s*|\s+or\s+|\.\.\.)'
+                   contnode: Node = None, env: BuildEnvironment = None,
+                   inliner: Inliner = None, location: Node = None) -> List[Node]:
+        delims = r'(\s*[\[\]\(\),](?:\s*or\s)?\s*|\s+or\s+|\s*\|\s*|\.\.\.)'
        delims_re = re.compile(delims)
        sub_targets = re.split(delims, target)

@@ -319,7 +335,7 @@ class PyXrefMixin:
                results.append(contnode or innernode(sub_target, sub_target))
            else:
                results.append(self.make_xref(rolename, domain, sub_target,
-                                              innernode, contnode, env))
+                                              innernode, contnode, env, inliner, location))

        return results

@@ -327,12 +343,14 @@ class PyXrefMixin:
 class PyField(PyXrefMixin, Field):
    def make_xref(self, rolename: str, domain: str, target: str,
                  innernode: Type[TextlikeNode] = nodes.emphasis,
-                  contnode: Node = None, env: BuildEnvironment = None) -> Node:
+                  contnode: Node = None, env: BuildEnvironment = None,
+                  inliner: Inliner = None, location: Node = None) -> Node:
        if rolename == 'class' and target == 'None':
            # None is not a type, so use obj role instead.
            rolename = 'obj'

-        return super().make_xref(rolename, domain, target, innernode, contnode, env)
+        return super().make_xref(rolename, domain, target, innernode, contnode,
+                                 env, inliner, location)


 class PyGroupedField(PyXrefMixin, GroupedField):
@@ -342,12 +360,14 @@ class PyGroupedField(PyXrefMixin, GroupedField):
 class PyTypedField(PyXrefMixin, TypedField):
    def make_xref(self, rolename: str, domain: str, target: str,
                  innernode: Type[TextlikeNode] = nodes.emphasis,
-                  contnode: Node = None, env: BuildEnvironment = None) -> Node:
+                  contnode: Node = None, env: BuildEnvironment = None,
+                  inliner: Inliner = None, location: Node = None) -> Node:
        if rolename == 'class' and target == 'None':
            # None is not a type, so use obj role instead.
            rolename = 'obj'

-        return super().make_xref(rolename, domain, target, innernode, contnode, env)
+        return super().make_xref(rolename, domain, target, innernode, contnode,
+                                 env, inliner, location)


 class PyObject(ObjectDescription[Tuple[str, str]]):
@@ -448,12 +468,9 @@ class PyObject(ObjectDescription[Tuple[str, str]]):

        if prefix:
            signode += addnodes.desc_addname(prefix, prefix)
-        elif add_module and self.env.config.add_module_names:
-            if modname and modname != 'exceptions':
-                # exceptions are a special case, since they are documented in the
-                # 'exceptions' module.
-                nodetext = modname + '.'
-                signode += addnodes.desc_addname(nodetext, nodetext)
+        elif modname and add_module and self.env.config.add_module_names:
+            nodetext = modname + '.'
+            signode += addnodes.desc_addname(nodetext, nodetext)

        signode += addnodes.desc_name(name, name)
        if arglist:
@@ -1363,10 +1380,6 @@ def builtin_resolver(app: Sphinx, env: BuildEnvironment,

        return s in typing.__all__  # type: ignore

-    content = find_pending_xref_condition(node, 'resolved')
-    if content:
-        contnode = content.children[0]  # type: ignore
-
    if node.get('refdomain') != 'py':
        return None
    elif node.get('reftype') in ('class', 'obj') and node.get('reftarget') == 'None':
--- a/sphinx/environment/init.py
+++ b/sphinx/environment/init.py
@@ -10,6 +10,7 @@

 import os
 import pickle
+import warnings
 from collections import defaultdict
 from copy import copy
 from datetime import datetime
@@ -22,6 +23,7 @@ from docutils.nodes import Node

 from sphinx import addnodes
 from sphinx.config import Config
+from sphinx.deprecation import RemovedInSphinx60Warning
 from sphinx.domains import Domain
 from sphinx.environment.adapters.toctree import TocTree
 from sphinx.errors import BuildEnvironmentError, DocumentError, ExtensionError, SphinxError
@@ -181,6 +183,9 @@ class BuildEnvironment:
        # set up environment
        if app:
            self.setup(app)
+        else:
+            warnings.warn("The 'app' argument for BuildEnvironment() becomes required now.",
+                          RemovedInSphinx60Warning, stacklevel=2)

    def __getstate__(self) -> Dict:
        """Obtains serializable data for pickling."""
--- a/sphinx/environment/collectors/metadata.py
+++ b/sphinx/environment/collectors/metadata.py
@@ -47,7 +47,7 @@ class MetadataCollector(EnvironmentCollector):
                    md[field_name.astext()] = field_body.astext()
                elif isinstance(node, nodes.TextElement):
                    # other children must be TextElement
-                    # see: http://docutils.sourceforge.net/docs/ref/doctree.html#bibliographic-elements  # NOQA
+                    # see: https://docutils.sourceforge.io/docs/ref/doctree.html#bibliographic-elements  # NOQA
                    md[node.__class__.__name__] = node.astext()

            for name, value in md.items():
--- a/sphinx/ext/autodoc/init.py
+++ b/sphinx/ext/autodoc/init.py
@@ -70,6 +70,9 @@ class _All:
    def __contains__(self, item: Any) -> bool:
        return True

+    def append(self, item: Any) -> None:
+        pass  # nothing
+

 class _Empty:
    """A special value for :exclude-members: that never matches to any member."""
@@ -1440,6 +1443,15 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:

    def __init__(self, *args: Any) -> None:
        super().__init__(*args)
+
+        if self.config.autodoc_class_signature == 'separated':
+            # show __init__() method
+            if self.options.special_members is None:
+                self.options['special-members'] = {'__new__', '__init__'}
+            else:
+                self.options.special_members.append('__new__')
+                self.options.special_members.append('__init__')
+
        merge_members_option(self.options)

    @classmethod
@@ -1556,6 +1568,9 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
    def format_signature(self, **kwargs: Any) -> str:
        if self.doc_as_attr:
            return ''
+        if self.config.autodoc_class_signature == 'separated':
+            # do not show signatures
+            return ''

        sig = super().format_signature()
        sigs = []
@@ -1626,18 +1641,23 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:

        # add inheritance info, if wanted
        if not self.doc_as_attr and self.options.show_inheritance:
-            sourcename = self.get_sourcename()
-            self.add_line('', sourcename)
-
            if hasattr(self.object, '__orig_bases__') and len(self.object.__orig_bases__):
                # A subclass of generic types
                # refs: PEP-560 <https://www.python.org/dev/peps/pep-0560/>
-                bases = [restify(cls) for cls in self.object.__orig_bases__]
-                self.add_line('   ' + _('Bases: %s') % ', '.join(bases), sourcename)
+                bases = list(self.object.__orig_bases__)
            elif hasattr(self.object, '__bases__') and len(self.object.__bases__):
                # A normal class
-                bases = [restify(cls) for cls in self.object.__bases__]
-                self.add_line('   ' + _('Bases: %s') % ', '.join(bases), sourcename)
+                bases = list(self.object.__bases__)
+            else:
+                bases = []
+
+            self.env.events.emit('autodoc-process-bases',
+                                 self.fullname, self.object, self.options, bases)
+
+            base_classes = [restify(cls) for cls in bases]
+            sourcename = self.get_sourcename()
+            self.add_line('', sourcename)
+            self.add_line('   ' + _('Bases: %s') % ', '.join(base_classes), sourcename)

    def get_object_members(self, want_all: bool) -> Tuple[bool, ObjectMembers]:
        members = get_class_members(self.object, self.objpath, self.get_attr)
@@ -1661,7 +1681,11 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
    def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
        if self.doc_as_attr:
            # Don't show the docstring of the class when it is an alias.
-            return None
+            comment = self.get_variable_comment()
+            if comment:
+                return []
+            else:
+                return None

        lines = getattr(self, '_new_docstrings', None)
        if lines is not None:
@@ -1680,7 +1704,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
            __init__ = self.get_attr(self.object, '__init__', None)
            initdocstring = getdoc(__init__, self.get_attr,
                                   self.config.autodoc_inherit_docstrings,
-                                   self.parent, self.object_name)
+                                   self.object, '__init__')
            # for new-style classes, no __init__ means default __init__
            if (initdocstring is not None and
                (initdocstring == object.__init__.__doc__ or  # for pypy
@@ -1691,7 +1715,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
                __new__ = self.get_attr(self.object, '__new__', None)
                initdocstring = getdoc(__new__, self.get_attr,
                                       self.config.autodoc_inherit_docstrings,
-                                       self.parent, self.object_name)
+                                       self.object, '__new__')
                # for new-style classes, no __new__ means default __new__
                if (initdocstring is not None and
                    (initdocstring == object.__new__.__doc__ or  # for pypy
@@ -1706,9 +1730,18 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
        tab_width = self.directive.state.document.settings.tab_width
        return [prepare_docstring(docstring, ignore, tab_width) for docstring in docstrings]

+    def get_variable_comment(self) -> Optional[List[str]]:
+        try:
+            key = ('', '.'.join(self.objpath))
+            analyzer = ModuleAnalyzer.for_module(self.get_real_modname())
+            analyzer.analyze()
+            return list(self.analyzer.attr_docs.get(key, []))
+        except PycodeError:
+            return None
+
    def add_content(self, more_content: Optional[StringList], no_docstring: bool = False
                    ) -> None:
-        if self.doc_as_attr:
+        if self.doc_as_attr and not self.get_variable_comment():
            try:
                more_content = StringList([_('alias of %s') % restify(self.object)], source='')
            except AttributeError:
@@ -1949,11 +1982,13 @@ class DataDocumenter(GenericAliasMixin, NewTypeMixin, TypeVarMixin,
            self.add_line('   :annotation: %s' % self.options.annotation,
                          sourcename)
        else:
-            # obtain annotation for this data
-            annotations = get_type_hints(self.parent, None, self.config.autodoc_type_aliases)
-            if self.objpath[-1] in annotations:
-                objrepr = stringify_typehint(annotations.get(self.objpath[-1]))
-                self.add_line('   :type: ' + objrepr, sourcename)
+            if self.config.autodoc_typehints != 'none':
+                # obtain annotation for this data
+                annotations = get_type_hints(self.parent, None,
+                                             self.config.autodoc_type_aliases)
+                if self.objpath[-1] in annotations:
+                    objrepr = stringify_typehint(annotations.get(self.objpath[-1]))
+                    self.add_line('   :type: ' + objrepr, sourcename)

            try:
                if self.options.no_value or self.should_suppress_value_header():
@@ -2193,6 +2228,38 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):  # type:
        else:
            return None

+    def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
+        if self.objpath[-1] == '__init__':
+            docstring = getdoc(self.object, self.get_attr,
+                               self.config.autodoc_inherit_docstrings,
+                               self.parent, self.object_name)
+            if (docstring is not None and
+                (docstring == object.__init__.__doc__ or  # for pypy
+                 docstring.strip() == object.__init__.__doc__)):  # for !pypy
+                docstring = None
+            if docstring:
+                tab_width = self.directive.state.document.settings.tab_width
+                return [prepare_docstring(docstring, tabsize=tab_width)]
+            else:
+                return []
+        elif self.objpath[-1] == '__new__':
+            __new__ = self.get_attr(self.object, '__new__', None)
+            if __new__:
+                docstring = getdoc(__new__, self.get_attr,
+                                   self.config.autodoc_inherit_docstrings,
+                                   self.parent, self.object_name)
+                if (docstring is not None and
+                    (docstring == object.__new__.__doc__ or  # for pypy
+                     docstring.strip() == object.__new__.__doc__)):  # for !pypy
+                    docstring = None
+            if docstring:
+                tab_width = self.directive.state.document.settings.tab_width
+                return [prepare_docstring(docstring, tabsize=tab_width)]
+            else:
+                return []
+        else:
+            return super().get_doc()
+

 class NonDataDescriptorMixin(DataDocumenterMixinBase):
    """
@@ -2291,9 +2358,29 @@ class RuntimeInstanceAttributeMixin(DataDocumenterMixinBase):
        # An instance variable defined in __init__().
        if self.get_attribute_comment(parent, self.objpath[-1]):  # type: ignore
            return True
+        elif self.is_runtime_instance_attribute_not_commented(parent):
+            return True
        else:
            return False

+    def is_runtime_instance_attribute_not_commented(self, parent: Any) -> bool:
+        """Check the subject is an attribute defined in __init__() without comment."""
+        for cls in inspect.getmro(parent):
+            try:
+                module = safe_getattr(cls, '__module__')
+                qualname = safe_getattr(cls, '__qualname__')
+
+                analyzer = ModuleAnalyzer.for_module(module)
+                analyzer.analyze()
+                if qualname and self.objpath:
+                    key = '.'.join([qualname, self.objpath[-1]])
+                    if key in analyzer.tagorder:
+                        return True
+            except (AttributeError, PycodeError):
+                pass
+
+        return None
+
    def import_object(self, raiseerror: bool = False) -> bool:
        """Check the existence of runtime instance attribute when failed to import the
        attribute."""
@@ -2324,6 +2411,13 @@ class RuntimeInstanceAttributeMixin(DataDocumenterMixinBase):
        return (self.object is self.RUNTIME_INSTANCE_ATTRIBUTE or
                super().should_suppress_value_header())

+    def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
+        if (self.object is self.RUNTIME_INSTANCE_ATTRIBUTE and
+                self.is_runtime_instance_attribute_not_commented(self.parent)):
+            return None
+        else:
+            return super().get_doc(ignore)  # type: ignore
+

 class UninitializedInstanceAttributeMixin(DataDocumenterMixinBase):
    """
@@ -2492,11 +2586,13 @@ class AttributeDocumenter(GenericAliasMixin, NewTypeMixin, SlotsMixin,  # type:
        elif self.options.annotation:
            self.add_line('   :annotation: %s' % self.options.annotation, sourcename)
        else:
-            # obtain type annotation for this attribute
-            annotations = get_type_hints(self.parent, None, self.config.autodoc_type_aliases)
-            if self.objpath[-1] in annotations:
-                objrepr = stringify_typehint(annotations.get(self.objpath[-1]))
-                self.add_line('   :type: ' + objrepr, sourcename)
+            if self.config.autodoc_typehints != 'none':
+                # obtain type annotation for this attribute
+                annotations = get_type_hints(self.parent, None,
+                                             self.config.autodoc_type_aliases)
+                if self.objpath[-1] in annotations:
+                    objrepr = stringify_typehint(annotations.get(self.objpath[-1]))
+                    self.add_line('   :type: ' + objrepr, sourcename)

            try:
                if self.options.no_value or self.should_suppress_value_header():
@@ -2580,7 +2676,7 @@ class PropertyDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter):  #
        if inspect.isabstractmethod(self.object):
            self.add_line('   :abstractmethod:', sourcename)

-        if safe_getattr(self.object, 'fget', None):
+        if safe_getattr(self.object, 'fget', None) and self.config.autodoc_typehints != 'none':
            try:
                signature = inspect.signature(self.object.fget,
                                              type_aliases=self.config.autodoc_type_aliases)
@@ -2662,6 +2758,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
    app.add_config_value('autoclass_content', 'class', True, ENUM('both', 'class', 'init'))
    app.add_config_value('autodoc_member_order', 'alphabetical', True,
                         ENUM('alphabetic', 'alphabetical', 'bysource', 'groupwise'))
+    app.add_config_value('autodoc_class_signature', 'mixed', True, ENUM('mixed', 'separated'))
    app.add_config_value('autodoc_default_options', {}, True)
    app.add_config_value('autodoc_docstring_signature', True, True)
    app.add_config_value('autodoc_mock_imports', [], True)
@@ -2676,6 +2773,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
    app.add_event('autodoc-process-docstring')
    app.add_event('autodoc-process-signature')
    app.add_event('autodoc-skip-member')
+    app.add_event('autodoc-process-bases')

    app.connect('config-inited', migrate_autodoc_member_order, priority=800)

--- a/sphinx/ext/autosummary/init.py
+++ b/sphinx/ext/autosummary/init.py
@@ -72,7 +72,8 @@ import sphinx
 from sphinx import addnodes
 from sphinx.application import Sphinx
 from sphinx.config import Config
-from sphinx.deprecation import RemovedInSphinx50Warning
+from sphinx.deprecation import (RemovedInSphinx50Warning, RemovedInSphinx60Warning,
+                                deprecated_alias)
 from sphinx.environment import BuildEnvironment
 from sphinx.environment.adapters.toctree import TocTree
 from sphinx.ext.autodoc import INSTANCEATTR, Documenter
@@ -80,7 +81,9 @@ from sphinx.ext.autodoc.directive import DocumenterBridge, Options
 from sphinx.ext.autodoc.importer import import_module
 from sphinx.ext.autodoc.mock import mock
 from sphinx.locale import __
+from sphinx.project import Project
 from sphinx.pycode import ModuleAnalyzer, PycodeError
+from sphinx.registry import SphinxComponentRegistry
 from sphinx.util import logging, rst
 from sphinx.util.docutils import (NullReporter, SphinxDirective, SphinxRole, new_document,
                                  switch_source_input)
@@ -163,17 +166,33 @@ def autosummary_table_visit_html(self: HTMLTranslator, node: autosummary_table)


 # -- autodoc integration -------------------------------------------------------
+deprecated_alias('sphinx.ext.autosummary',
+                 {
+                     '_app': None,
+                 },
+                 RemovedInSphinx60Warning,
+                 {
+                 })

-# current application object (used in `get_documenter()`).
-_app: Sphinx = None
+
+class FakeApplication:
+    def __init__(self):
+        self.doctreedir = None
+        self.events = None
+        self.extensions = {}
+        self.srcdir = None
+        self.config = Config()
+        self.project = Project(None, None)
+        self.registry = SphinxComponentRegistry()


 class FakeDirective(DocumenterBridge):
    def __init__(self) -> None:
        settings = Struct(tab_width=8)
        document = Struct(settings=settings)
-        env = BuildEnvironment()
-        env.config = Config()
+        app = FakeApplication()
+        app.config.add('autodoc_class_signature', 'mixed', True, None)
+        env = BuildEnvironment(app)  # type: ignore
        state = Struct(document=document)
        super().__init__(env, None, Options(), 0, state)

--- a/sphinx/ext/intersphinx.py
+++ b/sphinx/ext/intersphinx.py
@@ -45,7 +45,6 @@ from sphinx.environment import BuildEnvironment
 from sphinx.locale import _, __
 from sphinx.util import logging, requests
 from sphinx.util.inventory import InventoryFile
-from sphinx.util.nodes import find_pending_xref_condition
 from sphinx.util.typing import Inventory

 logger = logging.getLogger(__name__)
@@ -287,16 +286,6 @@ def missing_reference(app: Sphinx, env: BuildEnvironment, node: pending_xref,
        # Since Sphinx-2.1, properties are stored as py:method
        objtypes.append('py:method')

-    # determine the contnode by pending_xref_condition
-    content = find_pending_xref_condition(node, 'resolved')
-    if content:
-        # resolved condition found.
-        contnodes = content.children
-        contnode = content.children[0]  # type: ignore
-    else:
-        # not resolved. Use the given contnode
-        contnodes = [contnode]
-
    to_try = [(inventories.main_inventory, target)]
    if domain:
        full_qualified_name = env.get_domain(domain).get_full_qualified_name(node)
@@ -329,7 +318,7 @@ def missing_reference(app: Sphinx, env: BuildEnvironment, node: pending_xref,
            newnode = nodes.reference('', '', internal=False, refuri=uri, reftitle=reftitle)
            if node.get('refexplicit'):
                # use whatever title was given
-                newnode.extend(contnodes)
+                newnode.append(contnode)
            elif dispname == '-' or \
                    (domain == 'std' and node['reftype'] == 'keyword'):
                # use whatever title was given, but strip prefix
@@ -338,7 +327,7 @@ def missing_reference(app: Sphinx, env: BuildEnvironment, node: pending_xref,
                    newnode.append(contnode.__class__(title[len(in_set) + 1:],
                                                      title[len(in_set) + 1:]))
                else:
-                    newnode.extend(contnodes)
+                    newnode.append(contnode)
            else:
                # else use the given display name (used for :ref:)
                newnode.append(contnode.__class__(dispname, dispname))
--- a/sphinx/ext/mathjax.py
+++ b/sphinx/ext/mathjax.py
@@ -79,7 +79,7 @@ def install_mathjax(app: Sphinx, pagename: str, templatename: str, context: Dict
                             'mathjax extension to work')

    domain = cast(MathDomain, app.env.get_domain('math'))
-    if domain.has_equations(pagename):
+    if app.registry.html_assets_policy == 'always' or domain.has_equations(pagename):
        # Enable mathjax only if equations exists
        options = {'async': 'async'}
        if app.config.mathjax_options:
--- a/sphinx/locale/ar/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/ar/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/ar/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/ar/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/bg/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/bg/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/bg/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/bg/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/bn/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/bn/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/bn/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/bn/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/ca/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/ca/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/ca/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/ca/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/cak/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/cak/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/cak/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/cak/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/cs/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/cs/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/cs/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/cs/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/cy/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/cy/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/cy/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/cy/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/da/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/da/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/da/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/da/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/de/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/de/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/de/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/de/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/el/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/el/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/el/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/el/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/eo/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/eo/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/eo/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/eo/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/es/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/es/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/es/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/es/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/et/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/et/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/et/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/et/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/eu/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/eu/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/eu/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/eu/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/fa/LC_MESSAGES/sphinx.js
+++ b/sphinx/locale/fa/LC_MESSAGES/sphinx.js
@@ -12,18 +12,18 @@ Documentation.addTranslations({
        "Collapse sidebar": "\u062a\u0627 \u06a9\u0631\u062f\u0646 \u0646\u0648\u0627\u0631 \u06a9\u0646\u0627\u0631\u0647",
        "Complete Table of Contents": "\u0641\u0647\u0631\u0633\u062a \u06a9\u0627\u0645\u0644 \u0645\u0637\u0627\u0644\u0628",
        "Contents": "\u0645\u062d\u062a\u0648\u0627 \u0647\u0627",
-        "Copyright": "\u062d\u0642 \u0627\u0646\u062a\u0634\u0627\u0631",
+        "Copyright": "\u06a9\u067e\u06cc \u0631\u0627\u06cc\u062a",
        "Created using <a href=\"https://www.sphinx-doc.org/\">Sphinx</a> %(sphinx_version)s.": "\u0627\u06cc\u062c\u0627\u062f \u0634\u062f\u0647 \u0628\u0627<a href=\"https://www.sphinx-doc.org/\">Sphinx</a> %(sphinx_version)s.",
        "Expand sidebar": "\u06af\u0633\u062a\u0631\u0634 \u0646\u0648\u0627\u0631 \u06a9\u0646\u0627\u0631\u0647",
        "Full index on one page": "\u0641\u0647\u0631\u0633\u062a \u06a9\u0627\u0645\u0644 \u062f\u0631 \u06cc\u06a9 \u0635\u0641\u062d\u0647",
        "General Index": "\u0641\u0647\u0631\u0633\u062a \u06a9\u0644\u06cc",
        "Global Module Index": "\u0641\u0647\u0631\u0633\u062a \u06a9\u0644\u06cc \u0645\u0627\u0698\u0648\u0644 \u0647\u0627",
-        "Go": "\u0631\u0641\u062a\u0646 \u0628\u0647",
+        "Go": "\u0628\u0631\u0648",
        "Hide Search Matches": "\u0639\u062f\u0645 \u0646\u0645\u0627\u06cc\u0634 \u0646\u062a\u0627\u06cc\u062c \u06cc\u0627\u0641\u062a \u0634\u062f\u0647",
        "Index": "\u0641\u0647\u0631\u0633\u062a",
        "Index &ndash; %(key)s": "\u0641\u0647\u0631\u0633\u062a &ndash; %(key)s",
        "Index pages by letter": "\u0641\u0647\u0631\u0633\u062a \u0635\u0641\u062d\u0627\u062a \u0628\u0631 \u0627\u0633\u0627\u0633 \u062d\u0631\u0648\u0641",
-        "Indices and tables:": "\u0646\u0645\u0627\u06cc\u0647\u200c\u0647\u0627 \u0648 \u062c\u062f\u0648\u0644\u200c\u0647\u0627:",
+        "Indices and tables:": "\u0627\u06cc\u0646\u062f\u06a9\u0633 \u0647\u0627 \u0648 \u062c\u062f\u0627\u0648\u0644:",
        "Last updated on %(last_updated)s.": "\u0622\u062e\u0631\u06cc\u0646 \u0628\u0631\u0648\u0632 \u0631\u0633\u0627\u0646\u06cc \u062f\u0631 %(last_updated)s .",
        "Library changes": "\u062a\u063a\u06cc\u06cc\u0631\u0627\u062a \u06a9\u062a\u0627\u0628\u062e\u0627\u0646\u0647 \u0627\u06cc\u06cc",
        "Navigation": "\u0646\u0627\u0648\u0628\u0631\u06cc",
--- a/sphinx/locale/fa/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/fa/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/fa/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/fa/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/fi/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/fi/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/fi/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/fi/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/fr/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/fr/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/fr/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/fr/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/fr_FR/LC_MESSAGES/sphinx.js
+++ b/sphinx/locale/fr_FR/LC_MESSAGES/sphinx.js
@@ -0,0 +1,63 @@
+Documentation.addTranslations({
+    "locale": "fr_FR",
+    "messages": {
+        "%(filename)s &#8212; %(docstitle)s": "",
+        "&#169; <a href=\"%(path)s\">Copyright</a> %(copyright)s.": "",
+        "&#169; Copyright %(copyright)s.": "",
+        ", in ": "",
+        "About these documents": "",
+        "Automatically generated list of changes in version %(version)s": "",
+        "C API changes": "",
+        "Changes in Version %(version)s &#8212; %(docstitle)s": "",
+        "Collapse sidebar": "",
+        "Complete Table of Contents": "",
+        "Contents": "",
+        "Copyright": "",
+        "Created using <a href=\"https://www.sphinx-doc.org/\">Sphinx</a> %(sphinx_version)s.": "",
+        "Expand sidebar": "",
+        "Full index on one page": "",
+        "General Index": "",
+        "Global Module Index": "",
+        "Go": "",
+        "Hide Search Matches": "",
+        "Index": "",
+        "Index &ndash; %(key)s": "",
+        "Index pages by letter": "",
+        "Indices and tables:": "",
+        "Last updated on %(last_updated)s.": "",
+        "Library changes": "",
+        "Navigation": "",
+        "Next topic": "",
+        "Other changes": "",
+        "Overview": "",
+        "Permalink to this definition": "",
+        "Permalink to this headline": "",
+        "Please activate JavaScript to enable the search\n    functionality.": "",
+        "Preparing search...": "",
+        "Previous topic": "",
+        "Quick search": "",
+        "Search": "",
+        "Search Page": "",
+        "Search Results": "",
+        "Search finished, found %s page(s) matching the search query.": "",
+        "Search within %(docstitle)s": "",
+        "Searching": "",
+        "Searching for multiple words only shows matches that contain\n    all words.": "",
+        "Show Source": "",
+        "Table of Contents": "",
+        "This Page": "",
+        "Welcome! This is": "",
+        "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "",
+        "all functions, classes, terms": "",
+        "can be huge": "",
+        "last updated": "",
+        "lists all sections and subsections": "",
+        "next chapter": "",
+        "previous chapter": "",
+        "quick access to all modules": "",
+        "search": "",
+        "search this documentation": "",
+        "the documentation for": ""
+    },
+    "plural_expr": "(n > 1)"
+});
--- a/sphinx/locale/fr_FR/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/fr_FR/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/fr_FR/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/fr_FR/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/he/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/he/LC_MESSAGES/sphinx.mo
--- a/sphinx/locale/he/LC_MESSAGES/sphinx.po
+++ b/sphinx/locale/he/LC_MESSAGES/sphinx.po
--- a/sphinx/locale/hi/LC_MESSAGES/sphinx.mo
+++ b/sphinx/locale/hi/LC_MESSAGES/sphinx.mo
--- a/Show More
+++ b/Show More