Merge branch '5.x'

CHANGES

@@ -40,7 +40,7 @@ Bugs fixed
 Testing
 --------
 
-Release 5.0.1 (in development)
+Release 5.0.3 (in development)
 ==============================
 
 Dependencies
@@ -61,6 +61,39 @@ Bugs fixed
 Testing
 --------
 
+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)
 =====================================
 
@@ -100,6 +133,7 @@ Incompatible changes
 
 * #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
 ----------
@@ -155,19 +189,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

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/

doc/_themes/sphinx13/static/sphinx13.css

@@ -372,7 +372,9 @@ div.quotebar {
     margin-left: 1em;
 }
 
-div.topic {
+nav.contents,
+div.topic,
+aside.topic {
     background-color: #f8f8f8;
 }
 

doc/templating.rst

@@ -383,6 +383,15 @@ in the future.
 
    .. versionadded:: 4.2
 
+.. data:: docutils_version_info
+
+   The version of Docutils used to build represented as a tuple of five elements.
+   For Docutils version 0.16.1 beta 2 this would be `(0, 16, 1, 'beta', 2)``.
+   The fourth element can be one of: ``alpha``, ``beta``, ``candidate``, ``final``.
+   ``final`` always has 0 as the last element.
+
+   .. versionadded:: 5.0.2
+
 .. data:: style
 
    The name of the main stylesheet, as given by the theme or

setup.py

@@ -67,6 +67,7 @@
     long_description_content_type='text/x-rst',
     project_urls={
         "Code": "https://github.com/sphinx-doc/sphinx",
+        "Changelog": "https://www.sphinx-doc.org/en/master/changes.html",
         "Issue tracker": "https://github.com/sphinx-doc/sphinx/issues",
     },
     zip_safe=False,

sphinx/application.py

@@ -129,7 +129,7 @@ class Sphinx:
 
     def __init__(self, srcdir: str, confdir: Optional[str], outdir: str, doctreedir: str,
                  buildername: str, confoverrides: Dict = None,
-                 status: IO = sys.stdout, warning: IO = sys.stderr,
+                 status: Optional[IO] = sys.stdout, warning: Optional[IO] = sys.stderr,
                  freshenv: bool = False, warningiserror: bool = False, tags: List[str] = None,
                  verbosity: int = 0, parallel: int = 0, keep_going: bool = False) -> None:
         self.phase = BuildPhase.INITIALIZATION

sphinx/builders/gettext.py

@@ -53,7 +53,10 @@ def add(self, msg: str, origin: Union[Element, "MsgOrigin"]) -> None:
         if msg not in self.metadata:  # faster lookup in hash
             self.messages.append(msg)
             self.metadata[msg] = []
-        self.metadata[msg].append((origin.source, origin.line, origin.uid))  # type: ignore
+        line = origin.line
+        if line is None:
+            line = -1
+        self.metadata[msg].append((origin.source, line, origin.uid))  # type: ignore
 
     def __iter__(self) -> Generator[Message, None, None]:
         for message in self.messages:

sphinx/builders/html/__init__.py

@@ -536,6 +536,7 @@ def prepare_writing(self, docnames: Set[str]) -> None:
             'css_files': self.css_files,
             'sphinx_version': __display_version__,
             'sphinx_version_tuple': sphinx_version,
+            'docutils_version_info': docutils.__version_info__[:5],
             'style': self._get_style_filename(),
             'rellinks': rellinks,
             'builder': self.name,
@@ -1055,7 +1056,7 @@ def hasdoc(name: str) -> bool:
         # sort JS/CSS before rendering HTML
         try:
             # Convert script_files to list to support non-list script_files (refs: #8889)
-            ctx['script_files'] = sorted(list(ctx['script_files']), key=lambda js: js.priority)
+            ctx['script_files'] = sorted(ctx['script_files'], key=lambda js: js.priority)
         except AttributeError:
             # Skip sorting if users modifies script_files directly (maybe via `html_context`).
             # refs: #8885
@@ -1064,7 +1065,7 @@ def hasdoc(name: str) -> bool:
             pass
 
         try:
-            ctx['css_files'] = sorted(list(ctx['css_files']), key=lambda css: css.priority)
+            ctx['css_files'] = sorted(ctx['css_files'], key=lambda css: css.priority)
         except AttributeError:
             pass
 

sphinx/builders/html/transforms.py

@@ -40,7 +40,9 @@ class KeyboardTransform(SphinxPostTransform):
 
     def run(self, **kwargs: Any) -> None:
         matcher = NodeMatcher(nodes.literal, classes=["kbd"])
-        for node in self.document.findall(matcher):  # type: nodes.literal
+        # this list must be pre-created as during iteration new nodes
+        # are added which match the condition in the NodeMatcher.
+        for node in list(self.document.findall(matcher)):  # type: nodes.literal
             parts = self.pattern.split(node[-1].astext())
             if len(parts) == 1 or self.is_multiwords_key(parts):
                 continue

sphinx/config.py

@@ -164,13 +164,13 @@ def read(cls, confdir: str, overrides: Dict = None, tags: Tags = None) -> "Confi
                               confdir)
         namespace = eval_config_file(filename, tags)
 
-        # Note: Old sphinx projects have been configured as "langugae = None" because
+        # Note: Old sphinx projects have been configured as "language = None" because
         #       sphinx-quickstart previously generated this by default.
         #       To keep compatibility, they should be fallback to 'en' for a while
         #       (This conversion should not be removed before 2025-01-01).
         if namespace.get("language", ...) is None:
             logger.warning(__("Invalid configuration value found: 'language = None'. "
-                              "Update your configuration to a valid langauge code. "
+                              "Update your configuration to a valid language code. "
                               "Falling back to 'en' (English)."))
             namespace["language"] = "en"
 

sphinx/domains/c.py

@@ -2531,7 +2531,7 @@ def _parse_expression_fallback(
             while not self.eof:
                 if (len(symbols) == 0 and self.current_char in end):
                     break
-                if self.current_char in brackets.keys():
+                if self.current_char in brackets:
                     symbols.append(brackets[self.current_char])
                 elif len(symbols) > 0 and self.current_char == symbols[-1]:
                     symbols.pop()

sphinx/domains/cpp.py

@@ -5754,7 +5754,7 @@ def _parse_expression_fallback(self, end: List[str],
             while not self.eof:
                 if (len(symbols) == 0 and self.current_char in end):
                     break
-                if self.current_char in brackets.keys():
+                if self.current_char in brackets:
                     symbols.append(brackets[self.current_char])
                 elif len(symbols) > 0 and self.current_char == symbols[-1]:
                     symbols.pop()

sphinx/domains/python.py

@@ -396,7 +396,7 @@ def make_xrefs(self, rolename: str, domain: str, target: str,
                 results.append(self.make_xref(rolename, domain, sub_target,
                                               innernode, contnode, env, inliner, location))
 
-            if sub_target in ('Literal', 'typing.Literal'):
+            if sub_target in ('Literal', 'typing.Literal', '~typing.Literal'):
                 in_literal = True
 
         return results

sphinx/ext/autodoc/__init__.py

@@ -1670,7 +1670,8 @@ def add_directive_header(self, sig: str) -> None:
             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)
+        members = get_class_members(self.object, self.objpath, self.get_attr,
+                                    self.config.autodoc_inherit_docstrings)
         if not want_all:
             if not self.options.members:
                 return False, []  # type: ignore