Conform to PEP 257 summary line conventions

31 files changed, 86 insertions, 54 deletions

diff --git a/sphinx/builders/epub3.py b/sphinx/builders/epub3.py
index b413dce07..d172133ca 100644
--- a/sphinx/builders/epub3.py
+++ b/sphinx/builders/epub3.py
@@ -1,4 +1,5 @@
 """Build epub3 files.
+
 Originally derived from epub.py.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/domains/__init__.py b/sphinx/domains/__init__.py
index 9b3098e24..ef41a53fb 100644
--- a/sphinx/domains/__init__.py
+++ b/sphinx/domains/__init__.py
@@ -1,4 +1,6 @@
-"""Support for domains, which are groupings of description directives
+"""Support for domains.
+
+Domains are groupings of description directives
 and roles describing e.g. constructs of one programming language.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/errors.py b/sphinx/errors.py
index 30edd88a2..7ac997d3a 100644
--- a/sphinx/errors.py
+++ b/sphinx/errors.py
@@ -1,5 +1,4 @@
-"""Contains SphinxError and a few subclasses (in an extra module to avoid
-circular import problems).
+"""Contains SphinxError and a few subclasses.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
 :license: BSD, see LICENSE for details.
diff --git a/sphinx/ext/apidoc.py b/sphinx/ext/apidoc.py
index 6b93656f4..378eca221 100644
--- a/sphinx/ext/apidoc.py
+++ b/sphinx/ext/apidoc.py
@@ -1,4 +1,6 @@
-"""Parses a directory tree looking for Python modules and packages and creates
+"""Creates reST files corresponding to Python modules for code documentation.
+
+Parses a directory tree looking for Python modules and packages and creates
 ReST files appropriately to create code documentation with Sphinx.  It also
 creates a modules index (named modules.<suffix>).
 
diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py
index a66c76b45..0b794bbb9 100644
--- a/sphinx/ext/autodoc/__init__.py
+++ b/sphinx/ext/autodoc/__init__.py
@@ -1,4 +1,6 @@
-"""Automatically insert docstrings for functions, classes or whole modules into
+"""Extension to create automatic documentation from code docstrings.
+
+Automatically insert docstrings for functions, classes or whole modules into
 the doctree, thus avoiding duplication between docstrings and documentation
 for those who like elaborate docstrings.
 
diff --git a/sphinx/ext/autodoc/preserve_defaults.py b/sphinx/ext/autodoc/preserve_defaults.py
index fe71d088e..5526ada6d 100644
--- a/sphinx/ext/autodoc/preserve_defaults.py
+++ b/sphinx/ext/autodoc/preserve_defaults.py
@@ -1,4 +1,6 @@
-"""Preserve the default argument values of function signatures in source code
+"""Preserve function defaults.
+
+Preserve the default argument values of function signatures in source code
 and keep them not evaluated for readability.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py
index 69d5a89a4..5765300df 100644
--- a/sphinx/ext/autosummary/__init__.py
+++ b/sphinx/ext/autosummary/__init__.py
@@ -1,6 +1,7 @@
-"""Sphinx extension that adds an autosummary:: directive, which can be
-used to generate function/method/attribute/etc. summary lists, similar
-to those output eg. by Epydoc and other API doc generation tools.
+"""Extension that adds an autosummary:: directive.
+
+The directive can be used to generate function/method/attribute/etc. summary
+lists, similar to those output eg. by Epydoc and other API doc generation tools.
 
 An :autolink: role is also provided.
 
diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py
index 1912e3b08..092efd13b 100644
--- a/sphinx/ext/autosummary/generate.py
+++ b/sphinx/ext/autosummary/generate.py
@@ -1,4 +1,6 @@
-"""Usable as a library or script to generate automatic RST source files for
+"""Generates reST source files for autosummary.
+
+Usable as a library or script to generate automatic RST source files for
 items referred to in autosummary:: directives.
 
 Each generated RST file contains a single auto*:: directive which
diff --git a/sphinx/ext/coverage.py b/sphinx/ext/coverage.py
index a69bd6748..0cdbe80df 100644
--- a/sphinx/ext/coverage.py
+++ b/sphinx/ext/coverage.py
@@ -1,5 +1,7 @@
-"""Check Python modules and C API for coverage.  Mostly written by Josip
-Dzolonga for the Google Highly Open Participation contest.
+"""Check Python modules and C API for coverage.
+
+Mostly written by Josip Dzolonga for the Google Highly Open Participation
+contest.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
 :license: BSD, see LICENSE for details.
diff --git a/sphinx/ext/doctest.py b/sphinx/ext/doctest.py
index c1d3c5dd0..8a7b94a93 100644
--- a/sphinx/ext/doctest.py
+++ b/sphinx/ext/doctest.py
@@ -1,5 +1,6 @@
-"""Mimic doctest by automatically executing code snippets and checking
-their results.
+"""Mimic doctest in Sphinx.
+
+The extension automatically execute code snippets and checks their results.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
 :license: BSD, see LICENSE for details.
diff --git a/sphinx/ext/extlinks.py b/sphinx/ext/extlinks.py
index 74f0ea5ed..452c85034 100644
--- a/sphinx/ext/extlinks.py
+++ b/sphinx/ext/extlinks.py
@@ -1,5 +1,4 @@
-"""Extension to save typing and prevent hard-coding of base URLs in the reST
-files.
+"""Extension to save typing and prevent hard-coding of base URLs in reST files.
 
 This adds a new config value called ``extlinks`` that is created like this::
 
diff --git a/sphinx/ext/graphviz.py b/sphinx/ext/graphviz.py
index 189463d44..0cb85a2b9 100644
--- a/sphinx/ext/graphviz.py
+++ b/sphinx/ext/graphviz.py
@@ -1,5 +1,4 @@
-"""Allow graphviz-formatted graphs to be included in Sphinx-generated
-documents inline.
+"""Allow graphviz-formatted graphs to be included inline in generated documents.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
 :license: BSD, see LICENSE for details.
diff --git a/sphinx/ext/ifconfig.py b/sphinx/ext/ifconfig.py
index 244fa8187..0d97a1189 100644
--- a/sphinx/ext/ifconfig.py
+++ b/sphinx/ext/ifconfig.py
@@ -1,4 +1,6 @@
-"""Provides the ``ifconfig`` directive that allows to write documentation
+"""Provides the ``ifconfig`` directive.
+
+The ``ifconfig`` directive enables writing documentation
 that is included depending on configuration variables.
 
 Usage::
diff --git a/sphinx/ext/mathjax.py b/sphinx/ext/mathjax.py
index a411cd558..6b4a2db13 100644
--- a/sphinx/ext/mathjax.py
+++ b/sphinx/ext/mathjax.py
@@ -1,6 +1,8 @@
-"""Allow `MathJax <https://www.mathjax.org/>`_ to be used to display math in
-Sphinx's HTML writer -- requires the MathJax JavaScript library on your
-webserver/computer.
+"""Allow `MathJax`_ to be used to display math in Sphinx's HTML writer.
+
+This requires the MathJax JavaScript library on your webserver/computer.
+
+.. _MathJax: https://www.mathjax.org/
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
 :license: BSD, see LICENSE for details.
diff --git a/sphinx/ext/todo.py b/sphinx/ext/todo.py
index d4234c06b..3f27c6850 100644
--- a/sphinx/ext/todo.py
+++ b/sphinx/ext/todo.py
@@ -1,7 +1,8 @@
-"""Allow todos to be inserted into your documentation.  Inclusion of todos can
-be switched of by a configuration variable.  The todolist directive collects
-all todos of your project and lists them along with a backlink to the
-original location.
+"""Allow todos to be inserted into your documentation.
+
+Inclusion of todos can be switched of by a configuration variable.
+The todolist directive collects all todos of your project and lists them along
+with a backlink to the original location.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
 :license: BSD, see LICENSE for details.
diff --git a/sphinx/setup_command.py b/sphinx/setup_command.py
index 40254cce5..d69a96011 100644
--- a/sphinx/setup_command.py
+++ b/sphinx/setup_command.py
@@ -1,5 +1,4 @@
-"""Setuptools/distutils commands to assist the building of sphinx
-documentation.
+"""Setuptools/distutils commands to assist the building of sphinx documentation.
 
 :author: Sebastian Wiesner
 :contact: basti.wiesner@gmx.net
diff --git a/sphinx/util/docfields.py b/sphinx/util/docfields.py
index 81887126a..6617465da 100644
--- a/sphinx/util/docfields.py
+++ b/sphinx/util/docfields.py
@@ -1,4 +1,6 @@
-""""Doc fields" are reST field lists in object descriptions that will
+"""Utility code for "Doc fields".
+
+"Doc fields" are reST field lists in object descriptions that will
 be domain-specifically transformed to a more appealing presentation.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/util/jsdump.py b/sphinx/util/jsdump.py
index ae0075a66..0a685a0ea 100644
--- a/sphinx/util/jsdump.py
+++ b/sphinx/util/jsdump.py
@@ -1,4 +1,5 @@
 """This module implements a simple JavaScript serializer.
