[lint] follow PEP 8 for module-level dunder names (#12180)

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

.flake8

@@ -31,3 +31,6 @@ exclude =
     doc/_build/*,
     sphinx/search/*,
     doc/usage/extensions/example*.py,
+per-file-ignores =
+    tests/test_extensions/ext_napoleon_pep526_data_google.py:MLL001,
+    tests/test_extensions/ext_napoleon_pep526_data_numpy.py:MLL001,

sphinx/__init__.py

@@ -1,5 +1,8 @@
 """The Sphinx documentation toolchain."""
 
+__version__ = '7.3.0'
+__display_version__ = __version__  # used for command line version
+
 # Keep this file executable as-is in Python 3!
 # (Otherwise getting the version out of it when packaging is impossible.)
 
@@ -17,9 +20,6 @@ warnings.filterwarnings(
     'ignore', 'The frontend.Option class .*', DeprecationWarning, module='docutils.frontend'
 )
 
-__version__ = '7.3.0'
-__display_version__ = __version__  # used for command line version
-
 #: Version info for better programmatic use.
 #:
 #: A tuple of five elements; for Sphinx version 1.2.1 beta 3 this would be

sphinx/domains/cpp/_ids.py

@@ -1,46 +1,42 @@
-from __future__ import annotations
-
-import re
-
 """
-    Important note on ids
+Important note on ids
-    ----------------------------------------------------------------------------
+----------------------------------------------------------------------------
 
-    Multiple id generation schemes are used due to backwards compatibility.
+Multiple id generation schemes are used due to backwards compatibility.
-    - v1: 1.2.3 <= version < 1.3
+- v1: 1.2.3 <= version < 1.3
       The style used before the rewrite.
       It is not the actual old code, but a replication of the behaviour.
-    - v2: 1.3 <= version < now
+- v2: 1.3 <= version < now
       Standardised mangling scheme from
       https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangling
       though not completely implemented.
-    All versions are generated and attached to elements. The newest is used for
+All versions are generated and attached to elements. The newest is used for
-    the index. All of the versions should work as permalinks.
+the index. All of the versions should work as permalinks.
 
 
-    Signature Nodes and Tagnames
+Signature Nodes and Tagnames
-    ----------------------------------------------------------------------------
+----------------------------------------------------------------------------
 
-    Each signature is in a desc_signature node, where all children are
+Each signature is in a desc_signature node, where all children are
-    desc_signature_line nodes. Each of these lines will have the attribute
+desc_signature_line nodes. Each of these lines will have the attribute
-    'sphinx_line_type' set to one of the following (prioritized):
+'sphinx_line_type' set to one of the following (prioritized):
-    - 'declarator', if the line contains the name of the declared object.
+- 'declarator', if the line contains the name of the declared object.
-    - 'templateParams', if the line starts a template parameter list,
+- 'templateParams', if the line starts a template parameter list,
-    - 'templateParams', if the line has template parameters
+- 'templateParams', if the line has template parameters
   Note: such lines might get a new tag in the future.
-    - 'templateIntroduction, if the line is on the form 'conceptName{...}'
+- 'templateIntroduction, if the line is on the form 'conceptName{...}'
-    No other desc_signature nodes should exist (so far).
+No other desc_signature nodes should exist (so far).
 
 
-    Grammar
+Grammar
-    ----------------------------------------------------------------------------
+----------------------------------------------------------------------------
 
-    See https://www.nongnu.org/hcb/ for the grammar,
+See https://www.nongnu.org/hcb/ for the grammar,
-    and https://github.com/cplusplus/draft/blob/master/source/grammar.tex,
+and https://github.com/cplusplus/draft/blob/master/source/grammar.tex,
-    and https://github.com/cplusplus/concepts-ts
+and https://github.com/cplusplus/concepts-ts
-    for the newest grammar.
+for the newest grammar.
 
-    common grammar things:
+common grammar things:
     template-declaration ->
         "template" "<" template-parameter-list ">" declaration
     template-parameter-list ->
@@ -181,10 +177,10 @@ import re
           identifier
         | identifier "=" constant-expression
 
-    We additionally add the possibility for specifying the visibility as the
+We additionally add the possibility for specifying the visibility as the
-    first thing.
+first thing.
 
-    concept_object:
+concept_object:
     goal:
         just a declaration of the name (for now)
 
@@ -194,7 +190,7 @@ import re
         "template" "<" template-parameter-list ">"
         nested-name-specifier
 
-    type_object:
+type_object:
     goal:
         either a single type (e.g., "MyClass:Something_T" or a typedef-like
         thing (e.g. "Something Something_T" or "int I_arr[]"
@@ -209,20 +205,20 @@ import re
         decl-specifier-seq declarator
     Can start with a templateDeclPrefix.
 
-    member_object:
+member_object:
     goal: as a type_object which must have a declarator, and optionally
     with a initializer
     grammar:
         decl-specifier-seq declarator initializer
     Can start with a templateDeclPrefix.
 
-    function_object:
+function_object:
     goal: a function declaration, TODO: what about templates? for now: skip
     grammar: no initializer
        decl-specifier-seq declarator
     Can start with a templateDeclPrefix.
 
-    class_object:
+class_object:
     goal: a class declaration, but with specification of a base class
     grammar:
           attribute-specifier-seq[opt]
@@ -236,24 +232,28 @@ import re
         | access-specifier[opt] "virtual"[opt] base-type-specifier
     Can start with a templateDeclPrefix.
 
-    enum_object:
+enum_object:
     goal: an unscoped enum or a scoped enum, optionally with the underlying
           type specified
     grammar:
         ("class" | "struct")[opt] visibility[opt]
             attribute-specifier-seq[opt] nested-name (":" type)[opt]
-    enumerator_object:
+enumerator_object:
     goal: an element in a scoped or unscoped enum. The name should be
           injected according to the scopedness.
     grammar:
         nested-name ("=" constant-expression)
 
-    namespace_object:
+namespace_object:
     goal: a directive to put all following declarations in a specific scope
     grammar:
         nested-name
 """
 
+from __future__ import annotations
+
+import re
+
 udl_identifier_re = re.compile(r'''
     [a-zA-Z_][a-zA-Z0-9_]*\b   # note, no word boundary in the beginning
 ''', re.VERBOSE)

sphinx/ext/imgmath.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+__all__ = ()
+
 import base64
 import contextlib
 import re
@@ -40,8 +42,6 @@ logger = logging.getLogger(__name__)
 
 templates_path = path.join(package_dir, 'templates', 'imgmath')
 
-__all__ = ()
-
 
 class MathExtError(SphinxError):
     category = 'Math extension error'

sphinx/testing/util.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+__all__ = ('SphinxTestApp', 'SphinxTestAppWrapperForSkipBuilding')
+
 import contextlib
 import os
 import re
@@ -27,8 +29,6 @@ if TYPE_CHECKING:
 
     from docutils.nodes import Node
 
-__all__ = 'SphinxTestApp', 'SphinxTestAppWrapperForSkipBuilding'
-
 
 def assert_node(node: Node, cls: Any = None, xpath: str = "", **kwargs: Any) -> None:
     if cls:

sphinx/theming.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+__all__ = ('Theme', 'HTMLThemeFactory')
+
 import configparser
 import contextlib
 import os
@@ -27,8 +29,6 @@ else:
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
 
-__all__ = 'Theme', 'HTMLThemeFactory'
-
 logger = logging.getLogger(__name__)
 
 _NO_DEFAULT = object()