Description
In our README files, we use HTML markup to demarcate sections. This markup is useful in two ways: (1) it allows us to more readily perform transformations on Markdown content, as we can often use regexp which explicitly target opening <section> tags with a desired class and a corresponding comment and (2) it allows straightforward publishing to the documentation website.
It has, however, become a common occurrence for our READMEs to become "corrupted" with new contributors failing to insert closing tags or inserting content where it shouldn't be.
This RFC proposes adding linting to enforce both valid HTML markup and that sections are properly inserted.
-
At a bare minimum, each opening
<section>tag should have a corresponding</section>. Meaning, no orphaned<section>tags. -
At the next level of complexity, each opening
<section class="foo">tag should have a corresponding<!-- /.foo -->closing comment. -
At the highest level of complexity, we have lint rules which enforce expected nesting. Meaning, e.g., a C section should have usage, examples, notes, and maybe a couple of other sections, but never a "related packages" section. Or in other words, certain sections should always be at the same level, such as usage, notes, examples, C, references, related, and links.
While the first two lint capabilities can be considered stdlib agnostic, the last capability is heavily specific to stdlib.
Whether each capability should be a separate rule OR everything should be combined into a single rule is up to the implementor. At the least, 1-2 can likely be combined. 3, however, may be best left to a separate rule.
That said, (3) should also be straightforward to implement in its own right. Namely, visit each HTML node. Resolve the class, if present. Map each new section to an object. When you open a new class, create a new object. When you close a section, close the object. The result may be something like
[
{ "name": "intro" , "children": [...] },
{ "name": "usage", "children": [...] },
{ "name": "examples", "children": [...] },
{ "name": "c", "children": [
{ "name": "intro", "children": [...] },
{ "name": "usage", "children": [...] },
{ "name": "notes", "children": [... ] },
{ "name": "examples", "children": [...] }
},
{ "name": "references", "children": [...] },
{ "name": "related", "children": [... ] },
{ "name": "links", "children": [...] }
]
Once the HTML structure is derived, it should be possible to apply validation, either via a JSON schema or programmatically.
Time with AI: 2h 30min
TIme without AI: 3h
Prior Task Exposure: 3
External Resource Needs: 2