Invitation to collaborate

[edg2s]

Apologies for the @-spam, I have tagged ESLint plugin authors here who I identified as potential users of this documentation builder (i.e. your plugin was part of our analysis in #7).

I have been working on this tool for building ESLint plugin documentation and we have been using it at Wikimedia for eslint-plugin-no-jquery and eslint-plugin-mediawiki.

In those cases it is running fully automated off a master template (index.ejs) but it can also be used with existing documentation, allowing you to drop in automatically generated blocks incrementally. For this I have written a short migration guide.

Feature highlights:

• Generates "Examples of (in)correct code" blocks automatically from test cases.
  • Test cases can be selective excluded from these blocks if required
  • Also generates examples of how code is fixed for fixable rules, showing before and after.
• Generates boilerplate messages such as "This rule is deprecated (and replaced by...)", "This rule is included in the recommended config" and "This rule is fixable"
• Generates links to rule and test source.

Examples:

• Rule in eslint-plugin-no-jquery
• Rule in eslint-plugin-mediawiki
• Sample test case output

Thanks for taking a look, and apologies again if this is not of any interest to you, Ed

[edg2s]

CC @benmosher, @evcohen, @j-f1, @lo1tuma, @mysticatea, @platinumazure, @sindresorhus, @xjamundx, @yannickcr

[j-f1]

Neat! This reminds me of my eslint-docs package, which had similar functionality, although yours looks much more complete. I’m not super involved in the ESLint space anymore but I’d be happy to add a message to the top of that repo linking here. (I’d also be happy to give you the eslint-docs name if you’d like it)

[edg2s]

@j-f1 Thanks for the message. I did actually stumble across that package via https://github.com/dustinspecker/awesome-eslint, and had a poke around due it's similarity.

A link would be great and more than enough, thanks! Also if you have any thoughts on the approach used here they would be welcome.

Thanks,

[lo1tuma]

I had only a brief look so far, but I really like the idea of this project.

I few things that come to my mind:

• Excluding (in)correct examples could become a lot of work for rule tests that test a lot of edge cases. Usually I want to have only very few explanatory examples in the documentation and not all of the edge cases which are tested. So maybe it would be easier to explicitly flag which test-cases should be in the documentation.
• Personally I’m not a big fan of storing generated code in git (or at least in the same branch as the source code lives). Are there any plans to generate HTML output, so the documentation can be easily deployed to github pages?

[edg2s]

So maybe it would be easier to explicitly flag which test-cases should be in the documentation.

Good idea, that shouldn't be hard to do. Filed as #80.

Are there any plans to generate HTML output, so the documentation can be easily deployed to github pages?

The ejs templates can output anything, and in fact are intended to output HTML (they have native HTML escaping functions). We could add a set of default HTML templates but given end users would probably want to customise them that may not be that useful. Do you have any examples in mind that would make for a good default?