+
 Uses the basestring encode function from simplejson by Bob Ippolito.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
diff --git a/sphinx/util/smartypants.py b/sphinx/util/smartypants.py
index c1d9c4492..bc4171631 100644
--- a/sphinx/util/smartypants.py
+++ b/sphinx/util/smartypants.py
@@ -1,4 +1,6 @@
-"""This is extracted (with minor adaptations for flake8 compliance) from
+"""Deprecated backport of docutils.utils.smartquotes.
+
+This is extracted (with minor adaptations for flake8 compliance) from
 docutils’ docutils/utils/smartquotes.py as of revision 8097 (30 May 2017),
 in order to backport for Sphinx usage with Docutils < 0.14 extra language
 configurations and fixes. Replaces earlier smartypants version as used up
diff --git a/sphinx/versioning.py b/sphinx/versioning.py
index bba0b0ef4..b09590ffc 100644
--- a/sphinx/versioning.py
+++ b/sphinx/versioning.py
@@ -1,5 +1,4 @@
-"""Implements the low-level algorithms Sphinx uses for the versioning of
-doctrees.
+"""Implements the low-level algorithms Sphinx uses for versioning doctrees.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
 :license: BSD, see LICENSE for details.
diff --git a/tests/ext_napoleon_pep526_data_google.py b/tests/ext_napoleon_pep526_data_google.py
index 0a4676d89..e9a00b72c 100644
--- a/tests/ext_napoleon_pep526_data_google.py
+++ b/tests/ext_napoleon_pep526_data_google.py
@@ -1,5 +1,4 @@
-"""
-Test module for napoleon PEP 526 compatibility with google style
+"""Test module for napoleon PEP 526 compatibility with google style
 """
 
 module_level_var: int = 99
diff --git a/tests/ext_napoleon_pep526_data_numpy.py b/tests/ext_napoleon_pep526_data_numpy.py
index a421f53fe..6d31973f5 100644
--- a/tests/ext_napoleon_pep526_data_numpy.py
+++ b/tests/ext_napoleon_pep526_data_numpy.py
@@ -1,5 +1,4 @@
-"""
-Test module for napoleon PEP 526 compatibility with numpy style
+"""Test module for napoleon PEP 526 compatibility with numpy style
 """
 
 module_level_var: int = 99
