Merge branch '5.x' into remove-deprecated

# Conflicts:
#	sphinx/registry.py

.github/workflows/lint.yml

@@ -13,9 +13,9 @@ jobs:
     steps:
     - uses: actions/checkout@v2
     - name: Set up Python
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v4
       with:
-        python-version: 3.6
+        python-version: '>=3.7'
     - name: Install dependencies
       run:  pip install -U tox
     - name: Run Tox

AUTHORS

@@ -15,10 +15,10 @@ Other co-maintainers:
 * Jean-François Burnol <@jfbu>
 * Yoshiki Shibukawa <@shibu_jp>
 * Timotheus Kampik - <@TimKam>
+* Adam Turner - <@AA-Turner>
 
 Other contributors, listed alphabetically, are:
 
-* Adam Turner -- JavaScript improvements
 * Alastair Houghton -- Apple Help builder
 * Alexander Todorov -- inheritance_diagram tests and improvements
 * Andi Albrecht -- agogo theme
@@ -96,5 +96,3 @@ authors and projects:
 
 * sphinx.util.jsdump uses the basestring encoding from simplejson,
   written by Bob Ippolito, released under the MIT license
-* sphinx.util.stemmer was written by Vivake Gupta, placed in the
-  Public Domain

CHANGES

@@ -31,17 +31,28 @@ Incompatible changes
 Deprecated
 ----------
 
+* #10467: Deprecated ``sphinx.util.stemmer`` in favour of ``snowballstemmer``.
+  Patch by Adam Turner.
+
 Features added
 --------------
 
+* #10366: std domain: Add support for emphasising placeholders in :rst:dir`option`
+  directives through a new ``option_emphasise_placeholders`` configuration option.
+
 Bugs fixed
 ----------
 
+* #10031: py domain: Fix spurious whitespace in unparsing various operators (``+``,
+  ``-``, ``~``, and ``**``). Patch by Adam Turner.
+* #10460: logging: Always show node source locations as absolute paths.
+* #10520: HTML Theme: Fix use of sidebar classes in ``agogo.css_t``.
+
 Testing
 --------
 
-Release 5.0.0 beta2 (in development)
-====================================
+Release 5.0.3 (in development)
+==============================
 
 Dependencies
 ------------
@@ -58,33 +69,59 @@ Features added
 Bugs fixed
 ----------
 
-* #9575: autodoc: The annotation of return value should not be shown when
-  ``autodoc_typehints="description"``
-* #9648: autodoc: ``*args`` and ``**kwargs`` entries are duplicated when
-  ``autodoc_typehints="description"``
-* #8180: autodoc: Docstring metadata ignored for attributes
-* #10443: epub: EPUB builder can't detect the mimetype of .webp file
-* #10456: py domain: ``:meta:`` fields are displayed if docstring contains two
-  or more meta-field
-* #9096: sphinx-build: the value of progress bar for paralle build is wrong
-* #10110: sphinx-build: exit code is not changed when error is raised on
-  builder-finished event
-
 Testing
 --------
 
-Release 5.0.0 beta1 (released May 09, 2022)
-===========================================
+Release 5.0.2 (released Jun 17, 2022)
+=====================================
+
+Features added
+--------------
+
+* #10523: HTML Theme: Expose the Docutils's version info tuple as a template
+  variable, ``docutils_version_info``. Patch by Adam Turner.
+
+Bugs fixed
+----------
+
+* #10538: autodoc: Inherited class attribute having docstring is documented even
+  if :confval:`autodoc_inherit_docstring` is disabled
+* #10509: autosummary: autosummary fails with a shared library
+* #10497: py domain: Failed to resolve strings in Literal. Patch by Adam Turner.
+* #10523: HTML Theme: Fix double brackets on citation references in Docutils 0.18+.
+  Patch by Adam Turner.
+* #10534: Missing CSS for nav.contents in Docutils 0.18+. Patch by Adam Turner.
+
+Release 5.0.1 (released Jun 03, 2022)
+=====================================
+
+Bugs fixed
+----------
+
+* #10498: gettext: TypeError is raised when sorting warning messages if a node
+  has no line number. Patch by Adam Turner.
+* #10493: HTML Theme: :rst:dir:`topic` directive is rendered incorrectly with
+  Docutils 0.18. Patch by Adam Turner.
+* #10495: IndexError is raised for a :rst:role:`kbd` role having a separator.
+  Patch by Adam Turner.
+
+Release 5.0.0 (released May 30, 2022)
+=====================================
 
 Dependencies
 ------------
