Merge pull request #9470 from lmmx/4.x

Reviewed all docstrings to improve readability and correctness

sphinx/application.py

@@ -197,7 +197,7 @@ def __init__(self, srcdir: str, confdir: Optional[str], outdir: str, doctreedir:
 
         # notice for parallel build on macOS and py38+
         if sys.version_info > (3, 8) and platform.system() == 'Darwin' and parallel > 1:
-            logger.info(bold(__("For security reason, parallel mode is disabled on macOS and "
+            logger.info(bold(__("For security reasons, parallel mode is disabled on macOS and "
                                 "python3.8 and above. For more details, please read "
                                 "https://github.com/sphinx-doc/sphinx/issues/6803")))
 
@@ -415,7 +415,7 @@ def connect(self, event: str, callback: Callable, priority: int = 500) -> int:
         :param event: The name of target event
         :param callback: Callback function for the event
         :param priority: The priority of the callback.  The callbacks will be invoked
-                         in the order of *priority* in asending.
+                         in order of *priority* (ascending).
         :return: A listener ID.  It can be used for :meth:`disconnect`.
 
         .. versionchanged:: 3.0
@@ -493,7 +493,7 @@ def add_config_value(self, name: str, default: Any, rebuild: Union[bool, str],
         values accordingly.
 
 
-        :param name: The name of configuration value.  It is recommended to be prefixed
+        :param name: The name of the configuration value.  It is recommended to be prefixed
                      with the extension name (ex. ``html_logo``, ``epub_title``)
         :param default: The default value of the configuration.
         :param rebuild: The condition of rebuild.  It must be one of those values:
@@ -539,10 +539,10 @@ def set_translator(self, name: str, translator_class: Type[nodes.NodeVisitor],
         """Register or override a Docutils translator class.
 
         This is used to register a custom output translator or to replace a
-        builtin translator.  This allows extensions to use custom translator
+        builtin translator.  This allows extensions to use a custom translator
         and define custom nodes for the translator (see :meth:`add_node`).
 
-        :param name: The name of builder for the translator
+        :param name: The name of the builder for the translator
         :param translator_class: A translator class
         :param override: If true, install the translator forcedly even if another translator
                          is already installed as the same name
@@ -606,11 +606,11 @@ def add_enumerable_node(self, node: Type[Element], figtype: str,
         using :rst:role:`numref`.
 
         :param node: A node class
-        :param figtype: The type of enumerable nodes.  Each figtypes have individual numbering
-                        sequences.  As a system figtypes, ``figure``, ``table`` and
-                        ``code-block`` are defined.  It is able to add custom nodes to these
-                        default figtypes.  It is also able to define new custom figtype if new
-                        figtype is given.
+        :param figtype: The type of enumerable nodes.  Each figtype has individual numbering
+                        sequences.  As system figtypes, ``figure``, ``table`` and
+                        ``code-block`` are defined.  It is possible to add custom nodes to
+                        these default figtypes.  It is also possible to define new custom
+                        figtype if a new figtype is given.
         :param title_getter: A getter function to obtain the title of node.  It takes an
                              instance of the enumerable node, and it must return its title as
                              string.  The title is used to the default title of references for
@@ -629,7 +629,7 @@ def add_enumerable_node(self, node: Type[Element], figtype: str,
     def add_directive(self, name: str, cls: Type[Directive], override: bool = False) -> None:
         """Register a Docutils directive.
 
-        :param name: The name of directive
+        :param name: The name of the directive
         :param cls: A directive class
         :param override: If true, install the directive forcedly even if another directive
                          is already installed as the same name
@@ -755,9 +755,9 @@ def add_role_to_domain(self, domain: str, name: str, role: Union[RoleFunction, X
         Like :meth:`add_role`, but the role is added to the domain named
         *domain*.
 
-        :param domain: The name of target domain
-        :param name: A name of role
-        :param role: A role function
+        :param domain: The name of the target domain
+        :param name: The name of the role
+        :param role: The role function
         :param override: If true, install the role forcedly even if another role is already
                          installed as the same name
 
@@ -773,8 +773,8 @@ def add_index_to_domain(self, domain: str, index: Type[Index], override: bool =
 
         Add a custom *index* class to the domain named *domain*.
 
-        :param domain: The name of target domain
-        :param index: A index class
+        :param domain: The name of the target domain
+        :param index: The index class
         :param override: If true, install the index forcedly even if another index is
                          already installed as the same name
 
@@ -942,8 +942,8 @@ def add_js_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None
         Add *filename* to the list of JavaScript files that the default HTML
         template will include in order of *priority* (ascending).  The filename
         must be relative to the HTML static path , or a full URI with scheme.
-        If the priority of JavaScript file is the same as others, the JavaScript
-        files will be included in order of the registration.  If the keyword
+        If the priority of the JavaScript file is the same as others, the JavaScript
+        files will be included in order of registration.  If the keyword
         argument ``body`` is given, its value will be added between the
         ``<script>`` tags. Extra keyword arguments are included as attributes of
         the ``<script>`` tag.
@@ -971,7 +971,7 @@ def add_js_file(self, filename: str, priority: int = 500, **kwargs: Any) -> None
            * - 800
              - default priority for :confval:`html_js_files`
 
-        A JavaScript file can be added to the specific HTML page when on extension
+        A JavaScript file can be added to the specific HTML page when an extension
         calls this method on :event:`html-page-context` event.
 
         .. versionadded:: 0.5
@@ -993,8 +993,8 @@ def add_css_file(self, filename: str, priority: int = 500, **kwargs: Any) -> Non
         Add *filename* to the list of CSS files that the default HTML template
         will include in order of *priority* (ascending).  The filename must be
         relative to the HTML static path, or a full URI with scheme.  If the
-        priority of CSS file is the same as others, the CSS files will be
-        included in order of the registration.  The keyword arguments are also
+        priority of the CSS file is the same as others, the CSS files will be
+        included in order of registration.  The keyword arguments are also
         accepted for attributes of ``<link>`` tag.
 
         Example::
@@ -1022,15 +1022,15 @@ def add_css_file(self, filename: str, priority: int = 500, **kwargs: Any) -> Non
            * - 800
              - default priority for :confval:`html_css_files`
 
-        A CSS file can be added to the specific HTML page when on extension calls
+        A CSS file can be added to the specific HTML page when an extension calls
         this method on :event:`html-page-context` event.
 
         .. versionadded:: 1.0
 
         .. versionchanged:: 1.6
            Optional ``alternate`` and/or ``title`` attributes can be supplied
-           with the *alternate* (of boolean type) and *title* (a string)
-           arguments. The default is no title and *alternate* = ``False``. For
+           with the arguments *alternate* (a Boolean) and *title* (a string).
+           The default is no title and *alternate* = ``False``. For
            more information, refer to the `documentation
            <https://mdn.io/Web/CSS/Alternative_style_sheets>`__.
 
@@ -1051,7 +1051,7 @@ def add_latex_package(self, packagename: str, options: str = None,
         r"""Register a package to include in the LaTeX source code.
 
         Add *packagename* to the list of packages that LaTeX source code will
-        include.  If you provide *options*, it will be taken to `\usepackage`
+        include.  If you provide *options*, it will be taken to the `\usepackage`
         declaration.  If you set *after_hyperref* truthy, the package will be
         loaded after ``hyperref`` package.
 
@@ -1087,7 +1087,7 @@ def add_autodocumenter(self, cls: Any, override: bool = False) -> None:
 
         Add *cls* as a new documenter class for the :mod:`sphinx.ext.autodoc`
         extension.  It must be a subclass of
-        :class:`sphinx.ext.autodoc.Documenter`.  This allows to auto-document
+        :class:`sphinx.ext.autodoc.Documenter`.  This allows auto-documenting
         new types of objects.  See the source of the autodoc module for
         examples on how to subclass :class:`Documenter`.
 
@@ -1140,10 +1140,10 @@ def add_source_suffix(self, suffix: str, filetype: str, override: bool = False)
         """Register a suffix of source files.
 
         Same as :confval:`source_suffix`.  The users can override this
-        using the setting.
+        using the config setting.
 
         If *override* is True, the given *suffix* is forcedly installed even if
-        a same suffix is already installed.
+        the same suffix is already installed.
 
         .. versionadded:: 1.8
         """
@@ -1204,8 +1204,8 @@ def add_html_math_renderer(self, name: str,
     def add_message_catalog(self, catalog: str, locale_dir: str) -> None:
         """Register a message catalog.
 
-        :param catalog: A name of catalog
-        :param locale_dir: The base path of message catalog
+        :param catalog: The name of the catalog
+        :param locale_dir: The base path of the message catalog
 
         For more details, see :func:`sphinx.locale.get_translation()`.
 
@@ -1216,7 +1216,7 @@ def add_message_catalog(self, catalog: str, locale_dir: str) -> None:
 
     # ---- other methods -------------------------------------------------
     def is_parallel_allowed(self, typ: str) -> bool:
-        """Check parallel processing is allowed or not.
+        """Check whether parallel processing is allowed or not.
 
         :param typ: A type of processing; ``'read'`` or ``'write'``.
         """

sphinx/config.py

@@ -56,7 +56,7 @@ def is_serializable(obj: Any) -> bool:
 
 
 class ENUM:
-    """represents the config value should be a one of candidates.
+    """Represents the candidates which a config value should be one of.
 
     Example:
         app.add_config_value('latex_show_urls', 'no', None, ENUM('no', 'footnote', 'inline'))
@@ -215,7 +215,8 @@ def convert_overrides(self, name: str, value: Any) -> Any:
 
     def pre_init_values(self) -> None:
         """
-        Initialize some limited config variables before initialize i18n and loading extensions
+        Initialize some limited config variables before initializing i18n and loading
+        extensions.
         """
         variables = ['needs_sphinx', 'suppress_warnings', 'language', 'locale_dirs']
         for name in variables:
@@ -343,7 +344,7 @@ def eval_config_file(filename: str, tags: Optional[Tags]) -> Dict[str, Any]:
 
 
 def convert_source_suffix(app: "Sphinx", config: Config) -> None:
-    """This converts old styled source_suffix to new styled one.
+    """Convert old styled source_suffix to new styled one.
 
     * old style: str or list
     * new style: a dict which maps from fileext to filetype
@@ -371,7 +372,7 @@ def convert_highlight_options(app: "Sphinx", config: Config) -> None:
     """Convert old styled highlight_options to new styled one.
 
     * old style: options
-    * new style: dict that maps language names to options
+    * new style: a dict which maps from language name to options
     """
     options = config.highlight_options
     if options and not all(isinstance(v, dict) for v in options.values()):
@@ -392,7 +393,7 @@ def init_numfig_format(app: "Sphinx", config: Config) -> None:
 
 
 def correct_copyright_year(app: "Sphinx", config: Config) -> None:
-    """correct values of copyright year that are not coherent with
+    """Correct values of copyright year that are not coherent with
     the SOURCE_DATE_EPOCH environment variable (if set)
 
     See https://reproducible-builds.org/specs/source-date-epoch/
@@ -405,7 +406,7 @@ def correct_copyright_year(app: "Sphinx", config: Config) -> None:
 
 
 def check_confval_types(app: "Sphinx", config: Config) -> None:
-    """check all values for deviation from the default value's type, since
+    """Check all values for deviation from the default value's type, since
     that can result in TypeErrors all over the place NB.
     """
     for confval in config:
@@ -469,7 +470,7 @@ def check_primary_domain(app: "Sphinx", config: Config) -> None:
 def check_root_doc(app: "Sphinx", env: "BuildEnvironment", added: Set[str],
                    changed: Set[str], removed: Set[str]) -> Set[str]:
     """Adjust root_doc to 'contents' to support an old project which does not have
-    no root_doc setting.
+    any root_doc setting.
     """
     if (app.config.root_doc == 'index' and
             'index' not in app.project.docnames and

sphinx/errors.py

@@ -129,5 +129,5 @@ class NoUri(Exception):
 
 
 class FiletypeNotFoundError(Exception):
-    "Raised by get_filetype() if a filename matches no source suffix."
+    """Raised by get_filetype() if a filename matches no source suffix."""
     pass

sphinx/ext/apidoc.py

@@ -226,7 +226,7 @@ def walk(rootpath: str, excludes: List[str], opts: Any
 
 
 def has_child_module(rootpath: str, excludes: List[str], opts: Any) -> bool:
-    """Check the given directory contains child modules at least one."""
+    """Check the given directory contains child module/s (at least one)."""
     for root, subs, files in walk(rootpath, excludes, opts):
         if files:
             return True

sphinx/ext/autodoc/__init__.py

@@ -306,7 +306,7 @@ class Documenter:
 
     A Documenter has an *option_spec* that works like a docutils directive's;
     in fact, it will be used to parse an auto directive's options that matches
-    the documenter.
+    the Documenter.
     """
     #: name by which the directive is called (auto...) and the default
     #: generated directive name
@@ -331,7 +331,7 @@ def get_attr(self, obj: Any, name: str, *defargs: Any) -> Any:
     @classmethod
     def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
                             ) -> bool:
-        """Called to see if a member can be documented by this documenter."""
+        """Called to see if a member can be documented by this Documenter."""
         raise NotImplementedError('must be implemented in subclasses')
 
     def __init__(self, directive: "DocumenterBridge", name: str, indent: str = '') -> None:
@@ -552,7 +552,7 @@ def add_directive_header(self, sig: str) -> None:
     def get_doc(self, ignore: int = None) -> Optional[List[List[str]]]:
         """Decode and return lines of the docstring(s) for the object.
 
-        When it returns None value, autodoc-process-docstring will not be called for this
+        When it returns None, autodoc-process-docstring will not be called for this
         object.
         """
         if ignore is not None:
@@ -643,7 +643,7 @@ def get_object_members(self, want_all: bool) -> Tuple[bool, ObjectMembers]:
         list of `(membername, member)` pairs of the members of *self.object*.
 
         If *want_all* is True, return all members.  Else, only return those
-        members given by *self.options.members* (which may also be none).
+        members given by *self.options.members* (which may also be None).
         """
         warnings.warn('The implementation of Documenter.get_object_members() will be '
                       'removed from Sphinx-6.0.', RemovedInSphinx60Warning)
@@ -820,7 +820,7 @@ def is_filtered_inherited_member(name: str, obj: Any) -> bool:
     def document_members(self, all_members: bool = False) -> None:
         """Generate reST for member documentation.
 
-        If *all_members* is True, do all members, else those given by
+        If *all_members* is True, document all members, else those given by
         *self.options.members*.
         """
         # set current namespace for finding members
@@ -2382,7 +2382,7 @@ def is_runtime_instance_attribute_not_commented(self, parent: Any) -> bool:
         return None
 
     def import_object(self, raiseerror: bool = False) -> bool:
-        """Check the existence of runtime instance attribute when failed to import the
+        """Check the existence of runtime instance attribute after failing to import the
         attribute."""
         try:
             return super().import_object(raiseerror=True)  # type: ignore

sphinx/ext/autodoc/directive.py

@@ -61,7 +61,7 @@ def __init__(self, env: BuildEnvironment, reporter: Reporter, options: Options,
         self.state = state
 
     def warn(self, msg: str) -> None:
-        warnings.warn('DocumenterBridge.warn is deprecated.  Plase use sphinx.util.logging '
+        warnings.warn('DocumenterBridge.warn is deprecated.  Please use sphinx.util.logging '
                       'module instead.',
                       RemovedInSphinx60Warning, stacklevel=2)
         logger.warning(msg, location=(self.env.docname, self.lineno))
@@ -107,7 +107,7 @@ def process_documenter_options(documenter: Type[Documenter], config: Config, opt
 
 def parse_generated_content(state: RSTState, content: StringList, documenter: Documenter
                             ) -> List[Node]:
-    """Parse a generated content by Documenter."""
+    """Parse an item of content generated by Documenter."""
     with switch_source_input(state, content):
         if documenter.titles_allowed:
             node: Element = nodes.section()
@@ -125,8 +125,8 @@ def parse_generated_content(state: RSTState, content: StringList, documenter: Do
 class AutodocDirective(SphinxDirective):
     """A directive class for all autodoc directives. It works as a dispatcher of Documenters.
 
-    It invokes a Documenter on running. After the processing, it parses and returns
-    the generated content by Documenter.
+    It invokes a Documenter upon running. After the processing, it parses and returns
+    the content generated by Documenter.
     """
     option_spec = DummyOptionSpec()
     has_content = True

sphinx/ext/autodoc/importer.py

@@ -30,7 +30,7 @@
 
 
 def mangle(subject: Any, name: str) -> str:
-    """mangle the given name."""
+    """Mangle the given name."""
     try:
         if isclass(subject) and name.startswith('__') and not name.endswith('__'):
             return "_%s%s" % (subject.__name__, name)
@@ -41,7 +41,7 @@ def mangle(subject: Any, name: str) -> str:
 
 
 def unmangle(subject: Any, name: str) -> Optional[str]:
-    """unmangle the given name."""
+    """Unmangle the given name."""
     try:
         if isclass(subject) and not name.endswith('__'):
             prefix = "_%s__" % subject.__name__

sphinx/ext/autosummary/__init__.py

@@ -568,7 +568,7 @@ def parse(doc: List[str], settings: Any) -> nodes.document:
 
 def limited_join(sep: str, items: List[str], max_chars: int = 30,
                  overflow_marker: str = "...") -> str:
-    """Join a number of strings to one, limiting the length to *max_chars*.
+    """Join a number of strings into one, limiting the length to *max_chars*.
 
     If the string overflows this limit, replace the last fitting item by
     *overflow_marker*.

sphinx/io.py

@@ -73,7 +73,8 @@ def get_transforms(self) -> List[Type[Transform]]:
         return transforms
 
     def new_document(self) -> nodes.document:
-        """Creates a new document object which having a special reporter object good
+        """
+        Creates a new document object which has a special reporter object good
         for logging.
         """
         document = super().new_document()