IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Enable the entire D category in Ruff

Browse Source
This commit is contained in:
Adam Turner 2025-01-14 15:55:02 +00:00
parent dbf62cd503
commit c4daa95c09
96 changed files with 310 additions and 706 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
.ruff.toml
View File

@ -33,6 +33,18 @@ ignore = [
"COM812", # Trailing comma missing
# flake8-copyright
"CPY001", # Missing copyright notice at top of file
# pydocstyle ('D')
"D100", # Missing docstring in public module
"D101", # Missing docstring in public class
"D102", # Missing docstring in public method
"D103", # Missing docstring in public function
"D104", # Missing docstring in public package
"D105", # Missing docstring in magic method
"D107", # Missing docstring in `__init__`
"D200", # One-line docstring should fit on one line
"D205", # 1 blank line required between summary line and description
"D400", # First line should end with a period
"D401", # First line of docstring should be in imperative mood: "{first_line}"
# pycodestyle
"E741", # Ambiguous variable name: `{name}`
# eradicate
@ -152,51 +164,11 @@ select = [
# flake8-copyright ('CPY')
"CPY",
# pydocstyle ('D')
# "D100", # Missing docstring in public module
# "D101", # Missing docstring in public class
# "D102", # Missing docstring in public method
# "D103", # Missing docstring in public function
# "D104", # Missing docstring in public package
# "D105", # Missing docstring in magic method
"D106", # Missing docstring in public nested class
# "D107", # Missing docstring in `__init__`
# "D200", # One-line docstring should fit on one line
"D201", # No blank lines allowed before function docstring (found {num_lines})
"D202", # No blank lines allowed after function docstring (found {num_lines})
"D204", # 1 blank line required after class docstring
# "D205", # 1 blank line required between summary line and description
"D206", # Docstring should be indented with spaces, not tabs
"D207", # Docstring is under-indented
"D208", # Docstring is over-indented
"D209", # Multi-line docstring closing quotes should be on a separate line
"D210", # No whitespaces allowed surrounding docstring text
"D211", # No blank lines allowed before class docstring
# "D212", # Multi-line docstring summary should start at the first line
# "D213", # Multi-line docstring summary should start at the second line
# "D214", # Section is over-indented ("{name}")
# "D215", # Section underline is over-indented ("{name}")
"D300", # Use triple double quotes `"""`
"D301", # Use `r"""` if any backslashes in a docstring
# "D400", # First line should end with a period
# "D401", # First line of docstring should be in imperative mood: "{first_line}"
"D402", # First line should not be the function's signature
"D403", # First word of the first line should be capitalized: `{}` -> `{}`
# "D404", # First word of the docstring should not be "This"
"D405", # Section name should be properly capitalized ("{name}")
# "D406", # Section name should end with a newline ("{name}")
# "D407", # Missing dashed underline after section ("{name}")
"D408", # Section underline should be in the line following the section's name ("{name}")
"D409", # Section underline should match the length of its name ("{name}")
"D410", # Missing blank line after section ("{name}")
"D411", # Missing blank line before section ("{name}")
# "D412", # No blank lines allowed between a section header and its content ("{name}")
# "D413", # Missing blank line after last section ("{name}")
"D414", # Section has no content ("{name}")
# "D415", # First line should end with a period, question mark, or exclamation point
"D416", # Section name should end with a colon ("{name}")
"D",
"D212", # Multi-line docstring summary should start at the first line
# "D404", # First word of the docstring should not be "This"
# "D415", # First line should end with a period, question mark, or exclamation point
"D417", # Missing argument description in the docstring for `{definition}`: `{name}`
"D418", # Function decorated with `@overload` shouldn't contain a docstring
"D419", # Docstring is empty
# flake8-django ('DJ')
# Django is not used in Sphinx
# flake8-datetimez ('DTZ')
@ -294,6 +266,7 @@ select = [
# flake8-2020 ('YTT')
"YTT",
]
logger-objects = [
"sphinx.ext.apidoc._shared.LOGGER",
"sphinx.ext.intersphinx._shared.LOGGER",
@ -412,3 +385,8 @@ forced-separate = [
required-imports = [
"from __future__ import annotations",
]
[lint.pydocstyle]
convention = "pep257"
ignore-decorators = ["typing.overload"]
ignore-var-parameters = true

3
sphinx/application.py
View File

@ -1803,8 +1803,7 @@ class Sphinx:
class TemplateBridge:
"""
This class defines the interface for a "template bridge", that is, a class
"""This class defines the interface for a "template bridge", that is, a class
that renders templates given a template name and a context.
"""

7
sphinx/builders/__init__.py
View File

@ -66,9 +66,7 @@ logger = logging.getLogger(__name__)
class Builder:
"""
Builds target formats from the reST sources.
"""
"""Builds target formats from the reST sources."""
#: The builder's name.
#: This is the value used to select builders on the command line.
@ -812,8 +810,7 @@ class Builder:
pass
def write_doc(self, docname: str, doctree: nodes.document) -> None:
"""
Write the output file for the document
"""Write the output file for the document
:param docname: the :term:`docname <document name>`.
:param doctree: defines the content to be written.

3
sphinx/builders/_epub_base.py
View File

@ -126,8 +126,7 @@ ssp = sphinx_smarty_pants
class EpubBuilder(StandaloneHTMLBuilder):
"""
Builder that outputs epub files.
"""Builder that outputs epub files.
It creates the metainfo files container.opf, toc.ncx, mimetype, and
META-INF/container.xml. Afterwards, all necessary files are zipped to an

4
sphinx/builders/changes.py
View File

@ -25,9 +25,7 @@ logger = logging.getLogger(__name__)
class ChangesBuilder(Builder):
"""
Write a summary with all versionadded/changed/deprecated/removed directives.
"""
"""Write a summary with all versionadded/changed/deprecated/removed directives."""
name = 'changes'
epilog = __('The overview file is in %(outdir)s.')

3
sphinx/builders/dirhtml.py
View File

@ -17,8 +17,7 @@ logger = logging.getLogger(__name__)
class DirectoryHTMLBuilder(StandaloneHTMLBuilder):
"""
A StandaloneHTMLBuilder that creates all HTML pages as "index.html" in
"""A StandaloneHTMLBuilder that creates all HTML pages as "index.html" in
a directory given by their pagename, so that generated URLs don't have
``.html`` in them.
"""

3
sphinx/builders/epub3.py
View File

@ -73,8 +73,7 @@ _XML_NAME_PATTERN = re.compile(f'({_xml_name_start_char})({_xml_name_char})*')
class Epub3Builder(_epub_base.EpubBuilder):
"""
Builder that outputs epub3 files.
"""Builder that outputs epub3 files.
It creates the metainfo files content.opf, nav.xhtml, toc.ncx, mimetype,
and META-INF/container.xml. Afterwards, all necessary files are zipped to

12
sphinx/builders/gettext.py
View File

@ -98,9 +98,7 @@ class Catalog:
class MsgOrigin:
"""
Origin holder for Catalog message origin.
"""
"""Origin holder for Catalog message origin."""
__slots__ = 'source', 'line', 'uid'
@ -158,9 +156,7 @@ class I18nTags(Tags):
class I18nBuilder(Builder):
"""
General i18n builder.
"""
"""General i18n builder."""
name = 'i18n'
versioning_method = 'text'
@ -242,9 +238,7 @@ def _is_node_in_substitution_definition(node: nodes.Node) -> bool:
class MessageCatalogBuilder(I18nBuilder):
"""
Builds gettext-style message catalogs (.pot files).
"""
"""Builds gettext-style message catalogs (.pot files)."""
name = 'gettext'
epilog = __('The message catalogs are in %(outdir)s.')

4
sphinx/builders/html/__init__.py
View File

@ -105,9 +105,7 @@ def convert_locale_to_language_tag(locale: str | None) -> str | None:
class StandaloneHTMLBuilder(Builder):
"""
Builds standalone HTML docs.
"""
"""Builds standalone HTML docs."""
name = 'html'
format = 'html'

4
sphinx/builders/latex/__init__.py
View File

@ -111,9 +111,7 @@ logger = logging.getLogger(__name__)
class LaTeXBuilder(Builder):
"""
Builds LaTeX output to create PDF.
"""
"""Builds LaTeX output to create PDF."""
name = 'latex'
format = 'latex'

4
sphinx/builders/linkcheck.py
View File

@ -72,9 +72,7 @@ DEFAULT_DELAY = 60.0
class CheckExternalLinksBuilder(DummyBuilder):
"""
Checks for broken external links.
"""
"""Checks for broken external links."""
name = 'linkcheck'
epilog = __('Look for any errors in the above output or in %(outdir)s/output.txt')

4
sphinx/builders/manpage.py
View File

@ -31,9 +31,7 @@ logger = logging.getLogger(__name__)
class ManualPageBuilder(Builder):
"""
Builds groff output in manual page format.
"""
"""Builds groff output in manual page format."""
name = 'man'
format = 'man'

5
sphinx/builders/singlehtml.py
View File

@ -29,10 +29,7 @@ logger = logging.getLogger(__name__)
class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
"""
A StandaloneHTMLBuilder subclass that puts the whole document tree on one
HTML page.
"""
"""Builds the whole document tree as a single HTML page."""
name = 'singlehtml'
epilog = __('The HTML page is in %(outdir)s.')

4
sphinx/builders/texinfo.py
View File

@ -39,9 +39,7 @@ template_dir = os.path.join(package_dir, 'templates', 'texinfo')
class TexinfoBuilder(Builder):
"""
Builds Texinfo output to create Info documentation.
"""
"""Builds Texinfo output to create Info documentation."""
name = 'texinfo'
format = 'texinfo'

8
sphinx/builders/xml.py
View File

@ -29,9 +29,7 @@ logger = logging.getLogger(__name__)
class XMLBuilder(Builder):
"""
Builds Docutils-native XML.
"""
"""Builds Docutils-native XML."""
name = 'xml'
format = 'xml'
@ -101,9 +99,7 @@ class XMLBuilder(Builder):
class PseudoXMLBuilder(XMLBuilder):
"""
Builds pseudo-XML for display purposes.
"""
"""Builds pseudo-XML for display purposes."""
name = 'pseudoxml'
format = 'pseudoxml'

8
sphinx/cmd/build.py
View File

@ -50,10 +50,10 @@ def handle_exception(
def jobs_argument(value: str) -> int:
"""
Special type to handle 'auto' flags passed to 'sphinx-build' via -j flag. Can
be expanded to handle other special scaling requests, such as setting job count
to cpu_count.
"""Parse the ``--jobs`` flag.
Return the number of CPUs if 'auto' is used,
otherwise ensure *value* is a positive integer.
"""
if value == 'auto':
return multiprocessing.cpu_count()

63
sphinx/directives/__init__.py
View File

@ -30,9 +30,7 @@ strip_backslash_re = re.compile(r'\\(.)')
def optional_int(argument: str) -> int | None:
"""
Check for an integer argument or None value; raise ``ValueError`` if not.
"""
"""Check for an integer argument or None value; raise ``ValueError`` if not."""
if argument is None:
return None
else:
@ -47,10 +45,10 @@ ObjDescT = TypeVar('ObjDescT')
class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
"""
Directive to describe a class, function or similar object. Not used
directly, but subclassed (in domain-specific directives) to add custom
behavior.
"""Directive to describe a class, function or similar object.
Not used directly, but subclassed (in domain-specific directives)
to add custom behaviour.
"""
has_content = True
@ -91,9 +89,9 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
return self._doc_field_type_map
def get_signatures(self) -> list[str]:
"""
Retrieve the signatures to document from the directive arguments. By
default, signatures are given as arguments, one per line.
"""Retrieve the signatures to document from the directive arguments.
By default, signatures are given as arguments, one per line.
"""
lines = nl_escape_re.sub('', self.arguments[0]).split('\n')
if self.config.strip_signature_backslash:
@ -103,9 +101,10 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
return [line.strip() for line in lines]
def handle_signature(self, sig: str, signode: desc_signature) -> ObjDescT:
"""
Parse the signature *sig* into individual nodes and append them to
*signode*. If ValueError is raised, parsing is aborted and the whole
"""Parse the signature *sig*.
The individual nodes are then appended to *signode*.
If ValueError is raised, parsing is aborted and the whole
*sig* is put into a single desc_name node.
The return value should be a value that identifies the object. It is
@ -117,39 +116,39 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
def add_target_and_index(
self, name: ObjDescT, sig: str, signode: desc_signature
) -> None:
"""
Add cross-reference IDs and entries to self.indexnode, if applicable.
"""Add cross-reference IDs and entries to self.indexnode, if applicable.
*name* is whatever :meth:`handle_signature()` returned.
"""
pass # do nothing by default
def before_content(self) -> None:
"""
Called before parsing content. Used to set information about the current
directive context on the build environment.
"""Called before parsing content.
Used to set information about the current directive context
on the build environment.
"""
pass
def transform_content(self, content_node: addnodes.desc_content) -> None:
"""
"""Can be used to manipulate the content.
Called after creating the content through nested parsing,
but before the ``object-description-transform`` event is emitted,
and before the info-fields are transformed.
Can be used to manipulate the content.
"""
pass
def after_content(self) -> None:
"""
Called after parsing content. Used to reset information about the
current directive context on the build environment.
"""Called after parsing content.
Used to reset information about the current directive context
on the build environment.
"""
pass
def _object_hierarchy_parts(self, sig_node: desc_signature) -> tuple[str, ...]:
"""
Returns a tuple of strings, one entry for each part of the object's
"""Returns a tuple of strings, one entry for each part of the object's
hierarchy (e.g. ``('module', 'submodule', 'Class', 'method')``). The
returned tuple is used to properly nest children within parents in the
table of contents, and can also be used within the
@ -160,8 +159,7 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
return ()
def _toc_entry_name(self, sig_node: desc_signature) -> str:
"""
Returns the text of the table of contents entry for the object.
"""Returns the text of the table of contents entry for the object.
This function is called once, in :py:meth:`run`, to set the name for the
table of contents entry (a special attribute ``_toc_name`` is set on the
@ -186,8 +184,7 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
return ''
def run(self) -> list[Node]:
"""
Main directive entry function, called by docutils upon encountering the
"""Main directive entry function, called by docutils upon encountering the
directive.
This directive is meant to be quite easily subclassable, so it delegates
@ -321,9 +318,7 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
class DefaultRole(SphinxDirective):
"""
Set the default interpreted text role. Overridden from docutils.
"""
"""Set the default interpreted text role. Overridden from docutils."""
optional_arguments = 1
final_argument_whitespace = False
@ -353,9 +348,7 @@ class DefaultRole(SphinxDirective):
class DefaultDomain(SphinxDirective):
"""
Directive to (re-)set the default domain for this source file.
"""
"""Directive to (re-)set the default domain for this source file."""
has_content = False
required_arguments = 1

9
sphinx/directives/code.py
View File

@ -30,8 +30,7 @@ logger = logging.getLogger(__name__)
class Highlight(SphinxDirective):
"""
Directive to set the highlighting language for code blocks, as well
"""Directive to set the highlighting language for code blocks, as well
as the threshold for line numbers.
"""
@ -98,8 +97,7 @@ def container_wrapper(
class CodeBlock(SphinxDirective):
"""
Directive for a code block with special highlighting or line numbering
"""Directive for a code block with special highlighting or line numbering
settings.
"""
@ -411,8 +409,7 @@ class LiteralIncludeReader:
class LiteralInclude(SphinxDirective):
"""
Like ``.. include:: :literal:``, but only warns if the include file is
"""Like ``.. include:: :literal:``, but only warns if the include file is
not found, and does not raise errors. Also has several options for
selecting what to include.
"""

37
sphinx/directives/other.py
View File

@ -41,8 +41,7 @@ def int_or_nothing(argument: str) -> int:
class TocTree(SphinxDirective):
"""
Directive to notify Sphinx about the hierarchical structure of the docs,
"""Directive to notify Sphinx about the hierarchical structure of the docs,
and to include a table-of-contents like tree in the current document.
"""
@ -89,9 +88,7 @@ class TocTree(SphinxDirective):
return [wrappernode]
def parse_content(self, toctree: addnodes.toctree) -> None:
"""
Populate ``toctree['entries']`` and ``toctree['includefiles']`` from content.
"""
"""Populate ``toctree['entries']`` and ``toctree['includefiles']`` from content."""
generated_docnames = frozenset(StandardDomain._virtual_doc_names)
suffixes = self.config.source_suffix
current_docname = self.env.docname
@ -184,8 +181,7 @@ class TocTree(SphinxDirective):
class Author(SphinxDirective):
"""
Directive to give the name of the author of the current document
"""Directive to give the name of the author of the current document
or section. Shown in the output only if the show_authors option is on.
"""
@ -219,17 +215,13 @@ class Author(SphinxDirective):
class SeeAlso(BaseAdmonition):
"""
An admonition mentioning things to look at as reference.
"""
"""An admonition mentioning things to look at as reference."""
node_class = addnodes.seealso
class TabularColumns(SphinxDirective):
"""
Directive to give an explicit tabulary column definition to LaTeX.
"""
"""Directive to give an explicit tabulary column definition to LaTeX."""
has_content = False
required_arguments = 1
@ -245,9 +237,7 @@ class TabularColumns(SphinxDirective):
class Centered(SphinxDirective):
"""
Directive to create a centered line of bold text.
"""
"""Directive to create a centered line of bold text."""
has_content = False
required_arguments = 1
@ -268,9 +258,7 @@ class Centered(SphinxDirective):
class Acks(SphinxDirective):
"""
Directive for a list of names.
"""
"""Directive for a list of names."""
has_content = True
required_arguments = 0
@ -290,9 +278,7 @@ class Acks(SphinxDirective):
class HList(SphinxDirective):
"""
Directive for a list that gets compacted horizontally.
"""
"""Directive for a list that gets compacted horizontally."""
has_content = True
required_arguments = 0
@ -327,9 +313,7 @@ class HList(SphinxDirective):
class Only(SphinxDirective):
"""
Directive to only include text if the given tag(s) are enabled.
"""
"""Directive to only include text if the given tag(s) are enabled."""
has_content = True
required_arguments = 1
@ -389,8 +373,7 @@ class Only(SphinxDirective):
class Include(BaseInclude, SphinxDirective):
"""
Like the standard "Include" directive, but interprets absolute paths
"""Like the standard "Include" directive, but interprets absolute paths
"correctly", i.e. relative to source directory.
"""

6
sphinx/domains/__init__.py
View File

@ -36,8 +36,7 @@ __all__ = (
class ObjType:
"""
An ObjType is the description for a type of object that a domain can
"""An ObjType is the description for a type of object that a domain can
document. In the object_types attribute of Domain subclasses, object type
names are mapped to instances of this class.
@ -61,8 +60,7 @@ class ObjType:
class Domain:
"""
A Domain is meant to be a group of "object" description directives for
"""A Domain is meant to be a group of "object" description directives for
objects of a similar nature, and corresponding roles to create references to
them. Examples would be Python modules, classes, functions etc., elements
of a templating language, Sphinx roles and directives, etc.

6
sphinx/domains/_index.py
View File

@ -14,8 +14,7 @@ if TYPE_CHECKING:
class IndexEntry(NamedTuple):
"""
An index entry.
"""An index entry.
.. note::
@ -53,8 +52,7 @@ class IndexEntry(NamedTuple):
class Index(ABC):
"""
An Index is the description for a domain-specific index. To add an index to
"""An Index is the description for a domain-specific index. To add an index to
a domain, subclass Index, overriding the three name attributes:
* `name` is an identifier used for generating file names.

10
sphinx/domains/c/__init__.py
View File

@ -106,9 +106,7 @@ def _make_phony_error_name() -> ASTNestedName:
class CObject(ObjectDescription[ASTDeclaration]):
"""
Description of a C language object.
"""
"""Description of a C language object."""
option_spec: ClassVar[OptionSpec] = {
'no-index-entry': directives.flag,
@ -383,8 +381,7 @@ class CTypeObject(CObject):
class CNamespaceObject(SphinxDirective):
"""
This directive is just to tell Sphinx that we're documenting stuff in
"""This directive is just to tell Sphinx that we're documenting stuff in
namespace foo.
"""
@ -639,8 +636,7 @@ class CAliasObject(ObjectDescription):
}
def run(self) -> list[Node]:
"""
On purpose this doesn't call the ObjectDescription version, but is based on it.
"""On purpose this doesn't call the ObjectDescription version, but is based on it.
Each alias signature may expand into multiple real signatures if 'noroot'.
The code is therefore based on the ObjectDescription version.
"""

3
sphinx/domains/c/_parser.py
View File

@ -901,8 +901,7 @@ class DefinitionParser(BaseParser):
return ASTInitializer(value)
def _parse_type(self, named: bool | str, outer: str | None = None) -> ASTType:
"""
named=False|'single'|True: 'single' is e.g., for function objects which
"""named=False|'single'|True: 'single' is e.g., for function objects which
doesn't need to name the arguments, but otherwise is a single name
"""
if outer: # always named

4
sphinx/domains/changeset.py
View File

@ -47,9 +47,7 @@ class ChangeSet(NamedTuple):
class VersionChange(SphinxDirective):
"""
Directive to describe a change/addition/deprecation in a specific version.
"""
"""Directive to describe a change/addition/deprecation in a specific version."""
has_content = True
required_arguments = 1

3
sphinx/domains/citation.py
View File

@ -148,8 +148,7 @@ class CitationDefinitionTransform(SphinxTransform):
class CitationReferenceTransform(SphinxTransform):
"""
Replace citation references by pending_xref nodes before the default
"""Replace citation references by pending_xref nodes before the default
docutils transform tries to resolve them.
"""

6
sphinx/domains/cpp/__init__.py
View File

@ -528,8 +528,7 @@ class CPPEnumeratorObject(CPPObject):
class CPPNamespaceObject(SphinxDirective):
"""
This directive is just to tell Sphinx that we're documenting stuff in
"""This directive is just to tell Sphinx that we're documenting stuff in
namespace foo.
"""
@ -807,8 +806,7 @@ class CPPAliasObject(ObjectDescription):
}
def run(self) -> list[Node]:
"""
On purpose this doesn't call the ObjectDescription version, but is based on it.
"""On purpose this doesn't call the ObjectDescription version, but is based on it.
Each alias signature may expand into multiple real signatures (an overload set).
The code is therefore based on the ObjectDescription version.
"""

3
sphinx/domains/cpp/_ids.py
View File

@ -1,5 +1,4 @@
"""
Important note on ids
"""Important note on ids
----------------------------------------------------------------------------
Multiple id generation schemes are used due to backwards compatibility.

3
sphinx/domains/cpp/_parser.py
View File

@ -1624,8 +1624,7 @@ class DefinitionParser(BaseParser):
return ASTInitializer(value)
def _parse_type(self, named: bool | str, outer: str | None = None) -> ASTType:
"""
named=False|'maybe'|True: 'maybe' is e.g., for function objects which
"""named=False|'maybe'|True: 'maybe' is e.g., for function objects which
doesn't need to name the arguments
outer == operatorCast: annoying case, we should not take the params

4
sphinx/domains/index.py
View File

@ -62,9 +62,7 @@ class IndexDomain(Domain):
class IndexDirective(SphinxDirective):
"""
Directive to add entries to the index.
"""
"""Directive to add entries to the index."""
has_content = False
required_arguments = 1

7
sphinx/domains/javascript.py
View File

@ -35,9 +35,7 @@ logger = logging.getLogger(__name__)
class JSObject(ObjectDescription[tuple[str, str]]):
"""
Description of a JavaScript object.
"""
"""Description of a JavaScript object."""
#: If set to ``True`` this object is callable and a `desc_parameterlist` is
#: added
@ -303,8 +301,7 @@ class JSConstructor(JSCallable):
class JSModule(SphinxDirective):
"""
Directive to mark description of a new JavaScript module.
"""Directive to mark description of a new JavaScript module.
This directive specifies the module name that will be used by objects that
follow this directive.

15
sphinx/domains/python/__init__.py
View File

@ -182,9 +182,7 @@ class PyVariable(PyObject):
class PyClasslike(PyObject):
"""
Description of a class-like object (classes, interfaces, exceptions).
"""
"""Description of a class-like object (classes, interfaces, exceptions)."""
option_spec: ClassVar[OptionSpec] = PyObject.option_spec.copy()
option_spec.update({
@ -471,9 +469,7 @@ class PyTypeAlias(PyObject):
class PyModule(SphinxDirective):
"""
Directive to mark description of a new module.
"""
"""Directive to mark description of a new module."""
has_content = True
required_arguments = 1
@ -533,8 +529,7 @@ class PyModule(SphinxDirective):
class PyCurrentModule(SphinxDirective):
"""
This directive is just to tell Sphinx that we're documenting
"""This directive is just to tell Sphinx that we're documenting
stuff in module foo, but links to module foo won't lead here.
"""
@ -600,9 +595,7 @@ def filter_meta_fields(
class PythonModuleIndex(Index):
"""
Index subclass to provide the Python module index.
"""
"""Index subclass to provide the Python module index."""
name = 'modindex'
localname = _('Python Module Index')

3
sphinx/domains/python/_object.py
View File

@ -162,8 +162,7 @@ class PyTypedField(PyXrefMixin, TypedField):
class PyObject(ObjectDescription[tuple[str, str]]):
"""
Description of a general Python object.
"""Description of a general Python object.
:cvar allow_nesting: Class is an object that allows for nested namespaces
:vartype allow_nesting: bool

16
sphinx/domains/rst.py
View File

@ -34,9 +34,7 @@ dir_sig_re = re.compile(r'\.\. (.+?)::(.*)$')
class ReSTMarkup(ObjectDescription[str]):
"""
Description of generic reST markup.
"""
"""Description of generic reST markup."""
option_spec: ClassVar[OptionSpec] = {
'no-index': directives.flag,
@ -119,9 +117,7 @@ def parse_directive(d: str) -> tuple[str, str]:
class ReSTDirective(ReSTMarkup):
"""
Description of a reST directive.
"""
"""Description of a reST directive."""
def handle_signature(self, sig: str, signode: desc_signature) -> str:
name, args = parse_directive(sig)
@ -147,9 +143,7 @@ class ReSTDirective(ReSTMarkup):
class ReSTDirectiveOption(ReSTMarkup):
"""
Description of an option for reST directive.
"""
"""Description of an option for reST directive."""
option_spec: ClassVar[OptionSpec] = ReSTMarkup.option_spec.copy()
option_spec.update({
@ -219,9 +213,7 @@ class ReSTDirectiveOption(ReSTMarkup):
class ReSTRole(ReSTMarkup):
"""
Description of a reST role.
"""
"""Description of a reST role."""
def handle_signature(self, sig: str, signode: desc_signature) -> str:
desc_name = f':{sig}:'

30
sphinx/domains/std/__init__.py
View File

@ -50,9 +50,7 @@ samp_role = EmphasizedLiteral()
class GenericObject(ObjectDescription[str]):
"""
A generic x-ref directive registered with Sphinx.add_object_type().
"""
"""A generic x-ref directive registered with Sphinx.add_object_type()."""
indextemplate: str = ''
parse_node: Callable[[BuildEnvironment, str, desc_signature], str] | None = None
@ -93,9 +91,7 @@ class EnvVar(GenericObject):
class EnvVarXRefRole(XRefRole):
"""
Cross-referencing role for environment variables (adds an index entry).
"""
"""Cross-referencing role for environment variables (adds an index entry)."""
def result_nodes(
self,
@ -192,9 +188,7 @@ class ConfigurationValue(ObjectDescription[str]):
class Target(SphinxDirective):
"""
Generic target for user-defined cross-reference types.
"""
"""Generic target for user-defined cross-reference types."""
indextemplate = ''
@ -232,9 +226,7 @@ class Target(SphinxDirective):
class Cmdoption(ObjectDescription[str]):
"""
Description of a command-line option (.. option).
"""
"""Description of a command-line option (.. option)."""
def handle_signature(self, sig: str, signode: desc_signature) -> str:
"""Transform an option description into RST nodes."""
@ -338,9 +330,7 @@ class Cmdoption(ObjectDescription[str]):
class Program(SphinxDirective):
"""
Directive to name the program for which options are documented.
"""
"""Directive to name the program for which options are documented."""
has_content = False
required_arguments = 1
@ -417,8 +407,7 @@ def make_glossary_term(
class Glossary(SphinxDirective):
"""
Directive to create a glossary with cross-reference targets for :term:
"""Directive to create a glossary with cross-reference targets for :term:
roles.
"""
@ -599,9 +588,7 @@ def token_xrefs(text: str, *, production_group: str = '') -> list[Node]:
class ProductionList(SphinxDirective):
"""
Directive to list grammar productions.
"""
"""Directive to list grammar productions."""
has_content = False
required_arguments = 1
@ -666,8 +653,7 @@ class TokenXRefRole(XRefRole):
class StandardDomain(Domain):
"""
Domain for all objects that don't fit into another domain or are added
"""Domain for all objects that don't fit into another domain or are added
via the application interface.
"""

3
sphinx/environment/__init__.py
View File

@ -94,8 +94,7 @@ versioning_conditions: dict[str, Literal[False] | Callable[[Node], bool]] = {
class BuildEnvironment:
"""
The environment in which the ReST files are translated.
"""The environment in which the ReST files are translated.
Stores an inventory of cross-file targets and provides doctree
transformations to resolve links to them.
"""

3
sphinx/ext/apidoc/_generate.py
View File

@ -276,8 +276,7 @@ def recurse_tree(
opts: ApidocOptions,
user_template_dir: str | None = None,
) -> tuple[list[Path], list[str]]:
"""
Look for every file in the directory tree and create the corresponding
"""Look for every file in the directory tree and create the corresponding
ReST files.
"""
# check if the base directory is a package and get its name

74
sphinx/ext/autodoc/__init__.py
View File

@ -337,8 +337,7 @@ class ObjectMember:
class Documenter:
"""
A Documenter knows how to autodocument a single object type. When
"""A Documenter knows how to autodocument a single object type. When
registered with the AutoDirective, it will be used to document objects
of that type when needed by autodoc.
@ -1075,9 +1074,7 @@ class Documenter:
class ModuleDocumenter(Documenter):
"""
Specialized Documenter subclass for modules.
"""
"""Specialized Documenter subclass for modules."""
objtype = 'module'
content_indent = ''
@ -1264,8 +1261,7 @@ class ModuleDocumenter(Documenter):
class ModuleLevelDocumenter(Documenter):
"""
Specialized Documenter subclass for objects on module level (functions,
"""Specialized Documenter subclass for objects on module level (functions,
classes, data/constants).
"""
@ -1289,8 +1285,7 @@ class ModuleLevelDocumenter(Documenter):
class ClassLevelDocumenter(Documenter):
"""
Specialized Documenter subclass for objects on class level (methods,
"""Specialized Documenter subclass for objects on class level (methods,
attributes).
"""
@ -1325,8 +1320,7 @@ class ClassLevelDocumenter(Documenter):
class DocstringSignatureMixin:
"""
Mixin for FunctionDocumenter and MethodDocumenter to provide the
"""Mixin for FunctionDocumenter and MethodDocumenter to provide the
feature of reading the signature from the docstring.
"""
@ -1407,8 +1401,7 @@ class DocstringSignatureMixin:
class DocstringStripSignatureMixin(DocstringSignatureMixin):
"""
Mixin for AttributeDocumenter to provide the
"""Mixin for AttributeDocumenter to provide the
feature of stripping any function signature from the docstring.
"""
@ -1426,9 +1419,7 @@ class DocstringStripSignatureMixin(DocstringSignatureMixin):
class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type: ignore[misc]
"""
Specialized Documenter subclass for functions.
"""
"""Specialized Documenter subclass for functions."""
objtype = 'function'
member_order = 30
@ -1568,9 +1559,7 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # typ
class DecoratorDocumenter(FunctionDocumenter):
"""
Specialized Documenter subclass for decorator functions.
"""
"""Specialized Documenter subclass for decorator functions."""
objtype = 'decorator'
@ -1600,9 +1589,7 @@ _CLASS_NEW_BLACKLIST = frozenset({
class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type: ignore[misc]
"""
Specialized Documenter subclass for classes.
"""
"""Specialized Documenter subclass for classes."""
objtype = 'class'
member_order = 20
@ -2098,9 +2085,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter): # type:
class ExceptionDocumenter(ClassDocumenter):
"""
Specialized ClassDocumenter subclass for exceptions.
"""
"""Specialized ClassDocumenter subclass for exceptions."""
objtype = 'exception'
member_order = 10
@ -2148,8 +2133,7 @@ class DataDocumenterMixinBase:
class GenericAliasMixin(DataDocumenterMixinBase):
"""
Mixin for DataDocumenter and AttributeDocumenter to provide the feature for
"""Mixin for DataDocumenter and AttributeDocumenter to provide the feature for
supporting GenericAliases.
"""
@ -2173,8 +2157,7 @@ class GenericAliasMixin(DataDocumenterMixinBase):
class UninitializedGlobalVariableMixin(DataDocumenterMixinBase):
"""
Mixin for DataDocumenter to provide the feature for supporting uninitialized
"""Mixin for DataDocumenter to provide the feature for supporting uninitialized
(type annotation only) global variables.
"""
@ -2220,9 +2203,7 @@ class UninitializedGlobalVariableMixin(DataDocumenterMixinBase):
class DataDocumenter(
GenericAliasMixin, UninitializedGlobalVariableMixin, ModuleLevelDocumenter
):
"""
Specialized Documenter subclass for data items.
"""
"""Specialized Documenter subclass for data items."""
objtype = 'data'
member_order = 40
@ -2355,9 +2336,7 @@ class DataDocumenter(
class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type: ignore[misc]
"""
Specialized Documenter subclass for methods (normal, static and class).
"""
"""Specialized Documenter subclass for methods (normal, static and class)."""
objtype = 'method'
directivetype = 'method'
@ -2616,8 +2595,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter): # type:
class NonDataDescriptorMixin(DataDocumenterMixinBase):
"""
Mixin for AttributeDocumenter to provide the feature for supporting non
"""Mixin for AttributeDocumenter to provide the feature for supporting non
data-descriptors.
.. note:: This mix-in must be inherited after other mix-ins. Otherwise, docstring
@ -2649,9 +2627,7 @@ class NonDataDescriptorMixin(DataDocumenterMixinBase):
class SlotsMixin(DataDocumenterMixinBase):
"""
Mixin for AttributeDocumenter to provide the feature for supporting __slots__.
"""
"""Mixin for AttributeDocumenter to provide the feature for supporting __slots__."""
def isslotsattribute(self) -> bool:
"""Check the subject is an attribute in __slots__."""
@ -2699,11 +2675,10 @@ class SlotsMixin(DataDocumenterMixinBase):
class RuntimeInstanceAttributeMixin(DataDocumenterMixinBase):
"""
Mixin for AttributeDocumenter to provide the feature for supporting runtime
"""Mixin for AttributeDocumenter to provide the feature for supporting runtime
instance attributes (that are defined in __init__() methods with doc-comments).
Example:
Example::
class Foo:
def __init__(self):
@ -2783,11 +2758,10 @@ class RuntimeInstanceAttributeMixin(DataDocumenterMixinBase):
class UninitializedInstanceAttributeMixin(DataDocumenterMixinBase):
"""
Mixin for AttributeDocumenter to provide the feature for supporting uninitialized
"""Mixin for AttributeDocumenter to provide the feature for supporting uninitialized
instance attributes (PEP-526 styled, annotation only attributes).
Example:
Example::
class Foo:
attr: int #: This is a target of this mix-in.
@ -2848,9 +2822,7 @@ class AttributeDocumenter( # type: ignore[misc]
DocstringStripSignatureMixin,
ClassLevelDocumenter,
):
"""
Specialized Documenter subclass for attributes.
"""
"""Specialized Documenter subclass for attributes."""
objtype = 'attribute'
member_order = 60
@ -3020,9 +2992,7 @@ class AttributeDocumenter( # type: ignore[misc]
class PropertyDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter): # type: ignore[misc]
"""
Specialized Documenter subclass for properties.
"""
"""Specialized Documenter subclass for properties."""
objtype = 'property'
member_order = 60

4
sphinx/ext/autodoc/importer.py
View File

@ -161,9 +161,7 @@ def import_module(modname: str) -> Any:
def _reload_module(module: ModuleType) -> Any:
"""
Call importlib.reload(module), convert exceptions to ImportError
"""
"""Call importlib.reload(module), convert exceptions to ImportError"""
try:
return importlib.reload(module)
except BaseException as exc:

6
sphinx/ext/autosummary/__init__.py
View File

@ -224,8 +224,7 @@ def get_documenter(app: Sphinx, obj: Any, parent: Any) -> type[Documenter]:
class Autosummary(SphinxDirective):
"""
Pretty table containing short signatures and summaries of functions etc.
"""Pretty table containing short signatures and summaries of functions etc.
autosummary can also optionally generate a hidden toctree:: node.
"""
@ -660,8 +659,7 @@ class ImportExceptionGroup(Exception):
def get_import_prefixes_from_env(env: BuildEnvironment) -> list[str | None]:
"""
Obtain current Python import prefixes (for `import_by_name`)
"""Obtain current Python import prefixes (for `import_by_name`)
from ``document.env``
"""
prefixes: list[str | None] = [None]

4
sphinx/ext/coverage.py
View File

@ -165,9 +165,7 @@ def _determine_py_coverage_modules(
class CoverageBuilder(Builder):
"""
Evaluates coverage of code in the documentation.
"""
"""Evaluates coverage of code in the documentation."""
name = 'coverage'
epilog = __(

8
sphinx/ext/doctest.py
View File

@ -64,9 +64,7 @@ def is_allowed_version(spec: str, version: str) -> bool:
class TestDirective(SphinxDirective):
"""
Base class for doctest-related directives.
"""
"""Base class for doctest-related directives."""
has_content = True
required_arguments = 0
@ -292,9 +290,7 @@ class SphinxDocTestRunner(doctest.DocTestRunner):
class DocTestBuilder(Builder):
"""
Runs test snippets in the documentation.
"""
"""Runs test snippets in the documentation."""
name = 'doctest'
epilog = __(

6
sphinx/ext/extlinks.py
View File

@ -44,8 +44,7 @@ logger = logging.getLogger(__name__)
class ExternalLinksChecker(SphinxPostTransform):
"""
For each external link, check if it can be replaced by an extlink.
"""For each external link, check if it can be replaced by an extlink.
We treat each ``reference`` node without ``internal`` attribute as an external link.
"""
@ -60,8 +59,7 @@ class ExternalLinksChecker(SphinxPostTransform):
self.check_uri(refnode)
def check_uri(self, refnode: nodes.reference) -> None:
"""
If the URI in ``refnode`` has a replacement in ``extlinks``,
"""If the URI in ``refnode`` has a replacement in ``extlinks``,
emit a warning with a replacement suggestion.
"""
if 'internal' in refnode or 'refuri' not in refnode:

8
sphinx/ext/graphviz.py
View File

@ -113,9 +113,7 @@ def align_spec(argument: Any) -> str:
class Graphviz(SphinxDirective):
"""
Directive to insert arbitrary dot markup.
"""
"""Directive to insert arbitrary dot markup."""
has_content = True
required_arguments = 0
@ -195,9 +193,7 @@ class Graphviz(SphinxDirective):
class GraphvizSimple(SphinxDirective):
"""
Directive to insert arbitrary dot markup.
"""
"""Directive to insert arbitrary dot markup."""
has_content = True
required_arguments = 1

22
sphinx/ext/inheritance_diagram.py
View File

@ -143,8 +143,7 @@ class InheritanceException(Exception):
class InheritanceGraph:
"""
Given a list of classes, determines the set of classes that they inherit
"""Given a list of classes, determines the set of classes that they inherit
from all the way to the root "object", and then is able to generate a
graphviz dot graph from them.
"""
@ -361,17 +360,13 @@ class InheritanceGraph:
class inheritance_diagram(graphviz):
"""
A docutils node to use as a placeholder for the inheritance diagram.
"""
"""A docutils node to use as a placeholder for the inheritance diagram."""
pass
class InheritanceDiagram(SphinxDirective):
"""
Run when the inheritance_diagram directive is first encountered.
"""
"""Run when the inheritance_diagram directive is first encountered."""
has_content = False
required_arguments = 1
@ -441,8 +436,7 @@ def get_graph_hash(node: inheritance_diagram) -> str:
def html_visit_inheritance_diagram(
self: HTML5Translator, node: inheritance_diagram
) -> None:
"""
Output the graph for HTML. This will insert a PNG with clickable
"""Output the graph for HTML. This will insert a PNG with clickable
image map.
"""
graph = node['graph']
@ -488,9 +482,7 @@ def html_visit_inheritance_diagram(
def latex_visit_inheritance_diagram(
self: LaTeXTranslator, node: inheritance_diagram
) -> None:
"""
Output the graph for LaTeX. This will insert a PDF.
"""
"""Output the graph for LaTeX. This will insert a PDF."""
graph = node['graph']
graph_hash = get_graph_hash(node)
@ -507,9 +499,7 @@ def texinfo_visit_inheritance_diagram(
self: TexinfoTranslator,
node: inheritance_diagram,
) -> None:
"""
Output the graph for Texinfo. This will insert a PNG.
"""
"""Output the graph for Texinfo. This will insert a PNG."""
graph = node['graph']
graph_hash = get_graph_hash(node)

9
sphinx/ext/napoleon/docstring.py
View File

@ -55,8 +55,7 @@ _SINGLETONS = frozenset({'None', 'True', 'False', 'Ellipsis', '...'})
class Deque(collections.deque[Any]):
"""
A subclass of deque that mimics ``pockets.iterators.modify_iter``.
"""A subclass of deque that mimics ``pockets.iterators.modify_iter``.
The `.Deque.get` and `.Deque.next` methods are added.
"""
@ -64,8 +63,7 @@ class Deque(collections.deque[Any]):
sentinel = object()
def get(self, n: int) -> Any:
"""
Return the nth element of the stack, or ``self.sentinel`` if n is
"""Return the nth element of the stack, or ``self.sentinel`` if n is
greater than the stack size.
"""
return self[n] if n < len(self) else self.sentinel
@ -1293,8 +1291,7 @@ class NumpyDocstring(GoogleDocstring):
return self._format_admonition('seealso', lines)
def _parse_numpydoc_see_also_section(self, content: list[str]) -> list[str]:
"""
See Also
"""See Also
--------
func_name : Descriptive text
continued text

8
sphinx/ext/todo.py
View File

@ -47,9 +47,7 @@ class todolist(nodes.General, nodes.Element):
class Todo(BaseAdmonition, SphinxDirective):
"""
A todo entry, displayed (if configured) in the form of an admonition.
"""
"""A todo entry, displayed (if configured) in the form of an admonition."""
node_class = todo_node
has_content = True
@ -109,9 +107,7 @@ class TodoDomain(Domain):
class TodoList(SphinxDirective):
"""
A list of all todo entries.
"""
"""A list of all todo entries."""
has_content = False
required_arguments = 0

13
sphinx/io.py
View File

@ -39,8 +39,7 @@ logger = logging.getLogger(__name__)
class SphinxBaseReader(standalone.Reader): # type: ignore[misc]
"""
A base class of readers for Sphinx.
"""A base class of readers for Sphinx.
This replaces reporter by Sphinx's on generating document.
"""
@ -73,8 +72,7 @@ class SphinxBaseReader(standalone.Reader): # type: ignore[misc]
return transforms
def new_document(self) -> nodes.document:
"""
Creates a new document object which has a special reporter object good
"""Creates a new document object which has a special reporter object good
for logging.
"""
document = super().new_document()
@ -92,9 +90,7 @@ class SphinxBaseReader(standalone.Reader): # type: ignore[misc]
class SphinxStandaloneReader(SphinxBaseReader):
"""
A basic document reader for Sphinx.
"""
"""A basic document reader for Sphinx."""
def setup(self, app: Sphinx) -> None:
self.transforms = self.transforms + app.registry.get_transforms()
@ -120,8 +116,7 @@ class SphinxStandaloneReader(SphinxBaseReader):
class SphinxI18nReader(SphinxBaseReader):
"""
A document reader for i18n.
"""A document reader for i18n.
This returns the source line number of original text as current source line number
to let users know where the error happened.

10
sphinx/jinja2glue.py
View File

@ -41,8 +41,7 @@ def _toint(val: str) -> int:
def _todim(val: int | str) -> str:
"""
Make val a css dimension. In particular the following transformations
"""Make val a css dimension. In particular the following transformations
are performed:
- None -> 'initial' (default CSS value)
@ -114,8 +113,7 @@ def warning(context: dict[str, Any], message: str, *args: Any, **kwargs: Any) ->
class SphinxFileSystemLoader(FileSystemLoader):
"""
FileSystemLoader subclass that is not so strict about '..' entries in
"""FileSystemLoader subclass that is not so strict about '..' entries in
template names.
"""
@ -156,9 +154,7 @@ class SphinxFileSystemLoader(FileSystemLoader):
class BuiltinTemplateLoader(TemplateBridge, BaseLoader):
"""
Interfaces the rendering environment of jinja2 for use in Sphinx.
"""
"""Interfaces the rendering environment of jinja2 for use in Sphinx."""
# TemplateBridge interface

3
sphinx/locale/__init__.py
View File

@ -15,8 +15,7 @@ if TYPE_CHECKING:
class _TranslationProxy:
"""
The proxy implementation attempts to be as complete as possible, so that
"""The proxy implementation attempts to be as complete as possible, so that
the lazy objects should mostly work as expected, for example for sorting.
"""

13
sphinx/parsers.py
View File

@ -23,10 +23,12 @@ if TYPE_CHECKING:
class Parser(docutils.parsers.Parser):
"""
A base class of source parsers. The additional parsers should inherit this class instead
of ``docutils.parsers.Parser``. Compared with ``docutils.parsers.Parser``, this class
improves accessibility to Sphinx APIs.
"""A base class of source parsers.
The additional parsers should inherit this class
instead of ``docutils.parsers.Parser``.
Compared with ``docutils.parsers.Parser``,
this class improves accessibility to Sphinx APIs.
The subclasses can access sphinx core runtime objects (app, config and env).
"""
@ -51,8 +53,7 @@ class RSTParser(docutils.parsers.rst.Parser, Parser):
"""A reST parser for Sphinx."""
def get_transforms(self) -> list[type[Transform]]:
"""
Sphinx's reST parser replaces a transform class for smart-quotes by its own
"""Sphinx's reST parser replaces a transform class for smart-quotes by its own
refs: sphinx.io.SphinxStandaloneReader
"""

7
sphinx/pygments_styles.py
View File

@ -22,8 +22,7 @@ class NoneStyle(Style):
class SphinxStyle(Style):
"""
Like friendly, but a bit darker to enhance contrast on the green
"""Like friendly, but a bit darker to enhance contrast on the green
background.
"""
@ -39,9 +38,7 @@ class SphinxStyle(Style):
class PyramidStyle(Style):
"""
Pylons/pyramid pygments style based on friendly style, by Blaise Laflamme.
"""
"""Pylons/pyramid pygments style based on friendly style, by Blaise Laflamme."""
# work in progress...

6
sphinx/roles.py
View File

@ -42,8 +42,7 @@ generic_docroles = {
class XRefRole(ReferenceRole):
"""
A generic cross-referencing role. To create a callable that can be used as
"""A generic cross-referencing role. To create a callable that can be used as
a role function, create an instance of this class.
The general features of this role are:
@ -370,8 +369,7 @@ class RFC(ReferenceRole):
def _format_rfc_target(target: str, /) -> str:
"""
Takes an RFC number with an optional anchor (like ``123#section-2.5.3``)
"""Takes an RFC number with an optional anchor (like ``123#section-2.5.3``)
and attempts to produce a human-friendly title for it.
We have a set of known anchors that we format nicely,

29
sphinx/search/__init__.py
View File

@ -33,8 +33,7 @@ _MINIFIED_JS_PATH = Path(package_dir, 'search', 'minified-js')
class SearchLanguage:
"""
This class is the base class for search natural language preprocessors. If
"""This class is the base class for search natural language preprocessors. If
you want to add support for a new language, you should override the methods
of this class.
@ -86,21 +85,17 @@ var Stemmer = function() {
self.init(options)
def init(self, options: dict[str, str]) -> None:
"""
Initialize the class with the options the user has given.
"""
"""Initialize the class with the options the user has given."""
def split(self, input: str) -> list[str]:
"""
This method splits a sentence into words. Default splitter splits input
"""This method splits a sentence into words. Default splitter splits input
at white spaces, which should be enough for most languages except CJK
languages.
"""
return self._word_re.findall(input)
def stem(self, word: str) -> str:
"""
This method implements stemming algorithm of the Python version.
"""This method implements stemming algorithm of the Python version.
Default implementation does nothing. You should implement this if the
language has any stemming rules.
@ -112,8 +107,7 @@ var Stemmer = function() {
return word
def word_filter(self, word: str) -> bool:
"""
Return true if the target word should be registered in the search index.
"""Return true if the target word should be registered in the search index.
This method is called after stemming.
"""
return len(word) == 0 or not (
@ -127,8 +121,7 @@ from sphinx.search.en import SearchEnglish # NoQA: E402
def parse_stop_word(source: str) -> set[str]:
"""
Parse snowball style word list like this:
"""Parse snowball style word list like this:
* https://snowball.tartarus.org/algorithms/finnish/stop.txt
"""
@ -162,8 +155,7 @@ languages: dict[str, str | type[SearchLanguage]] = {
class _JavaScriptIndex:
"""
The search index as JavaScript file that calls a function
"""The search index as JavaScript file that calls a function
on the documentation search object to register the index.
"""
@ -212,9 +204,7 @@ class WordStore:
class WordCollector(nodes.NodeVisitor):
"""
A special visitor that collects words for the `IndexBuilder`.
"""
"""A special visitor that collects words for the `IndexBuilder`."""
def __init__(self, document: nodes.document, lang: SearchLanguage) -> None:
super().__init__(document)
@ -262,8 +252,7 @@ class WordCollector(nodes.NodeVisitor):
class IndexBuilder:
"""
Helper class that creates a search index based on the doctrees
"""Helper class that creates a search index based on the doctrees
passed to the `feed` method.
"""

6
sphinx/search/ja.py
View File

@ -42,8 +42,7 @@ class BaseSplitter:
self.options = options
def split(self, input: str) -> list[str]:
"""
:param str input:
""":param str input:
:return:
:rtype: list[str]
"""
@ -516,8 +515,7 @@ class DefaultSplitter(BaseSplitter):
class SearchJapanese(SearchLanguage):
"""
Japanese search implementation: uses no stemmer, but word splitting is quite
"""Japanese search implementation: uses no stemmer, but word splitting is quite
complicated.
"""

4
sphinx/search/zh.py
View File

@ -218,9 +218,7 @@ iti|ous|ive|ize)$/;
class SearchChinese(SearchLanguage):
"""
Chinese search implementation
"""
"""Chinese search implementation"""
lang = 'zh'
language_name = 'Chinese'

27
sphinx/testing/fixtures.py
View File

@ -76,8 +76,7 @@ def app_params(
sphinx_test_tempdir: str,
rootdir: Path,
) -> _app_params:
"""
Parameters that are specified by 'pytest.mark.sphinx' for
"""Parameters that are specified by 'pytest.mark.sphinx' for
sphinx.application.Sphinx initialization
"""
# ##### process pytest.mark.sphinx
@ -119,8 +118,7 @@ _app_params = namedtuple('_app_params', 'args,kwargs') # NoQA: PYI024
@pytest.fixture
def test_params(request: Any) -> dict[str, Any]:
"""
Test parameters that are specified by 'pytest.mark.test_params'
"""Test parameters that are specified by 'pytest.mark.test_params'
:param Union[str] shared_result:
If the value is provided, app._status and app._warning objects will be
@ -148,9 +146,7 @@ def app(
make_app: Callable[[], SphinxTestApp],
shared_result: SharedResult,
) -> Iterator[SphinxTestApp]:
"""
Provides the 'sphinx.application.Sphinx' object
"""
"""Provides the 'sphinx.application.Sphinx' object"""
args, kwargs = app_params
app_ = make_app(*args, **kwargs)
yield app_
@ -168,24 +164,19 @@ def app(
@pytest.fixture
def status(app: SphinxTestApp) -> StringIO:
"""
Back-compatibility for testing with previous @with_app decorator
"""
"""Back-compatibility for testing with previous @with_app decorator"""
return app.status
@pytest.fixture
def warning(app: SphinxTestApp) -> StringIO:
"""
Back-compatibility for testing with previous @with_app decorator
"""
"""Back-compatibility for testing with previous @with_app decorator"""
return app.warning
@pytest.fixture
def make_app(test_params: dict[str, Any]) -> Iterator[Callable[[], SphinxTestApp]]:
"""
Provides make_app function to initialize SphinxTestApp instance.
"""Provides make_app function to initialize SphinxTestApp instance.
if you want to initialize 'app' in your test function. please use this
instead of using SphinxTestApp class directory.
"""
@ -223,8 +214,7 @@ def _shared_result_cache() -> None:
@pytest.fixture
def if_graphviz_found(app: SphinxTestApp) -> None:
"""
The test will be skipped when using 'if_graphviz_found' fixture and graphviz
"""The test will be skipped when using 'if_graphviz_found' fixture and graphviz
dot command is not found.
"""
graphviz_dot = getattr(app.config, 'graphviz_dot', '')
@ -247,8 +237,7 @@ def sphinx_test_tempdir(tmp_path_factory: pytest.TempPathFactory) -> Path:
@pytest.fixture
def rollback_sysmodules() -> Iterator[None]:
"""
Rollback sys.modules to its value before testing to unload modules
"""Rollback sys.modules to its value before testing to unload modules
during tests.
For example, used in test_ext_autosummary.py to permit unloading the

79
sphinx/testing/path.py
View File

@ -34,56 +34,40 @@ UMASK = getumask()
class path(str): # NoQA: FURB189
"""
Represents a path which behaves like a string.
"""
"""Represents a path which behaves like a string."""
__slots__ = ()
@property
def parent(self) -> path:
"""
The name of the directory the file or directory is in.
"""
"""The name of the directory the file or directory is in."""
return self.__class__(os.path.dirname(self))
def basename(self) -> str:
return os.path.basename(self)
def abspath(self) -> path:
"""
Returns the absolute path.
"""
"""Returns the absolute path."""
return self.__class__(os.path.abspath(self))
def isabs(self) -> bool:
"""
Returns ``True`` if the path is absolute.
"""
"""Returns ``True`` if the path is absolute."""
return os.path.isabs(self)
def isdir(self) -> bool:
"""
Returns ``True`` if the path is a directory.
"""
"""Returns ``True`` if the path is a directory."""
return os.path.isdir(self)
def isfile(self) -> bool:
"""
Returns ``True`` if the path is a file.
"""
"""Returns ``True`` if the path is a file."""
return os.path.isfile(self)
def islink(self) -> bool:
"""
Returns ``True`` if the path is a symbolic link.
"""
"""Returns ``True`` if the path is a symbolic link."""
return os.path.islink(self)
def ismount(self) -> bool:
"""
Returns ``True`` if the path is a mount point.
"""
"""Returns ``True`` if the path is a mount point."""
return os.path.ismount(self)
def rmtree(
@ -91,8 +75,7 @@ class path(str): # NoQA: FURB189
ignore_errors: bool = False,
onerror: Callable[[Callable[..., Any], str, Any], object] | None = None,
) -> None:
"""
Removes the file or directory and any files or directories it may
"""Removes the file or directory and any files or directories it may
contain.
:param ignore_errors:
@ -109,8 +92,7 @@ class path(str): # NoQA: FURB189
shutil.rmtree(self, ignore_errors=ignore_errors, onerror=onerror)
def copytree(self, destination: str, symlinks: bool = False) -> None:
"""
Recursively copy a directory to the given `destination`. If the given
"""Recursively copy a directory to the given `destination`. If the given
`destination` does not exist it will be created.
:param symlinks:
@ -131,8 +113,7 @@ class path(str): # NoQA: FURB189
os.chmod(os.path.join(root, name), 0o644 & ~UMASK)
def movetree(self, destination: str) -> None:
"""
Recursively move the file or directory to the given `destination`
"""Recursively move the file or directory to the given `destination`
similar to the Unix "mv" command.
If the `destination` is a file it may be overwritten depending on the
@ -143,15 +124,11 @@ class path(str): # NoQA: FURB189
move = movetree
def unlink(self) -> None:
"""
Removes a file.
"""
"""Removes a file."""
os.unlink(self)
def stat(self) -> Any:
"""
Returns a stat of the file.
"""
"""Returns a stat of the file."""
return os.stat(self)
def utime(self, arg: Any) -> None:
@ -161,29 +138,22 @@ class path(str): # NoQA: FURB189
return open(self, mode, **kwargs)
def write_text(self, text: str, encoding: str = 'utf-8', **kwargs: Any) -> None:
"""
Writes the given `text` to the file.
"""
"""Writes the given `text` to the file."""
with open(self, 'w', encoding=encoding, **kwargs) as f:
f.write(text)
def read_text(self, encoding: str = 'utf-8', **kwargs: Any) -> str:
"""
Returns the text in the file.
"""
"""Returns the text in the file."""
with open(self, encoding=encoding, **kwargs) as f:
return f.read()
def read_bytes(self) -> builtins.bytes:
"""
Returns the bytes in the file.
"""
"""Returns the bytes in the file."""
with open(self, mode='rb') as f:
return f.read()
def write_bytes(self, bytes: bytes, append: bool = False) -> None:
"""
Writes the given `bytes` to the file.
"""Writes the given `bytes` to the file.
:param append:
If ``True`` given `bytes` are added at the end of the file.
@ -196,28 +166,21 @@ class path(str): # NoQA: FURB189
f.write(bytes)
def exists(self) -> bool:
"""
Returns ``True`` if the path exist.
"""
"""Returns ``True`` if the path exist."""
return os.path.exists(self)
def lexists(self) -> bool:
"""
Returns ``True`` if the path exists unless it is a broken symbolic
"""Returns ``True`` if the path exists unless it is a broken symbolic
link.
"""
return os.path.lexists(self)
def makedirs(self, mode: int = 0o777, exist_ok: bool = False) -> None:
"""
Recursively create directories.
"""
"""Recursively create directories."""
os.makedirs(self, mode, exist_ok=exist_ok)
def joinpath(self, *args: Any) -> path:
"""
Joins the path with the argument given and returns the result.
"""
"""Joins the path with the argument given and returns the result."""
return self.__class__(os.path.join(self, *map(self.__class__, args)))
def listdir(self) -> list[str]:

45
sphinx/transforms/__init__.py
View File

@ -76,9 +76,7 @@ class SphinxTransform(Transform):
class SphinxTransformer(Transformer):
"""
A transformer for Sphinx.
"""
"""A transformer for Sphinx."""
document: nodes.document
env: BuildEnvironment | None = None
@ -106,9 +104,7 @@ class SphinxTransformer(Transformer):
class DefaultSubstitutions(SphinxTransform):
"""
Replace some substitutions if they aren't defined in the document.
"""
"""Replace some substitutions if they aren't defined in the document."""
# run before the default Substitutions
default_priority = 210
@ -150,8 +146,7 @@ def _calculate_translation_progress(document: nodes.document) -> str:
class MoveModuleTargets(SphinxTransform):
"""
Move module targets that are the first thing in a section to the section
"""Move module targets that are the first thing in a section to the section
title.
XXX Python specific
@ -176,9 +171,7 @@ class MoveModuleTargets(SphinxTransform):
class HandleCodeBlocks(SphinxTransform):
"""
Several code block related transformations.
"""
"""Several code block related transformations."""
default_priority = 210
@ -200,9 +193,7 @@ class HandleCodeBlocks(SphinxTransform):
class AutoNumbering(SphinxTransform):
"""
Register IDs of tables, figures and literal_blocks to assign numbers.
"""
"""Register IDs of tables, figures and literal_blocks to assign numbers."""
default_priority = 210
@ -219,9 +210,7 @@ class AutoNumbering(SphinxTransform):
class SortIds(SphinxTransform):
"""
Sort section IDs so that the "id[0-9]+" one comes last.
"""
"""Sort section IDs so that the "id[0-9]+" one comes last."""
default_priority = 261
@ -241,9 +230,7 @@ TRANSLATABLE_NODES = {
class ApplySourceWorkaround(SphinxTransform):
"""
Update source and rawsource attributes
"""
"""Update source and rawsource attributes"""
default_priority = 10
@ -254,9 +241,7 @@ class ApplySourceWorkaround(SphinxTransform):
class AutoIndexUpgrader(SphinxTransform):
"""
Detect old style (4 column based indices) and automatically upgrade to new style.
"""
"""Detect old style (4 column based indices) and automatically upgrade to new style."""
default_priority = 210
@ -277,9 +262,7 @@ class AutoIndexUpgrader(SphinxTransform):
class ExtraTranslatableNodes(SphinxTransform):
"""
Make nodes translatable
"""
"""Make nodes translatable"""
default_priority = 10
@ -297,9 +280,7 @@ class ExtraTranslatableNodes(SphinxTransform):
class UnreferencedFootnotesDetector(SphinxTransform):
"""
Detect unreferenced footnotes and emit warnings
"""
"""Detect unreferenced footnotes and emit warnings"""
default_priority = Footnotes.default_priority + 2
@ -361,8 +342,7 @@ class FilterSystemMessages(SphinxTransform):
class SphinxContentsFilter(ContentsFilter):
"""
Used with BuildEnvironment.add_toc_from() to discard cross-file links
"""Used with BuildEnvironment.add_toc_from() to discard cross-file links
within table-of-contents link nodes.
"""
@ -373,8 +353,7 @@ class SphinxContentsFilter(ContentsFilter):
class SphinxSmartQuotes(SmartQuotes, SphinxTransform):
"""
Customized SmartQuotes to avoid transform for some extra node types.
"""Customized SmartQuotes to avoid transform for some extra node types.
refs: sphinx.parsers.RSTParser
"""

20
sphinx/transforms/i18n.py
View File

@ -100,9 +100,7 @@ def parse_noqa(source: str) -> tuple[str, bool]:
class PreserveTranslatableMessages(SphinxTransform):
"""
Preserve original translatable messages before translation
"""
"""Preserve original translatable messages before translation"""
default_priority = 10 # this MUST be invoked before Locale transform
@ -380,9 +378,7 @@ class _NodeUpdater:
class Locale(SphinxTransform):
"""
Replace translatable nodes with their translated doctree.
"""
"""Replace translatable nodes with their translated doctree."""
default_priority = 20
@ -609,9 +605,7 @@ class Locale(SphinxTransform):
class TranslationProgressTotaliser(SphinxTransform):
"""
Calculate the number of translated and untranslated nodes.
"""
"""Calculate the number of translated and untranslated nodes."""
default_priority = 25 # MUST happen after Locale
@ -634,9 +628,7 @@ class TranslationProgressTotaliser(SphinxTransform):
class AddTranslationClasses(SphinxTransform):
"""
Add ``translated`` or ``untranslated`` classes to indicate translation status.
"""
"""Add ``translated`` or ``untranslated`` classes to indicate translation status."""
default_priority = 950
@ -674,9 +666,7 @@ class AddTranslationClasses(SphinxTransform):
class RemoveTranslatableInline(SphinxTransform):
"""
Remove inline nodes used for translation as placeholders.
"""
"""Remove inline nodes used for translation as placeholders."""
default_priority = 999

4
sphinx/transforms/post_transforms/__init__.py
View File

@ -60,9 +60,7 @@ class SphinxPostTransform(SphinxTransform):
class ReferencesResolver(SphinxPostTransform):
"""
Resolves cross-references on doctrees.
"""
"""Resolves cross-references on doctrees."""
default_priority = 10

6
sphinx/transforms/post_transforms/code.py
View File

@ -28,8 +28,7 @@ class HighlightSetting(NamedTuple):
class HighlightLanguageTransform(SphinxTransform):
"""
Apply highlight_language to all literal_block nodes.
"""Apply highlight_language to all literal_block nodes.
This refers both :confval:`highlight_language` setting and
:rst:dir:`highlight` directive. After processing, this transform
@ -88,8 +87,7 @@ class HighlightLanguageVisitor(nodes.NodeVisitor):
class TrimDoctestFlagsTransform(SphinxTransform):
"""
Trim doctest flags like ``# doctest: +FLAG`` from python code-blocks.
"""Trim doctest flags like ``# doctest: +FLAG`` from python code-blocks.
see :confval:`trim_doctest_flags` for more information.
"""

3
sphinx/util/_files.py
View File

@ -10,8 +10,7 @@ if TYPE_CHECKING:
class FilenameUniqDict(dict[str, tuple[set[str], str]]):
"""
A dictionary that automatically generates unique names for its keys,
"""A dictionary that automatically generates unique names for its keys,
interpreted as filenames, and keeps track of a set of docnames they
appear in. Used for images and downloadable files in the environment.
"""

9
sphinx/util/docfields.py
View File

@ -183,8 +183,7 @@ class Field:
class GroupedField(Field):
"""
A doc field that is grouped; i.e., all fields of that type will be
"""A doc field that is grouped; i.e., all fields of that type will be
transformed into one field with its body being a bulleted list. It always
has an argument. The argument can be linked using the given *rolename*.
GroupedField should be used for doc fields that can occur more than once.
@ -248,8 +247,7 @@ class GroupedField(Field):
class TypedField(GroupedField):
"""
A doc field that is grouped and has type information for the arguments. It
"""A doc field that is grouped and has type information for the arguments. It
always has an argument. The argument can be linked using the given
*rolename*, the type using the given *typerolename*.
@ -340,8 +338,7 @@ class TypedField(GroupedField):
class DocFieldTransformer:
"""
Transforms field lists in "doc field" syntax into better-looking
"""Transforms field lists in "doc field" syntax into better-looking
equivalents, using the field type definitions given on a domain.
"""

6
sphinx/util/docutils.py
View File

@ -730,8 +730,7 @@ class SphinxTranslator(nodes.NodeVisitor):
self._domains = builder.env.domains
def dispatch_visit(self, node: Node) -> None:
"""
Dispatch node to appropriate visitor method.
"""Dispatch node to appropriate visitor method.
The priority of visitor method is:
1. ``self.visit_{node_class}()``
@ -747,8 +746,7 @@ class SphinxTranslator(nodes.NodeVisitor):
super().dispatch_visit(node)
def dispatch_departure(self, node: Node) -> None:
"""
Dispatch node to appropriate departure method.
"""Dispatch node to appropriate departure method.
The priority of departure method is:
1. ``self.depart_{node_class}()``

6
sphinx/util/nodes.py
View File

@ -99,8 +99,7 @@ class NodeMatcher(Generic[N]):
def get_full_module_name(node: Node) -> str:
"""
Return full module dotted path like: 'docutils.nodes.paragraph'
"""Return full module dotted path like: 'docutils.nodes.paragraph'
:param nodes.Node node: target node
:return: full module dotted path
@ -109,8 +108,7 @@ def get_full_module_name(node: Node) -> str:
def repr_domxml(node: Node, length: int = 80) -> str:
"""
Return DOM XML representation of the specified node like:
"""Return DOM XML representation of the specified node like:
'<paragraph translatable="False"><inline classes="versionadded">Added in version...'
:param nodes.Node node: target node

4
sphinx/writers/html5.py
View File

@ -44,9 +44,7 @@ def multiply_length(length: str, scale: int) -> str:
class HTML5Translator(SphinxTranslator, BaseTranslator): # type: ignore[misc]
"""
Our custom HTML translator.
"""
"""Our custom HTML translator."""
builder: StandaloneHTMLBuilder
# Override docutils.writers.html5_polyglot:HTMLTranslator

7
sphinx/writers/manpage.py
View File

@ -41,8 +41,7 @@ class ManualPageWriter(Writer): # type: ignore[misc]
class NestedInlineTransform:
"""
Flatten nested inline nodes:
"""Flatten nested inline nodes:
Before:
<strong>foo=<emphasis>1</emphasis>
@ -73,9 +72,7 @@ class NestedInlineTransform:
class ManualPageTranslator(SphinxTranslator, BaseTranslator): # type: ignore[misc]
"""
Custom man page translator.
"""
"""Custom man page translator."""
_docinfo: dict[str, Any] = {}

8
tests/roots/test-ext-autodoc/target/__init__.py
View File

@ -22,9 +22,7 @@ class CustomEx(Exception):
def _funky_classmethod(name, b, c, d, docstring=None):
"""
Generates a classmethod for a class from a template by filling out some arguments.
"""
"""Generates a classmethod for a class from a template by filling out some arguments."""
def template(cls, a, b, c, d=4, e=5, f=6):
return a, b, c, d, e, f
@ -95,9 +93,7 @@ class CustomDict(dict): # NoQA: FURB189
def function(foo, *args, **kwds):
"""
Return spam.
"""
"""Return spam."""
pass

4
tests/roots/test-ext-autodoc/target/empty_all.py
View File

@ -1,6 +1,4 @@
"""
docsting of empty_all module.
"""
"""docsting of empty_all module."""
__all__ = []

3
tests/roots/test-ext-autodoc/target/inherited_annotations.py
View File

@ -1,5 +1,4 @@
"""
Test case for #11387 corner case involving inherited
"""Test case for #11387 corner case involving inherited
members with type annotations on python 3.9 and earlier
"""

3
tests/roots/test-ext-autodoc/target/process_docstring.py
View File

@ -1,6 +1,5 @@
def func():
"""
first line
"""first line
---
second line
---

12
tests/roots/test-ext-autosummary-ext/dummy_module.py
View File

@ -7,7 +7,7 @@
C.prop_attr1
C.prop_attr2
C.C2
"""
""" # NoQA: D212
def with_sentence():
@ -41,8 +41,7 @@ module_attr = 1
class C:
"""
My C class
"""My C class
with class_attr attribute
"""
@ -59,8 +58,7 @@ class C:
self.instance_attr = '42'
def _prop_attr_get(self):
"""
This is a function docstring
"""This is a function docstring
return value is string.
"""
@ -76,9 +74,7 @@ class C:
"""
class C2:
"""
This is a nested inner class docstring
"""
"""This is a nested inner class docstring"""
def func(arg_, *args, **kwargs):

4
tests/roots/test-ext-autosummary-ext/underscore_module_.py
View File

@ -1,6 +1,4 @@
"""
module with trailing underscores everywhere
"""
"""module with trailing underscores everywhere"""
class class_:

5
tests/roots/test-ext-doctest-with-autodoc/dir/bar.py
View File

@ -1,4 +1 @@
"""
>>> 'dir/bar.py:2'
"""
""">>> 'dir/bar.py:2'"""

6
tests/roots/test-ext-doctest-with-autodoc/foo.py
View File

@ -1,5 +1 @@
"""
>>> 'foo.py:3'
"""
""">>> 'foo.py:3'"""

3
tests/roots/test-ext-napoleon/mypackage/typehints.py
View File

@ -1,6 +1,5 @@
def hello(x: int, *args: int, **kwargs: int) -> None:
"""
Parameters
"""Parameters
----------
x
X

16
tests/roots/test-ext-viewcode-find-package/main_package/subpackage/_subpackage2/submodule.py
View File

@ -1,6 +1,4 @@
"""
submodule
"""
"""submodule"""
# raise RuntimeError('This module should not get imported')
@ -10,23 +8,17 @@ def decorator(f):
@decorator
def func1(a, b):
"""
this is func1
"""
"""this is func1"""
return a, b
@decorator
class Class1:
"""
this is Class1
"""
"""this is Class1"""
class Class3:
"""
this is Class3
"""
"""this is Class3"""
class_attr = 42
"""this is the class attribute class_attr"""

12
tests/roots/test-ext-viewcode-find/not_a_package/submodule.py
View File

@ -1,6 +1,6 @@
"""
submodule
"""
""" # NoQA: D212
raise RuntimeError('This module should not get imported') # NoQA: EM101,TRY003
@ -13,21 +13,17 @@ def decorator(f):
def func1(a, b):
"""
this is func1
"""
""" # NoQA: D212
return a, b
@decorator
class Class1:
"""
this is Class1
"""
"""this is Class1"""
class Class3:
"""
this is Class3
"""
"""this is Class3"""
class_attr = 42
"""this is the class attribute class_attr"""

16
tests/roots/test-ext-viewcode/spam/mod1.py
View File

@ -1,6 +1,4 @@
"""
mod1
"""
"""mod1"""
def decorator(f):
@ -9,23 +7,17 @@ def decorator(f):
@decorator
def func1(a, b):
"""
this is func1
"""
"""this is func1"""
return a, b
@decorator
class Class1:
"""
this is Class1
"""
"""this is Class1"""
class Class3:
"""
this is Class3
"""
"""this is Class3"""
class_attr = 42
"""this is the class attribute class_attr"""

12
tests/roots/test-ext-viewcode/spam/mod2.py
View File

@ -1,6 +1,4 @@
"""
mod2
"""
"""mod2"""
def decorator(f):
@ -9,14 +7,10 @@ def decorator(f):
@decorator
def func2(a, b):
"""
this is func2
"""
"""this is func2"""
return a, b
@decorator
class Class2:
"""
this is Class2
"""
"""this is Class2"""

4
tests/roots/test-inheritance/dummy/test.py
View File

@ -1,6 +1,4 @@
r"""
Test with a class diagram like this::
r"""Test with a class diagram like this::
A
/ \

12
tests/roots/test-root/autodoc_target.py
View File

@ -46,9 +46,7 @@ class CustomDataDescriptor2(CustomDataDescriptor):
def _funky_classmethod(name, b, c, d, docstring=None):
"""
Generates a classmethod for a class from a template by filling out some arguments.
"""
"""Generates a classmethod for a class from a template by filling out some arguments."""
def template(cls, a, b, c, d=4, e=5, f=6):
return a, b, c, d, e, f
@ -136,9 +134,7 @@ class CustomDict(dict): # NoQA: FURB189
def function(foo, *args, **kwds):
"""
Return spam.
"""
"""Return spam."""
pass
@ -216,9 +212,7 @@ class InstAttCls:
class EnumCls(enum.Enum):
"""
this is enum class
"""
"""this is enum class"""
#: doc for val1
val1 = 12

3
tests/roots/test-warnings/autodoc_fodder.py
View File

@ -1,6 +1,5 @@
class MarkupError:
"""
.. note:: This is a docstring with a
""".. note:: This is a docstring with a
small markup error which should have
correct location information.
"""

3
tests/test_builders/test_build_html_copyright.py
View File

@ -11,8 +11,7 @@ LOCALTIME_2009 = type(LT)(LT_NEW)
@pytest.fixture
def no_source_date_year(monkeypatch):
"""
Explicitly clear SOURCE_DATE_EPOCH from the environment; this
"""Explicitly clear SOURCE_DATE_EPOCH from the environment; this
fixture can be used to ensure that copyright substitution logic
does not occur during selected test cases.
"""

3
tests/test_builders/test_build_linkcheck.py
View File

@ -488,8 +488,7 @@ def custom_handler(
valid_credentials: tuple[str, str] | None = None,
success_criteria: Callable[[Any], bool] = lambda _: True,
) -> type[BaseHTTPRequestHandler]:
"""
Returns an HTTP request handler that authenticates the client and then determines
"""Returns an HTTP request handler that authenticates the client and then determines
an appropriate HTTP response code, based on caller-provided credentials and optional
success criteria, respectively.
"""

3
tests/test_extensions/ext_napoleon_pep526_data_numpy.py
View File

@ -7,8 +7,7 @@ module_level_var: int = 99
class PEP526NumpyClass:
"""
Sample class with PEP 526 annotations and numpy docstring
"""Sample class with PEP 526 annotations and numpy docstring
Attributes
----------

7
tests/test_extensions/test_ext_autodoc.py
View File

@ -243,8 +243,7 @@ def test_format_signature(app):
"""some docstring for F2."""
def __init__(self, *args, **kw):
"""
__init__(a1, a2, kw1=True, kw2=False)
"""__init__(a1, a2, kw1=True, kw2=False)
some docstring for __init__.
"""
@ -363,9 +362,7 @@ def test_get_doc(app):
"""Docstring"""
def g():
"""
Docstring
"""
"""Docstring"""
for func in (f, g):
assert getdocl('function', func) == ['Docstring']

4
tests/test_extensions/test_ext_napoleon.py
View File

@ -13,9 +13,7 @@ from sphinx.ext.napoleon import Config, _process_docstring, _skip_member, setup
def simple_decorator(f):
"""
A simple decorator that does nothing, for tests to use.
"""
"""A simple decorator that does nothing, for tests to use."""
@functools.wraps(f)
def wrapper(*args, **kwargs):

3
tests/test_extensions/test_ext_todo.py
View File

@ -94,8 +94,7 @@ def test_todo_not_included(app):
confoverrides={'todo_include_todos': True},
)
def test_todo_valid_link(app):
"""
Test that the inserted "original entry" links for todo items have a target
"""Test that the inserted "original entry" links for todo items have a target
that exists in the LaTeX output. The target was previously incorrectly
omitted (GitHub issue #1020).
"""

7
tests/test_extensions/test_ext_viewcode.py
View File

@ -48,9 +48,10 @@ def check_viewcode_output(app: SphinxTestApp) -> str:
) in result
assert '<span>@decorator</span>\n' in result
assert f'<span>class</span>{sp}<span>Class1</span><span>:</span>\n' in result
assert '<span> </span><span>&quot;&quot;&quot;</span>\n' in result
assert '<span> this is Class1</span>\n' in result
assert '<span> &quot;&quot;&quot;</span>\n' in result
assert (
'<span> </span>'
'<span>&quot;&quot;&quot;this is Class1&quot;&quot;&quot;</span></div>\n'
) in result
return result

3
tests/test_markup/test_metadata.py
View File

@ -9,8 +9,7 @@ import pytest
@pytest.mark.sphinx('dummy', testroot='metadata')
def test_docinfo(app):
"""
Inspect the 'docinfo' metadata stored in the first node of the document.
"""Inspect the 'docinfo' metadata stored in the first node of the document.
Note this doesn't give us access to data stored in subsequence blocks
that might be considered document metadata, such as 'abstract' or
'dedication' blocks, or the 'meta' role. Doing otherwise is probably more

3
tests/test_search.py
View File

@ -425,8 +425,7 @@ def test_search_index_is_deterministic(app):
def is_title_tuple_type(item: list[int | str]) -> bool:
"""
In the search index, titles inside .alltitles are stored as a tuple of
"""In the search index, titles inside .alltitles are stored as a tuple of
(document_idx, title_anchor). Tuples are represented as lists in JSON,
but their contents must not be sorted. We cannot sort them anyway, as
document_idx is an int and title_anchor is a str.

10
tests/test_util/test_util_inspect.py
View File

@ -943,9 +943,8 @@ def test_getdoc_inherited_classmethod():
class Foo:
@classmethod
def meth(cls):
"""
Docstring
indented text
"""Docstring
indented text
"""
class Bar(Foo):
@ -961,9 +960,8 @@ def test_getdoc_inherited_classmethod():
def test_getdoc_inherited_decorated_method():
class Foo:
def meth(self):
"""
Docstring
indented text
"""Docstring
indented text
"""
class Bar(Foo):

3
tests/test_util/test_util_nodes.py
View File

@ -161,8 +161,7 @@ def test_extract_messages(rst, node_cls, count):
def test_extract_messages_without_rawsource():
"""
Check node.rawsource is fall-backed by using node.astext() value.
"""Check node.rawsource is fall-backed by using node.astext() value.
`extract_message` which is used from Sphinx i18n feature drop ``not node.rawsource``
nodes. So, all nodes which want to translate must have ``rawsource`` value.

9
tests/utils.py
View File

@ -28,8 +28,7 @@ CERT_FILE: Final[str] = str(TESTS_ROOT / 'certs' / 'cert.pem')
class HttpServerThread(Thread):
def __init__(self, handler: type[BaseRequestHandler], *, port: int = 0) -> None:
"""
Constructs a threaded HTTP server. The default port number of ``0``
"""Constructs a threaded HTTP server. The default port number of ``0``
delegates selection of a port number to bind to to Python.
Ref: https://docs.python.org/3.11/library/socketserver.html#asynchronous-mixins
@ -77,8 +76,7 @@ def http_server(
@contextmanager
def rewrite_hyperlinks(app: Sphinx, server: HTTPServer) -> Iterator[None]:
"""
Rewrite hyperlinks that refer to network location 'localhost:7777',
"""Rewrite hyperlinks that refer to network location 'localhost:7777',
allowing that location to vary dynamically with the arbitrary test HTTP
server port assigned during unit testing.
@ -109,8 +107,7 @@ def serve_application(
tls_enabled: bool = False,
port: int = 0,
) -> Iterator[str]:
"""
Prepare a temporary server to handle HTTP requests related to the links
"""Prepare a temporary server to handle HTTP requests related to the links
found in a Sphinx application project.
:param app: The Sphinx application.

3
utils/babel_runner.py
View File

@ -163,8 +163,7 @@ def run_update() -> None:
def run_compile() -> None:
"""
Catalog compilation command.
"""Catalogue compilation command.
An extended command that writes all message strings that occur in
JavaScript files to a JavaScript file along with the .mo file.