Conform to PEP 257 summary line conventions

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.

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.

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.

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

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.
 

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.

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.
 

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

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.

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.

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

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.

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

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.

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.

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

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.

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.

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

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.

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.