Better message documentation: add various templates to be able to handle all messages

[Pierre-Sassoulas]

Current problem

In #5953, some messages do not follow the generic template with good code and bad code or can't be triggered easily. Among them:

internal errors

• astroid-error

configuration errors

• b/bad-plugin-value

Code that require multiple examples

There already are multiple example mixed in the existing files.

• missing-final-newline
• A <= symbol < D [doc] Use the new multiple file template for A <= message-symbol < D  #9006
• D < symbol < Z TODO

Messages that depend on multiple file or dependency to trigger

• import-error
• cyclic-import Add documentation for cyclic-import #8322
• import-self
• d/duplicate-code
• n/non-ascii-file-name [doc] Add an example for 'non-ascii-file-name' #8340

other

• too-many-lines (Hard and meaningless to do parity behavior between bad/good, creating a new file is often the solution)
• b/bad-file-encoding (Need to be handled by the generating part)
• c/c-extension-no-member (This one is going to be hard to trigger, not for beginner)
• r/relative-beyond-top-level

Desired solution

We need to create templates for those message so we can generate the proper skeleton for them.

• For internal errors, probably only a message stating "You should never encounter this one, please open an issue if you do"
• For configuration errors a bad.toml and good.toml with some tests close to what we do for good.py / bad.py (maybe running on a dummy empty file)
• For code that require multiple examples, handle multiple example more gracefully than right now (we just add a longer example with multiple part)

Additional context

The Sphinx extension that generates these pages needs to be modified see #5953 (comment)

[ollie-iterators]

I think it would be beneficial if the errors that need to have a different template with good.py and bad.py were moved into this or a separate PR so that people could focus on the issues that can currently have documentation added.

There could also be an explanation of what needs to be added if different things need to be added for different errors.

[ollie-iterators]

An alternative suggestion is to add notes to each issue that needs to have a different template on #5953.

[Pierre-Sassoulas]

add notes to each issue that needs to have a different template on #5953.

That's what I'm trying to do in the tasklist of the description in the first comment, check it out :)

[ollie-iterators]

Do you still think that unexpected-line-ending-format should be included in this list? Because it has not had a comment for that

[Pierre-Sassoulas]

It's done in #8255

[Pierre-Sassoulas]

It's possible to do some messages without a new template by removing good.py and bad.py and simply adding a details.rst and related.rst.

[ollie-iterators]

import-error and import-self both have documentation

[ollie-iterators]

I noticed that the error: https://bugs.python.org/issue20485 that is mentioned in the documentation for non-ascii-file-name has been fixed.

[Pierre-Sassoulas]

Nice catch, it look like its been fixed for python > 3.4 (python/cpython#64684 (comment)).

[DanielNoord]

We still need support for configuration file messages, but with #8287 we now have support for multi-file messages 😄

[ollie-iterators]

I think it would be beneficial if the errors that need to have a different template with good.py and bad.py were moved into this or a separate PR so that people could focus on the issues that can currently have documentation added.

There could also be an explanation of what needs to be added if different things need to be added for different errors.

I see that the errors that needed to have a different template were moved here.

[ollie-iterators]

I'm trying to use the duplicate-code example as a way to do too-many-lines (Don't worry @DanielNoord, I mentioned you in the commit), and it keeps saying that there is an "AssertionError: There should be at least one warning raised for 'bad' examples." I have max-module-lines at 15, which should cause an issue with orange.py and not for any other file but, as I said before, pytest still says that "there should be at least one warning raised ..."

NOTE: I just changed orange.py to bad.py and the code was able to find the too-many-lines error. This could be an issue with how the new template code was made.

[ollie-iterators]

Also, how would one go about removing non-ascii-file-name from pylint?

[Pierre-Sassoulas]

The too-many-lines examples could work without a bad/good example imo.

For non-ascii-file-name, we can either remove it or add a py-version guard. I would be in favor of removing as python 3.4 is long gone: for that there is a DELETED_MESSAGES constant to upgrade and everything related to the check should be removed (related: #6670).

[Pierre-Sassoulas]

Closing as completed as the template now exists and we can move and deal with the remaining messages in #5953