diff --git a/tests/test_config.py b/tests/test_config.py
index 1e060e24c..48b941b94 100644
--- a/tests/test_config.py
+++ b/tests/test_config.py
@@ -1,5 +1,4 @@
-"""Test the sphinx.config.Config class and its handling in the
-Application class.
+"""Test the sphinx.config.Config class.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
 :license: BSD, see LICENSE for details.
diff --git a/tests/test_ext_autodoc.py b/tests/test_ext_autodoc.py
index 149d5c890..60eb3b925 100644
--- a/tests/test_ext_autodoc.py
+++ b/tests/test_ext_autodoc.py
@@ -1,5 +1,7 @@
-"""Test the autodoc extension.  This tests mainly the Documenters; the auto
-directives are tested in a test source file translated by test_build.
+"""Test the autodoc extension.
+
+This tests mainly the Documenters; the auto directives are tested in a test
+source file translated by test_build.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
 :license: BSD, see LICENSE for details.
diff --git a/tests/test_ext_autodoc_autoattribute.py b/tests/test_ext_autodoc_autoattribute.py
index 560aeed1c..692f06f6d 100644
--- a/tests/test_ext_autodoc_autoattribute.py
+++ b/tests/test_ext_autodoc_autoattribute.py
@@ -1,5 +1,7 @@
-"""Test the autodoc extension.  This tests mainly the Documenters; the auto
-directives are tested in a test source file translated by test_build.
+"""Test the autodoc extension.
+
+This tests mainly the Documenters; the auto directives are tested in a test
+source file translated by test_build.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
 :license: BSD, see LICENSE for details.
