Automate documentation creation

[ilyavolodin]

I would like to streamline documentation create a bit. Now that we have schemas, I would like to create a built task that would export schemas and append available options at the end of each rule documentation.I also think we can take it even further, in order to help people search google for errors they get as a result of linting, I think we should include all possible error messages into exportable object that would also be appended to rule documentation. We also can remove "README.md" all together, and generated it from exported object. I will create a WIP pull request with proposed changes for a few rules.

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[lo1tuma]

Some error messages are created dynamically, so I don't think it is possible to automatically document every possible error message.

[ilyavolodin]

Most of the error messages are created by substitution, that's why I used {0} in my example. If the messages is completely generated (I think there might be one or two rules that do that), then oh well... It's better to have most of the messages then none.

[nzakas]

I think this might end up being a bit too pie-in-the-sky, but feel free to explore. :)

[IanVS]

append available options at the end of each rule documentation.

It seems to me like option documentation is important enough that it should be fairly early in the rule docs. Imagine needing to scroll to the very bottom of object-curly-spacing to find the options.

[ilyavolodin]

Agree. But without knowing how the document is structured, it's hard to insert auto-created pieces in the middle.

[IanVS]

Could we manually put a placeholder in all the rule docs? Perhaps stub out the header "### Rule Options" or similar?

[mysticatea]

Or I think to generate TOC automatically is good for large rules.

[IanVS]

I agree, looks like it was discussed in #1073, but I don't see it live on the site.

[ilyavolodin]

It is live. Or at least anchors on all headers are. If you mouse over any header, you should see a link icon pop up.

[IanVS]

You're right, I wasn't clear. The anchors are there, but there are no TOC.

[nzakas]

I don't think there are enough sections on rule docs to have a TOC... Most have three, four sections at most. I'm not a big fan of boilerplate like that.

[IanVS]

This is getting off topic, but how about some of the larger pages like Configuring ESLint?

[nzakas]

I think the larger pages should be broken up into smaller ones

[kaicataldo]

Is this still being worked on?

[ilyavolodin]

Second part is done (Index.md). The rest of it is controversial enough to hold off for now.