A longstanding issue of pylint has been that there is little documentation about some of the messages and why they are emitted. For some messages the short message that is displayed is not enough to make explicit what needs to be changed or what is considered wrong.
With the closure of #5527 and the merge of #5934 we have now set up a system that allows us to do so!
We have also received the okay from @vald-phoenix to base this additional documentation on their wonderful pylint-errors project.
However, now we need some community help to write this documentation. If you'd like to help out and help future users of pylint understand what pylint is telling them, please continue reading.
Details
Two examples of how the new documentation is supposed to look like can be seen [here](https://pylint.pycqa.org/en/latest/messages/error/yield-inside-async-function.html) and [here](https://pylint.pycqa.org/en/latest/messages/convention/empty-docstring.html).
How to create such pages? The process is quite straightforward.
Within the doc/data/messages directory you can find various subdirectories. These are the letters of the alphabet. Within these directories you will find directories for each message that pylint can emit. These directories contain the data from which these pages are build.
To help build a new page:
- Create a new directory for the message you are working on. For example
doc/data/messages/a/abstract-class-instantiated.
- Look at the page for the message in the
pylint-errors repo. For example here. If the message is not documented yet you will need to come up with examples yourself.
- Create a
good.py document in which you include a short code example that shows of good code that won't trigger the message. You can base this on pylint-error.
- Create a
bad.py document in which you include a short bad code example. On the line that is supposed to emit the message please add a # [abstract-class-instantiated] comment. See these examples.
- If necessary create a
pylintrc file. Here you can include configuration options for pylint like loading of optional checkers. See doc/data/messages/c/confusing-consecutive-elif/pylintrc for example.
- If necessary create a
details.rst file. Here you can place additional details in .rst format that will be displayed on the page. Note that some of the details included on the pylint-error pages are already included in our Message or Description sections.
- If necessary create a
related.rst file. Here you can place .rst style links to external sources that are relevant for the message. Generally we do not include the links to Test Cases and the Issue Tracker that pylint-error provides as they can break easily.
- If you're basing yourself on the work in the
pylint-errors repo it is appreciated if you add the following line to your commits:
Co-authored-by: Vladyslav Krylasov <vladyslav.krylasov@gmail.com> (or any of the other contributors to that project you're basing yourself on!
- To make sure the code examples are correct, you can run
pytest doc/test_messages_documentation.py.
- Create a PR. A changelog entry is not necessary :)
Two examples of how to do this can be found in #5934.
To make this work somewhat manageable please do not add more than 5 messages in one PR, as otherwise it will be impossible to review the changes correctly.
The big list of messages without any documentation:
As of the 2023-09-09.
Related pull requests:
#5992, #5994, #5995, #6016, #5993, #5996, #6150, #5997, #6026, #6086, #6000, #6088, #6021, #6002, #6090, #6164, #6166, #6020, #6104, #6103, #6167, #6105, #6106, #6107, #6156, #6157, #6131, #6009, #6139, #6083, #6092, #6200, #6203, #6204, #6237, #6159, #6243, #6250, #6115, #6248, #6249, #6339, #6341, #6342, #6343, #6340, #6344, #6345, #6262, #6263, #6264, #6265, #6080, #6079, #6206, #6245, #6205, #6158, #6114, #6114, #6201, #6160, #6149, #6238, #6152, #6153, #6133, #6244, #6230, #6232, #6151, #6247, #6132, #6239, #6240, #6472, #6699, #6679, #6460, #6697, #6630, #6637, #6698, #6472, #6586, #6541, #6472, #6669, #6618, #6690, #6619, #6620, #6621, #6659, #6576, #6574, #6540, #6700, #6590, #6701, #6591, #6583, #6562, #6585 #9042
#7897
(List of related pull request is not exhaustive)
A longstanding issue of
pylinthas been that there is little documentation about some of the messages and why they are emitted. For some messages the short message that is displayed is not enough to make explicit what needs to be changed or what is considered wrong.With the closure of #5527 and the merge of #5934 we have now set up a system that allows us to do so!
We have also received the okay from @vald-phoenix to base this additional documentation on their wonderful pylint-errors project.
However, now we need some community help to write this documentation. If you'd like to help out and help future users of
pylintunderstand whatpylintis telling them, please continue reading.Details
Two examples of how the new documentation is supposed to look like can be seen [here](https://pylint.pycqa.org/en/latest/messages/error/yield-inside-async-function.html) and [here](https://pylint.pycqa.org/en/latest/messages/convention/empty-docstring.html).How to create such pages? The process is quite straightforward.
Within the
doc/data/messagesdirectory you can find various subdirectories. These are the letters of the alphabet. Within these directories you will find directories for each message thatpylintcan emit. These directories contain the data from which these pages are build.To help build a new page:
doc/data/messages/a/abstract-class-instantiated.pylint-errorsrepo. For example here. If the message is not documented yet you will need to come up with examples yourself.good.pydocument in which you include a short code example that shows of good code that won't trigger the message. You can base this onpylint-error.bad.pydocument in which you include a short bad code example. On the line that is supposed to emit the message please add a# [abstract-class-instantiated]comment. See these examples.pylintrcfile. Here you can include configuration options forpylintlike loading of optional checkers. Seedoc/data/messages/c/confusing-consecutive-elif/pylintrcfor example.details.rstfile. Here you can place additional details in .rst format that will be displayed on the page. Note that some of the details included on thepylint-errorpages are already included in ourMessageorDescriptionsections.related.rstfile. Here you can place .rst style links to external sources that are relevant for the message. Generally we do not include the links toTest Casesand theIssue Trackerthatpylint-errorprovides as they can break easily.pylint-errorsrepo it is appreciated if you add the following line to your commits:Co-authored-by: Vladyslav Krylasov <vladyslav.krylasov@gmail.com>(or any of the other contributors to that project you're basing yourself on!pytest doc/test_messages_documentation.py.Two examples of how to do this can be found in #5934.
To make this work somewhat manageable please do not add more than 5 messages in one PR, as otherwise it will be impossible to review the changes correctly.
The big list of messages without any documentation:
As of the 2023-09-09.
Related pull requests:
#5992, #5994, #5995, #6016, #5993, #5996, #6150, #5997, #6026, #6086, #6000, #6088, #6021, #6002, #6090, #6164, #6166, #6020, #6104, #6103, #6167, #6105, #6106, #6107, #6156, #6157, #6131, #6009, #6139, #6083, #6092, #6200, #6203, #6204, #6237, #6159, #6243, #6250, #6115, #6248, #6249, #6339, #6341, #6342, #6343, #6340, #6344, #6345, #6262, #6263, #6264, #6265, #6080, #6079, #6206, #6245, #6205, #6158, #6114, #6114, #6201, #6160, #6149, #6238, #6152, #6153, #6133, #6244, #6230, #6232, #6151, #6247, #6132, #6239, #6240, #6472, #6699, #6679, #6460, #6697, #6630, #6637, #6698, #6472, #6586, #6541, #6472, #6669, #6618, #6690, #6619, #6620, #6621, #6659, #6576, #6574, #6540, #6700, #6590, #6701, #6591, #6583, #6562, #6585 #9042
#7897
(List of related pull request is not exhaustive)