+
+5.0.0 b1
+
 * #10164: Support `Docutils 0.18`_. Patch by Adam Turner.
 
 .. _Docutils 0.18:  https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-18-2021-10-26
 
 Incompatible changes
 --------------------
 
+5.0.0 b1
+
 * #10031: autosummary: ``sphinx.ext.autosummary.import_by_name()`` now raises
   ``ImportExceptionGroup`` instead of ``ImportError`` when it failed to import
   target object.  Please handle the exception if your extension uses the
@@ -103,9 +140,17 @@ Incompatible changes
 * #10062: Change the default language to ``'en'`` if any language is not set in
   ``conf.py``
 
+5.0.0 final
+
+* #10474: :confval:`language` does not accept ``None`` as it value.  The default
+  value of ``language`` becomes to ``'en'`` now.
+  Patch by Adam Turner and Takeshi KOMIYA.
+
 Deprecated
 ----------
 
+5.0.0 b1
+
 * #10028: jQuery and underscore.js will no longer be automatically injected into
   themes from Sphinx 6.0. If you develop a theme or extension that uses the
   ``jQuery``, ``$``, or ``$u`` global objects, you need to update your
@@ -123,6 +168,8 @@ Deprecated
          <script src="{{ pathto('_static/underscore.js', resource=True) }}"></script>
          {{ super() }}
      {%- endblock %}
+
+   Patch by Adam Turner.
 * setuptools integration.  The ``build_sphinx`` sub-command for setup.py is
   marked as deprecated to follow the policy of setuptools team.
 * The ``locale`` argument of ``sphinx.util.i18n:babel_format_date()`` becomes
@@ -138,6 +185,8 @@ Deprecated
 Features added
 --------------
 
+5.0.0 b1
+
 * #9075: autodoc: The default value of :confval:`autodoc_typehints_format` is
   changed to ``'smart'``.  It will suppress the leading module names of
   typehints (ex. ``io.StringIO`` -> ``StringIO``).
@@ -153,17 +202,20 @@ Features added
   non-imported
 * #10028: Removed internal usages of JavaScript frameworks (jQuery and
   underscore.js) and modernised ``doctools.js`` and ``searchtools.js`` to
-  EMCAScript 2018.
+  EMCAScript 2018. Patch by Adam Turner.
 * #10302: C++, add support for conditional expressions (``?:``).
 * #5157, #10251: Inline code is able to be highlighted via :rst:dir:`role`
   directive
-* #10337: Make sphinx-build faster by caching Publisher object during build
+* #10337: Make sphinx-build faster by caching Publisher object during build.
+  Patch by Adam Turner.
 
 Bugs fixed
 ----------
 
+5.0.0 b1
+
 * #10200: apidoc: Duplicated submodules are shown for modules having both .pyx
-  and .so files
+  and .so files. Patch by Adam Turner and Takeshi KOMIYA.
 * #10279: autodoc: Default values for keyword only arguments in overloaded
   functions are rendered as a string literal
 * #10280: autodoc: :confval:`autodoc_docstring_signature` unexpectedly generates
@@ -191,8 +243,21 @@ Bugs fixed
 * #10318: ``:prepend:`` option of :rst:dir:`literalinclude` directive does not
   work with ``:dedent:`` option
 
