Document each rule separately

[PCManticore]

We can do a better job at documenting our rules. Currently we're employing an automatic approach, in which we generate a restructuredText document from the help messages of the rules, but this means we can't explain them properly, we can't put actual examples in the help messages and we can't version them (when they were added, removed etc)

We can take same inspiration from how the folks from ESLint are doing things: http://eslint.org/docs/rules/

[moylop260]

+1

[iselind]

+1
Anyone know how ESLint generates http://eslint.org/docs/rules/, i cannot imagine it being hand crafted...

[moylop260]

They have a MarkDown by each rule: https://github.com/eslint/eslint/tree/master/docs/rules
The file is named as the rule.

• Build the webpage
• Checking rules doc

[iselind]

I was more thinking about the markdown file itself, seems handcrafted to me:
https://github.com/eslint/eslint/pull/6881/files#diff-1a27b1465768f431cef37a2fcfa5e88f

[iselind]

Are the msgs dict in the checked assembed into some data structure in pylint? If so, could we perhaps use that as a base to generate some markdown table with all the warnings that pylint can generate.

Even if it's not similar to what ESLint has it's a small step in that direction, still better than nothing.

[PCManticore]

We already do that. That is how https://pylint.readthedocs.io/en/latest/features.html is generated, completely automatic. The problem is we cannot go too much in details when documenting a rule, since the initial purpose of the structure we are using is to show a short help message when calling pylint --help-msg=message id. In short, we cannot be too verbose, which is why I want to document the rules separately and a bit more complete than what we are doing now.

[iselind]

Perhaps as a start you don't have to go into too much details on each and every rule. Those that need some clarification could get a manual markdown file as need araise, somewhere in the code tree.The https://pylint.readthedocs.io/en/latest/features.html generator can look through that directory and create a link if a matching markdown file exists.

[PCManticore]

This could work, we could generate those files when building the documentation, using as a content the help message. If the files already exist, we can assume they are already updated, thus we can go and put additional information where necessary.

[iselind]

or you could have a separate page with 'clarifications' for the rules that need it and the docs could link to those clarifications if they exist. That way you would only need to maintain the clarifications and still generate the 'normal' rules information.

[PCManticore]

I would incline to have them separated, rather than going with a clarifications page. Anyway, the generation is kind of easy, we just need to implement it based on the current features.rst generation.

[iselind]

You mean to just augment the current features page with at least one new section for each rule with examples, clarifications, and when the rule in its current form was introduced in pylint. Correct?

I'm not sure what you want/mean there...

[PCManticore]

Oh, sorry about being confusing.

What I was suggesting was something along these lines:

• generating the files per each rule when pylint_features.py runs when building the documentation
• referring those files in another .rst file, which contains the rule definitions and whatnot (the file can be generated by pylint_features as well)
• if a file already exists, don't regenerate it. This means we can modify a new file by annotating it with whatever extra information we need.
• the result is that we don't have to maintain the rule files manually, only we can intervene in those places we need.