[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>

11 files changed, 27 insertions, 33 deletions

diff --git a/doc/data/messages/n/non-ascii-file-name/bad/bàd.py b/doc/data/messages/n/non-ascii-file-name/bad/bàd.py
new file mode 100644
index 000000000..bc59418e1
--- /dev/null
+++ b/doc/data/messages/n/non-ascii-file-name/bad/bàd.py
@@ -0,0 +1 @@
+# [non-ascii-file-name]
diff --git a/doc/data/messages/n/non-ascii-file-name/bad/not_bétter.py b/doc/data/messages/n/non-ascii-file-name/bad/not_bétter.py
new file mode 100644
index 000000000..bc59418e1
--- /dev/null
+++ b/doc/data/messages/n/non-ascii-file-name/bad/not_bétter.py
@@ -0,0 +1 @@
+# [non-ascii-file-name]
diff --git a/doc/data/messages/n/non-ascii-file-name/details.rst b/doc/data/messages/n/non-ascii-file-name/details.rst
deleted file mode 100644
index ab8204529..000000000
--- a/doc/data/messages/n/non-ascii-file-name/details.rst
+++ /dev/null
@@ -1 +0,0 @@
-You can help us make the doc better `by contributing <https://github.com/PyCQA/pylint/issues/5953>`_ !
diff --git a/doc/data/messages/n/non-ascii-file-name/good.py b/doc/data/messages/n/non-ascii-file-name/good.py
deleted file mode 100644
index c40beb573..000000000
--- a/doc/data/messages/n/non-ascii-file-name/good.py
+++ /dev/null
@@ -1 +0,0 @@
-# This is a placeholder for correct code for this message.
diff --git a/doc/data/messages/n/non-ascii-file-name/good/bad.py b/doc/data/messages/n/non-ascii-file-name/good/bad.py
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/doc/data/messages/n/non-ascii-file-name/good/bad.py
diff --git a/doc/data/messages/n/non-ascii-file-name/good/not_better.py b/doc/data/messages/n/non-ascii-file-name/good/not_better.py
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/doc/data/messages/n/non-ascii-file-name/good/not_better.py
diff --git a/doc/data/messages/n/non-ascii-file-name/related.rst b/doc/data/messages/n/non-ascii-file-name/related.rst
new file mode 100644
index 000000000..9c7cecacf
--- /dev/null
+++ b/doc/data/messages/n/non-ascii-file-name/related.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>`_
diff --git a/doc/user_guide/checkers/features.rst b/doc/user_guide/checkers/features.rst
index 6dfb222a8..ac17fabb6 100644
--- a/doc/user_guide/checkers/features.rst
+++ b/doc/user_guide/checkers/features.rst
@@ -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
diff --git a/doc/user_guide/configuration/all-options.rst b/doc/user_guide/configuration/all-options.rst
index ff5e942b8..21c58a057 100644
--- a/doc/user_guide/configuration/all-options.rst
+++ b/doc/user_guide/configuration/all-options.rst
@@ -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:**  ``()``
 
diff --git a/pylint/checkers/non_ascii_names.py b/pylint/checkers/non_ascii_names.py
index 6e3628063..455e575ad 100644
--- a/pylint/checkers/non_ascii_names.py
+++ b/pylint/checkers/non_ascii_names.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"
diff --git a/tests/functional/n/non_ascii_name/non_ascii_name_loł.txt b/tests/functional/n/non_ascii_name/non_ascii_name_loł.txt
index eefaa197a..b2f82cde4 100644
--- a/tests/functional/n/non_ascii_name/non_ascii_name_loł.txt
+++ b/tests/functional/n/non_ascii_name/non_ascii_name_loł.txt
@@ -1 +1 @@
-non-ascii-file-name:1:0:None:None::"File name ""non_ascii_name_loł"" contains a non-ASCII character. PEP 3131 only allows non-ascii identifiers, not file names.":HIGH
+non-ascii-file-name:1:0:None:None::"File name ""non_ascii_name_loł"" contains a non-ASCII character.":HIGH