-Release 4.5.1 (in development)
-==============================
+5.0.0 final
+
+* #9575: autodoc: The annotation of return value should not be shown when
+  ``autodoc_typehints="description"``
+* #9648: autodoc: ``*args`` and ``**kwargs`` entries are duplicated when
+  ``autodoc_typehints="description"``
+* #8180: autodoc: Docstring metadata ignored for attributes
+* #10443: epub: EPUB builder can't detect the mimetype of .webp file
+* #10104: gettext: Duplicated locations are shown if 3rd party extension does
+  not provide correct information
+* #10456: py domain: ``:meta:`` fields are displayed if docstring contains two
+  or more meta-field
+* #9096: sphinx-build: the value of progress bar for paralle build is wrong
+* #10110: sphinx-build: exit code is not changed when error is raised on
+  builder-finished event
 
 Release 4.5.0 (released Mar 28, 2022)
 =====================================

EXAMPLES

@@ -40,7 +40,7 @@ Documentation using the alabaster theme
 * `pytest <https://docs.pytest.org/>`__ (customized)
 * `python-apt <https://apt-team.pages.debian.net/python-apt/>`__
 * `PyVisfile <https://documen.tician.de/pyvisfile/>`__
-* `Requests <https://docs.python-requests.org/>`__
+* `Requests <https://requests.readthedocs.io/>`__
 * `searx <https://asciimoo.github.io/searx/>`__
 * `Spyder <https://docs.spyder-ide.org/>`__ (customized)
 * `Tablib <http://docs.python-tablib.org/>`__

Makefile

@@ -62,7 +62,7 @@ type-check:
 
 .PHONY: doclinter
 doclinter:
-	python utils/doclinter.py CHANGES *.rst doc/
+	sphinx-lint --enable line-too-long --max-line-length 85 CHANGES *.rst doc/
 
 .PHONY: test
 test:

README.rst

@@ -6,118 +6,57 @@
    :target: https://pypi.org/project/Sphinx/
    :alt: Package on PyPI
 
+.. image:: https://github.com/sphinx-doc/sphinx/actions/workflows/main.yml/badge.svg
+   :target: https://github.com/sphinx-doc/sphinx/actions/workflows/main.yml
+   :alt: Build Status
+
 .. image:: https://readthedocs.org/projects/sphinx/badge/?version=master
-   :target: http://www.sphinx-doc.org/
+   :target: https://www.sphinx-doc.org/
    :alt: Documentation Status
 
-.. image:: https://ci.appveyor.com/api/projects/status/github/sphinx-doc/sphinx?branch=master&svg=true
-   :target: https://ci.appveyor.com/project/sphinxdoc/sphinx
-   :alt: Build Status (AppVeyor)
-
-.. image:: https://circleci.com/gh/sphinx-doc/sphinx.svg?style=shield
-   :target: https://circleci.com/gh/sphinx-doc/sphinx
-   :alt: Build Status (CircleCI)
-
-.. image:: https://codecov.io/gh/sphinx-doc/sphinx/branch/master/graph/badge.svg
-   :target: https://codecov.io/gh/sphinx-doc/sphinx
-   :alt: Code Coverage Status (Codecov)
-
-.. image:: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg
-   :target: https://opensource.org/licenses/BSD-3-Clause
-   :alt: BSD 3 Clause
+.. image:: https://img.shields.io/badge/License-BSD%202--Clause-blue.svg
+   :target: https://opensource.org/licenses/BSD-2-Clause
+   :alt: BSD 2 Clause
 
-.. image:: https://codetriage.com/sphinx-doc/sphinx/badges/users.svg
-   :target: https://codetriage.com/sphinx-doc/sphinx
-   :alt: Open Source Helpers badge
-
-Sphinx is a tool that makes it easy to create intelligent and beautiful
-documentation for Python projects (or other documents consisting of multiple
-reStructuredText sources), written by Georg Brandl.  It was originally created
-for the new Python documentation, and has excellent facilities for Python
-project documentation, but C/C++ is supported as well, and more languages are
-planned.
+**Sphinx makes it easy to create intelligent and beautiful documentation.**
 
 Sphinx uses reStructuredText as its markup language, and many of its strengths
 come from the power and straightforwardness of reStructuredText and its parsing
 and translating suite, the Docutils.
 
-Among its features are the following:
+Features
+========
 