diff --git a/tests/test_ext_autodoc_autoclass.py b/tests/test_ext_autodoc_autoclass.py
index 0f1d8dba8..064f8136f 100644
--- a/tests/test_ext_autodoc_autoclass.py
+++ b/tests/test_ext_autodoc_autoclass.py
@@ -1,5 +1,7 @@
-"""Test the autodoc extension.  This tests mainly the Documenters; the auto
-directives are tested in a test source file translated by test_build.
+"""Test the autodoc extension.
+
+This tests mainly the Documenters; the auto directives are tested in a test
+source file translated by test_build.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
 :license: BSD, see LICENSE for details.
diff --git a/tests/test_ext_autodoc_autodata.py b/tests/test_ext_autodoc_autodata.py
index 7cbd78d4a..709797ff7 100644
--- a/tests/test_ext_autodoc_autodata.py
+++ b/tests/test_ext_autodoc_autodata.py
@@ -1,5 +1,7 @@
-"""Test the autodoc extension.  This tests mainly the Documenters; the auto
-directives are tested in a test source file translated by test_build.
+"""Test the autodoc extension.
+
+This tests mainly the Documenters; the auto directives are tested in a test
+source file translated by test_build.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
 :license: BSD, see LICENSE for details.
diff --git a/tests/test_ext_autodoc_autofunction.py b/tests/test_ext_autodoc_autofunction.py
index 61cc7c6db..60b8bf89c 100644
--- a/tests/test_ext_autodoc_autofunction.py
+++ b/tests/test_ext_autodoc_autofunction.py
@@ -1,5 +1,7 @@
-"""Test the autodoc extension.  This tests mainly the Documenters; the auto
-directives are tested in a test source file translated by test_build.
+"""Test the autodoc extension.
+
+This tests mainly the Documenters; the auto directives are tested in a test
+source file translated by test_build.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
 :license: BSD, see LICENSE for details.
diff --git a/tests/test_ext_autodoc_automodule.py b/tests/test_ext_autodoc_automodule.py
index 47bd41234..6333ba5c0 100644
--- a/tests/test_ext_autodoc_automodule.py
+++ b/tests/test_ext_autodoc_automodule.py
@@ -1,5 +1,7 @@
-"""Test the autodoc extension.  This tests mainly the Documenters; the auto
-directives are tested in a test source file translated by test_build.
+"""Test the autodoc extension.
+
+This tests mainly the Documenters; the auto directives are tested in a test
+source file translated by test_build.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
 :license: BSD, see LICENSE for details.
diff --git a/tests/test_ext_autodoc_autoproperty.py b/tests/test_ext_autodoc_autoproperty.py
index b3f7403ec..765ba30ac 100644
--- a/tests/test_ext_autodoc_autoproperty.py
+++ b/tests/test_ext_autodoc_autoproperty.py
@@ -1,5 +1,7 @@
-"""Test the autodoc extension.  This tests mainly the Documenters; the auto
-directives are tested in a test source file translated by test_build.
+"""Test the autodoc extension.
+
+This tests mainly the Documenters; the auto directives are tested in a test
+source file translated by test_build.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
 :license: BSD, see LICENSE for details.
diff --git a/tests/test_intl.py b/tests/test_intl.py
index 83410d555..b125a0d17 100644
--- a/tests/test_intl.py
+++ b/tests/test_intl.py
@@ -1,5 +1,6 @@
-"""Test message patching for internationalization purposes.  Runs the text
-builder in the test root.
+"""Test message patching for internationalization purposes.
+
+Runs the text builder in the test root.
 
 :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
 :license: BSD, see LICENSE for details.