Enable various pydocstyle (D) rules (#11878)

Co-authored-by: Adam Turner <[email protected]>

Author: danieleades

.ruff.toml

@@ -73,26 +73,25 @@ select = [
 #    "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})
-#    "D203",  # 1 blank line required before class docstring
-#    "D204",  # 1 blank line required after class docstring
+    "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
+    "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
+    "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: `{}` -> `{}`
+    "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}")
@@ -499,9 +498,14 @@ select = [
 # Ruff bug: https://github.com/astral-sh/ruff/issues/6540
 "sphinx/transforms/i18n.py" = ["PGH004"]
 
+# Function wrappers
+"sphinx/ext/autodoc/importer.py" = ["D402"]
+"sphinx/util/requests.py" = ["D402"]
+
 "tests/*" = [
     "E501",
     "ANN",  # tests don't need annotations
+    "D402",
     "T201",  # whitelist ``print`` for tests
 ]
 

doc/conf.py

@@ -210,8 +210,7 @@ def parse_event(env, sig, signode):
 
 
 def linkify_issues_in_changelog(app, docname, source):
-    """ Linkify issue references like #123 in changelog to GitHub. """
-
+    """Linkify issue references like #123 in changelog to GitHub."""
     if docname == 'changes':
         changelog_path = os.path.join(os.path.dirname(__file__), "../CHANGES.rst")
         # this path trickery is needed because this script can

sphinx/addnodes.py

@@ -79,6 +79,7 @@ def extract_original_messages(self) -> Sequence[str]:
 
 class not_smartquotable:
     """A node which does not support smart-quotes."""
+
     support_smartquotes = False
 
 
@@ -163,6 +164,7 @@ class desc_signature(_desc_classes_injector, nodes.Part, nodes.Inline, nodes.Tex
 
     This node always has the classes ``sig``, ``sig-object``, and the domain it belongs to.
     """
+
     # Note: the domain name is being added through a post-transform DescSigAddDomainAsClass
     classes = ['sig', 'sig-object']
 
@@ -181,6 +183,7 @@ class desc_signature_line(nodes.Part, nodes.Inline, nodes.FixedTextElement):
     with ``is_multiline`` set to ``True``.
     Set ``add_permalink = True`` for the line that should get the permalink.
     """
+
     sphinx_line_type = ''
 
 
@@ -199,6 +202,7 @@ class desc_inline(_desc_classes_injector, nodes.Inline, nodes.TextElement):
     This node always has the classes ``sig``, ``sig-inline``,
     and the name of the domain it belongs to.
     """
+
     classes = ['sig', 'sig-inline']
 
     def __init__(self, domain: str, *args: Any, **kwargs: Any) -> None:
@@ -219,6 +223,7 @@ class desc_name(_desc_classes_injector, nodes.Part, nodes.Inline, nodes.FixedTex
 
     This node always has the class ``sig-name``.
     """
+
     classes = ['sig-name', 'descname']  # 'descname' is for backwards compatibility
 
 
@@ -230,6 +235,7 @@ class desc_addname(_desc_classes_injector, nodes.Part, nodes.Inline, nodes.Fixed
 
     This node always has the class ``sig-prename``.
     """
+
     # 'descclassname' is for backwards compatibility
     classes = ['sig-prename', 'descclassname']
 
@@ -256,6 +262,7 @@ class desc_parameterlist(nodes.Part, nodes.Inline, nodes.FixedTextElement):
     Set ``multi_line_parameter_list = True`` to describe a multi-line parameter list.
     In that case each parameter will then be written on its own, indented line.
     """
+
     child_text_separator = ', '
 
     def astext(self) -> str:
@@ -269,6 +276,7 @@ class desc_type_parameter_list(nodes.Part, nodes.Inline, nodes.FixedTextElement)
     Set ``multi_line_parameter_list = True`` to describe a multi-line type parameters list.
     In that case each type parameter will then be written on its own, indented line.
     """
+
     child_text_separator = ', '
 
     def astext(self) -> str:
@@ -285,6 +293,7 @@ class desc_type_parameter(nodes.Part, nodes.Inline, nodes.FixedTextElement):
 
 class desc_optional(nodes.Part, nodes.Inline, nodes.FixedTextElement):
     """Node for marking optional parts of the parameter list."""
+
     child_text_separator = ', '
 
     def astext(self) -> str:
@@ -315,6 +324,7 @@ class desc_annotation(nodes.Part, nodes.Inline, nodes.FixedTextElement):
 
 class desc_sig_element(nodes.inline, _desc_classes_injector):
     """Common parent class of nodes for inline text of a signature."""
+
     classes: list[str] = []
 
     def __init__(self, rawsource: str = '', text: str = '',
@@ -334,6 +344,7 @@ def __init_subclass__(cls, *, _sig_element: bool = False, **kwargs: Any):
 
 class desc_sig_space(desc_sig_element, _sig_element=True):
     """Node for a space in a signature."""
+
     classes = ["w"]
 
     def __init__(self, rawsource: str = '', text: str = ' ',
@@ -343,41 +354,49 @@ def __init__(self, rawsource: str = '', text: str = ' ',
 
 class desc_sig_name(desc_sig_element, _sig_element=True):
     """Node for an identifier in a signature."""
+
     classes = ["n"]
 
 
 class desc_sig_operator(desc_sig_element, _sig_element=True):
     """Node for an operator in a signature."""
+
     classes = ["o"]
 
 
 class desc_sig_punctuation(desc_sig_element, _sig_element=True):
     """Node for punctuation in a signature."""
+
     classes = ["p"]
 
 
 class desc_sig_keyword(desc_sig_element, _sig_element=True):
     """Node for a general keyword in a signature."""
+
     classes = ["k"]
 
 
 class desc_sig_keyword_type(desc_sig_element, _sig_element=True):
     """Node for a keyword which is a built-in type in a signature."""
+
     classes = ["kt"]
 
 
 class desc_sig_literal_number(desc_sig_element, _sig_element=True):
     """Node for a numeric literal in a signature."""
+
     classes = ["m"]
 
 
 class desc_sig_literal_string(desc_sig_element, _sig_element=True):
     """Node for a string literal in a signature."""
+
     classes = ["s"]
 
 
 class desc_sig_literal_char(desc_sig_element, _sig_element=True):
     """Node for a character literal in a signature."""
+
     classes = ["sc"]
 
 
@@ -425,7 +444,7 @@ class index(nodes.Invisible, nodes.Inline, nodes.TextElement):
 
 
 class centered(nodes.Part, nodes.TextElement):
-    """This node is deprecated."""
+    """Deprecated."""
 
 
 class acks(nodes.Element):
@@ -479,6 +498,7 @@ class pending_xref(nodes.Inline, nodes.Element):
     These nodes are resolved before writing output, in
     BuildEnvironment.resolve_references.
     """
+
     child_text_separator = ''
 
 

sphinx/builders/_epub_base.py

@@ -317,7 +317,8 @@ def make_footnote(doc: nodes.document, label: str, uri: str) -> nodes.footnote:
         def footnote_spot(tree: nodes.document) -> tuple[Element, int]:
             """Find or create a spot to place footnotes.
 
-            The function returns the tuple (parent, index)."""
+            The function returns the tuple (parent, index).
+            """
             # The code uses the following heuristic:
             # a) place them after the last existing footnote
             # b) place them after an (empty) Footnotes rubric
@@ -480,7 +481,6 @@ def content_metadata(self) -> dict[str, Any]:
         """Create a dictionary with all metadata for the content.opf
         file properly escaped.
         """
-
         if (source_date_epoch := os.getenv('SOURCE_DATE_EPOCH')) is not None:
             time_tuple = time.gmtime(int(source_date_epoch))
         else:

sphinx/builders/changes.py

@@ -26,6 +26,7 @@ class ChangesBuilder(Builder):
     """
     Write a summary with all versionadded/changed directives.
     """
+
     name = 'changes'
     epilog = __('The overview file is in %(outdir)s.')
 

sphinx/builders/dirhtml.py

@@ -21,6 +21,7 @@ class DirectoryHTMLBuilder(StandaloneHTMLBuilder):
     a directory given by their pagename, so that generated URLs don't have
     ``.html`` in them.
     """
+
     name = 'dirhtml'
 
     def get_target_uri(self, docname: str, typ: str | None = None) -> str:

sphinx/builders/epub3.py

@@ -75,6 +75,7 @@ class Epub3Builder(_epub_base.EpubBuilder):
     and META-INF/container.xml. Afterwards, all necessary files are zipped to
     an epub file.
     """
+
     name = 'epub'
     epilog = __('The ePub file is in %(outdir)s.')
 
@@ -240,7 +241,7 @@ def validate_config_values(app: Sphinx) -> None:
 
 
 def convert_epub_css_files(app: Sphinx, config: Config) -> None:
-    """This converts string styled epub_css_files to tuple styled one."""
+    """Convert string styled epub_css_files to tuple styled one."""
     epub_css_files: list[tuple[str, dict[str, Any]]] = []
     for entry in config.epub_css_files:
         if isinstance(entry, str):

sphinx/builders/gettext.py

@@ -39,6 +39,7 @@
 
 class Message:
     """An entry of translatable message."""
+
     def __init__(self, text: str, locations: list[tuple[str, int]], uuids: list[str]):
         self.text = text
         self.locations = locations
@@ -119,6 +120,7 @@ class I18nTags(Tags):
     To translate all text inside of only nodes, this class
     always returns True value even if no tags are defined.
     """
+
     def eval_condition(self, condition: Any) -> bool:
         return True
 
@@ -127,6 +129,7 @@ class I18nBuilder(Builder):
     """
     General i18n builder.
     """
+
     name = 'i18n'
     versioning_method = 'text'
     use_message_catalog = False
@@ -212,6 +215,7 @@ class MessageCatalogBuilder(I18nBuilder):
     """
     Builds gettext-style message catalogs (.pot files).
     """
+
     name = 'gettext'
     epilog = __('The message catalogs are in %(outdir)s.')
 

sphinx/builders/html/__init__.py

@@ -160,6 +160,7 @@ class StandaloneHTMLBuilder(Builder):
     """
     Builds standalone HTML docs.
     """
+
     name = 'html'
     format = 'html'
     epilog = __('The HTML pages are in %(outdir)s.')
@@ -782,7 +783,7 @@ def to_relpath(f: str) -> str:
                                    path.join(self.srcdir, src), err)
 
     def create_pygments_style_file(self) -> None:
-        """create a style file for pygments."""
+        """Create a style file for pygments."""
         with open(path.join(self.outdir, '_static', 'pygments.css'), 'w',
                   encoding="utf-8") as f:
             f.write(self.highlighter.get_stylesheet())
@@ -863,7 +864,7 @@ def copy_static_files(self) -> None:
             logger.warning(__('cannot copy static file %r'), err)
 
     def copy_extra_files(self) -> None:
-        """copy html_extra_path files."""
+        """Copy html_extra_path files."""
         try:
             with progress_message(__('copying extra files')):
                 excluded = Matcher(self.config.exclude_patterns)
@@ -1169,7 +1170,7 @@ def dump_search_index(self) -> None:
 
 
 def convert_html_css_files(app: Sphinx, config: Config) -> None:
-    """This converts string styled html_css_files to tuple styled one."""
+    """Convert string styled html_css_files to tuple styled one."""
     html_css_files: list[tuple[str, dict]] = []
     for entry in config.html_css_files:
         if isinstance(entry, str):
@@ -1192,7 +1193,7 @@ def _format_modified_time(timestamp: float) -> str:
 
 
 def convert_html_js_files(app: Sphinx, config: Config) -> None:
-    """This converts string styled html_js_files to tuple styled one."""
+    """Convert string styled html_js_files to tuple styled one."""
     html_js_files: list[tuple[str, dict]] = []
     for entry in config.html_js_files:
         if isinstance(entry, str):

sphinx/builders/html/transforms.py

@@ -31,6 +31,7 @@ class KeyboardTransform(SphinxPostTransform):
             <literal class="kbd">
                 x
     """
+
     default_priority = 400
     formats = ('html',)
     pattern = re.compile(r'(?<=.)(-|\+|\^|\s+)(?=.)')