-* Output formats: HTML (including derivative formats such as HTML Help, Epub
-  and Qt Help), plain text, manual pages and LaTeX or direct PDF output
-  using rst2pdf
-* Extensive cross-references: semantic markup and automatic links
+* **Output formats**: HTML, PDF, plain text, EPUB, TeX, manual pages, and more
+* **Extensive cross-references**: semantic markup and automatic links
   for functions, classes, glossary terms and similar pieces of information
-* Hierarchical structure: easy definition of a document tree, with automatic
+* **Hierarchical structure**: easy definition of a document tree, with automatic
   links to siblings, parents and children
-* Automatic indices: general index as well as a module index
-* Code handling: automatic highlighting using the Pygments highlighter
-* Flexible HTML output using the Jinja 2 templating engine
-* Various extensions are available, e.g. for automatic testing of snippets
-  and inclusion of appropriately formatted docstrings
-* Setuptools integration
-
-For more information, refer to the `the documentation`__.
+* **Automatic indices**: general index as well as a module index
+* **Code highlighting**: automatic highlighting using the Pygments highlighter
+* **Templating**: Flexible HTML output using the Jinja 2 templating engine
+* **Extension ecosystem**: Many extensions are available, for example for
+  automatic function documentation or working with Jupyter notebooks.
+* **Language Support**: Python, C, C++, JavaScript, mathematics, and many other
+  languages through extensions.
 
-.. __: http://www.sphinx-doc.org/
+For more information, refer to the `the documentation`_.
 
 Installation
 ============
 
-Sphinx is published on `PyPI`__ and can be installed from there::
-
-   pip install -U sphinx
-
-We also publish beta releases::
-
-   pip install -U --pre sphinx
-
-If you wish to install `Sphinx` for development purposes, refer to `the
-contributors guide`__.
-
-__ https://pypi.org/project/Sphinx/
-__ http://www.sphinx-doc.org/en/master/internals/contributing.html
-
-Documentation
-=============
+The following command installs Sphinx from the `Python Package Index`_. You will
+need a working installation of Python and pip.
 
-Documentation is available from `sphinx-doc.org`__.
+.. code-block:: sh
 
-__ http://www.sphinx-doc.org/
-
-Get in touch
-============
-
-- Report bugs, suggest features or view the source code `on GitHub`_.
-- For less well defined questions or ideas, use the `mailing list`_.
-
-.. _on GitHub: https://github.com/sphinx-doc/sphinx
-.. _mailing list: https://groups.google.com/forum/#!forum/sphinx-users
-
-Please adhere to our `code of conduct`__.
-
-__ http://www.sphinx-doc.org/en/master/code_of_conduct.html
-
-Testing
-=======
-
-Continuous testing is provided by `Travis`__ (for unit tests and style checks
-on Linux), `AppVeyor`__ (for unit tests on Windows), and `CircleCI`__ (for
-large processes like TeX compilation).
-
-For information on running tests locally, refer to `the contributors guide`__.
-
-__ https://travis-ci.org/sphinx-doc/sphinx
-__ https://ci.appveyor.com/project/sphinxdoc/sphinx
-__ https://circleci.com/gh/sphinx-doc/sphinx
-__ http://www.sphinx-doc.org/en/master/internals/contributing.html
+   pip install -U sphinx
 
 Contributing
 ============
 
-Refer to `the contributors guide`__.
-
-__ http://www.sphinx-doc.org/en/master/internals/contributing.html
+We appreciate all contributions! Refer to `the contributors guide`_ for
+information.
 
 Release signatures
 ==================
@@ -126,3 +65,7 @@ Releases are signed with following keys:
 
 * `498D6B9E <https://pgp.mit.edu/pks/lookup?op=vindex&search=0x102C2C17498D6B9E>`_
 * `5EBA0E07 <https://pgp.mit.edu/pks/lookup?op=vindex&search=0x1425F8CE5EBA0E07>`_
+
+.. _the documentation: https://www.sphinx-doc.org/
+.. _the contributors guide: https://www.sphinx-doc.org/en/master/internals/contributing.html
+.. _Python Package Index: https://pypi.org/project/Sphinx/