[doc] Add an example for 'non-ascii-file-name' (#8340)

And move links to related.rst

Co-authored-by: Mark Byrne <31762852+mbyrnepr2@users.noreply.github.com>

Author: Pierre-Sassoulas

doc/data/messages/n/non-ascii-file-name/bad/bàd.py

@@ -0,0 +1 @@
+# [non-ascii-file-name]

doc/data/messages/n/non-ascii-file-name/bad/not_bétter.py

@@ -0,0 +1 @@
+# [non-ascii-file-name]

doc/data/messages/n/non-ascii-file-name/details.rst

@@ -0,0 +1,3 @@
+- `PEP 489 <https://peps.python.org/pep-0489/#export-hook-name>`_
+- `PEP 672 <https://peps.python.org/pep-0672/#confusing-features>`_
+- `Python issue 20485 <https://bugs.python.org/issue20485>`_

doc/data/messages/n/non-ascii-file-name/good.py

@@ -728,13 +728,10 @@ Verbatim name of the checker is ``nonascii-checker``.
 
 Nonascii-Checker checker Messages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-:non-ascii-file-name (W2402): *%s name "%s" contains a non-ASCII character. PEP 3131 only allows non-ascii identifiers, not file names.*
-  Some editors don't support non-ASCII file names properly. Even though Python
-  supports UTF-8 files since Python 3.5 this isn't recommended for
-  interoperability. Further reading: -
-  https://peps.python.org/pep-0489/#export-hook-name -
-  https://peps.python.org/pep-0672/#confusing-features -
-  https://bugs.python.org/issue20485
+:non-ascii-file-name (W2402): *%s name "%s" contains a non-ASCII character.*
+  Under python 3.5, PEP 3131 only allows non-ascii identifiers, not file
+  names.Since Python 3.5, even though Python supports UTF-8 files, some editors
+  or tools don't.
 :non-ascii-name (C2401): *%s name "%s" contains a non-ASCII character, consider renaming it.*
   Used when the name contains at least one non-ASCII unicode character. See
   https://peps.python.org/pep-0672/#confusing-features for a background why
@@ -1363,8 +1360,8 @@ Variables checker Messages
 :unused-variable (W0612): *Unused variable %r*
   Used when a variable is defined but not used.
 :global-variable-not-assigned (W0602): *Using global for %r but no assignment is done*
-  When a variable defined in the global scope is modified in an inner scope, the
-  'global' keyword is required in the inner scope only if there is an
+  When a variable defined in the global scope is modified in an inner scope,
+  the 'global' keyword is required in the inner scope only if there is an
   assignment operation done in the inner scope.
 :undefined-loop-variable (W0631): *Using possibly undefined loop variable %r*
   Used when a loop variable (i.e. defined by a for loop or a list comprehension

doc/data/messages/n/non-ascii-file-name/good/bad.py

@@ -174,13 +174,6 @@ Standard Checkers
 **Default:**  ``(3, 10)``
 
 
---source-roots
-""""""""""""""
-*Add paths to the list of the source roots. The source root is an absolute path or a path relative to the current working directory used to determine a package namespace for modules located under the source root.*
-
-**Default:**  ``()``
-
-
 --recursive
 """""""""""
 *Discover python modules and packages in the file system subtree.*
@@ -202,6 +195,13 @@ Standard Checkers
 **Default:**  ``True``
 
 
+--source-roots
+""""""""""""""
+*Add paths to the list of the source roots. Supports globbing patterns. The source root is an absolute path or a path relative to the current working directory used to determine a package namespace for modules located under the source root.*
+
+**Default:**  ``()``
+
+
 --suggestion-mode
 """""""""""""""""
 *When enabled, pylint would attempt to guess common misconfiguration and emit user-friendly hints instead of false-positive error messages.*
@@ -279,6 +279,8 @@ Standard Checkers
 
    score = true
 
+   source-roots = []
+
    suggestion-mode = true
 
    unsafe-load-any-extension = false
@@ -1000,7 +1002,7 @@ Standard Checkers
 
 --preferred-modules
 """""""""""""""""""
-*Couples of modules and preferred modules, separated by a comma. Submodules may also be specified using '.' syntax (for ex. 'os.path').*
+*Couples of modules and preferred modules, separated by a comma.*
 
 **Default:**  ``()``
 

doc/data/messages/n/non-ascii-file-name/good/not_better.py

@@ -43,22 +43,14 @@ class NonAsciiNameChecker(base_checker.BaseChecker):
         ),
         # First %s will always be "file"
         "W2402": (
-            (
-                '%s name "%s" contains a non-ASCII character. PEP 3131 only allows '
-                "non-ascii identifiers, not file names."
-            ),
+            '%s name "%s" contains a non-ASCII character.',
             "non-ascii-file-name",
             (
                 # Some = PyCharm at the time of writing didn't display the non_ascii_name_loł
-                # files and had big troubles with git.
-                # Probably only a bug shows the problem quite good.
-                # That's also why this is a warning and not only a convention!
-                "Some editors don't support non-ASCII file names properly. "
-                "Even though Python supports UTF-8 files since Python 3.5 this isn't "
-                "recommended for interoperability. Further reading:\n"
-                "- https://peps.python.org/pep-0489/#export-hook-name\n"
-                "- https://peps.python.org/pep-0672/#confusing-features\n"
-                "- https://bugs.python.org/issue20485"
+                # files. That's also why this is a warning and not only a convention!
+                "Under python 3.5, PEP 3131 allows non-ascii identifiers, but not non-ascii file names."
+                "Since Python 3.5, even though Python supports UTF-8 files, some editors or tools "
+                "don't."
             ),
         ),
         # First %s will always be "module"