[Docs] extensions, order: improve documentation

[Xunnamius]

Resolves #2897
Related to #3104 and #3105
Potentially related to #2708, #2304, #2540

I can slice and dice this PR in whatever way is most useful.

The changes to the import/extensions documentation (preview) are not so massive and should merge cleanly.

The changes to the import/order documentation (preview), however, are much more extensive. I've been referring back to these docs on and off for several months as I've tweaked my linter configurations, and every time I do I pretty much leave confused and fall back on stepping through eslint-plugin-import's source to see what's actually happening. Along with documenting the new functionality introduced in #3104, this PR attempts to demystify import/order's documentation in the following ways:

• There is no documentation describing how an import is grouped. What classifies an import as "external" vs "internal" vs "builtin"? What does "sibling" or "parent" actually mean? Every time I come back to these docs, I find myself looking for a technical description that doesn't exist and so I ultimately guess, which leads to problems 😅. For this PR, I've looked through the rule's source and have attempted to describe the grouping algorithm with specificity. Since I've only spent a day or so with this repo's source code, it may not be totally accurate and should be scrutinized for mistakes.

• Some of the examples don't work. They've been fixed (and [New] order: allow intragroup sorting of type-only imports via sortTypesGroup #3104 adds corresponding tests for them).

• The options headings contain their type description alongside their names. This means references into this document from the wider web will break whenever one of the settings is tweaked. I've encountered several of these "dead links" over time. Worse, they make for truly ugly headings. I believe it best to instead use short simple headings that are unlikely to change, such as each option's full name alone.

• The type descriptions of the options (e.g. [array of this or that]) and their defaults are vague and confusing and are documented inconsistently. Some of the descriptions of the functionality of each option are similarly confusing, such as the description for pathGroups. In my review of the issues literature, I found I was not alone in this. This is my stab at making this aspect of the documentation more approachable.

• There are several "gotchas" and "footguns" when using some of these options. In this PR, these are now shouted out using GFM alert syntax.

• Option sections are formatted inconsistently. Several of the examples and their descriptions are formatted differently than the others. This PR ensures all sections are using consistent formatting and structure.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 95.17%. Comparing base (a20d843) to head (31b786b).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3106      +/-   ##
==========================================
- Coverage   95.28%   95.17%   -0.12%     
==========================================
  Files          83       83              
  Lines        3584     3583       -1     
  Branches     1252     1251       -1     
==========================================
- Hits         3415     3410       -5     
- Misses        169      173       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[ljharb]

@Xunnamius just curious; did you use an LLM in any part of your PR description?

[Xunnamius]

@Xunnamius just curious; did you use an LLM in any part of your PR description?

@ljharb Haha, no 🤭. I write the docs for the fancy linear algebra, it doesn't madlib my docs for me. I hope my writing doesn't read like slop!

And thanks for taking a look at the PR 👍

[ljharb]

@Xunnamius glad to hear it, it'd have been the first time it wasn't immediately obvious to me :-p your writing is fine :-)

[jftanner]

Should this have been merged before the implementation?
Answer: Yes

I just spent entirely too much time trying to figure out why my new ESLint config throws Unexpected property "sortTypesAmongThemselves".. 🤣

[ljharb]

@jftanner this commit isn't released yet - you always need to check the docs on the version tag you're using, not on master/main :)

[jftanner]

Ah. My bad. Google took me to main, and I'm used to living in a semantic-release world where main == latest.

Carry on. :)

[ljharb]

actually, @Xunnamius, i think #3106 erroneously included sortTypesAmongThemselves and newlines-between-types documentation. I'll make a commit removing them.

[Xunnamius]

@ljharb My goal was to isolate all documentation changes to a documentation-only PR, mostly because I thought they warranted further discussion on their own merits, but also because I find it's easier for me to write good documentation (wrt section order, refs between sections, etc) in one pass.

EDIT: I can split the docs changes between the feature PRs since it's already written, let me know

[ljharb]

Understood, but I prefer each feature to land complete, with its own docs :-) it should be pretty easy to revert my commit during your rebase.

[Xunnamius]

Gotcha! Will take a look tomorrow