refactor doc generation

[devoncarew]

This is currently a speculative refactor of the linter's doc generation.

This is generally in the spirit of #2301 (though I should probably open a more specific issue). The main motivation for me here is that the current linter docs (https://dart-lang.github.io/linter/lints/index.html) don't have either a dart.dev style or a github style; they have their own separate branding.

Some potential changes:

• no longer generate html docs from this repo
• have the analysis server link to the newer dart.dev docs for lint codes instead of the above linter ones
• have the current linter doc pages all redirect to the dart.dev page (to avoid breaking any existing search results / pointers to those docs)
• update the generation here to write (simpler) markdown pages; these could be committed to the repo, and would then be auto-rendered as std github markdown
• update the generation to be more deterministic (to not rely on downloading from other repos at generation time, but instead just render w/ the info available in the current repo).

Some sample generated markdown files included w/ this PR.

[coveralls]

Coverage: 95.557%. Remained the same when pulling 44f6fe5 on gen_markdown into a7ff636 on main.

[devoncarew]

@parlough - the dart.dev site now includes lint codes? Just codes+docs for stable lints?

[parlough]

Yep, dart.dev includes linter rules, their descriptions, status, and version support at https://dart.dev/tools/linter-rules. This includes both stable and experimental or unreleased rules. The format isn't amazing as there are plans for a new structure with some consolidation with diagnostic messages, so I decided to focus on that instead.

It seems the current thinking is to split linter documentation by two separate use cases (on dart.dev):

• The diagnostics themselves and how to fix them, rewritten in the same style as the diagnostic messages (☂ [Tracking] Restructure diagnostic message docs site-www#4499). They would be combined with other diagnostics (Combine Linter rules and Diagnostic messages pages? site-www#4498), likely with each diagnostic on its own page rather than one big one like now. These would be the pages tools would link to, and likely wouldn't be in the sidenav of the site.
• Newly written "Why" documentation for each lint, for users determining lints to enable. This would also include things like version support, lint status, what sets the lint is in, links to Effective Dart, etc. These could have a link back to their diagnostic information as well. This content would be discoverable on the sidenav of the site.
• These may be declared in the code like now or in a separate yaml file like the diagnostics, not sure. But either way, we would likely introduce some GitHub workflow to check for updates and open a PR to update the source file as needed.

Some extra context on this idea: dart-lang/site-www#4498, dart-lang/site-www#4499

I'd be happy to discuss more and create a formal plan if it's the direction we want to go. It's my intended focus after finishing some flutter.dev work :)

[devoncarew]

Thanks for the info! I see from one of the linked issues that one of the goals is deprecate github.io/linter, which resonates w/ me.

I think generated markdown files here still provide some value, but am not sure that I can really describe why. Perhaps the value is marginal enough to not be worth the maintenance cost.

It looks like we have stable 'go' links for diagnostic codes (https://github.com/dart-lang/site-www/blob/main/firebase.json#L97). Are these what IDEs would point to? Do we do that today? If no, we may want to update things, so that we could have links we can update as and if the lint docs locations change.

[parlough]

Yep, that's what the analysis server uses today for diagnostics.

With the discussed changes this would be still be the intended access point for the original diagnostics, and now the new access point for lint diagnostics as well.

One exists for lints as well (/lints/<code>), but this one will likely lead to the sales pitch rather than the diagnostic information in the future.

[parlough]

I thought about updating the analysis server to link to the dart.dev linter rule docs rather than github.io/linter, but I thought it might be best to wait until we've consolidated them with the other diagnostics.

[bwilkerson]

For what it's worth, I already have a significant number of the linter docs rewritten to use the same format as the analyzer diagnostic messages.

[pq]

I thought about updating the analysis server to link to the dart.dev linter rule docs rather than github.io/linter, but I thought it might be best to wait until we've consolidated them with the other diagnostics.

I think it's a good idea to wait at least until we're feel like we've converged on a link format that feels stable.

Maybe we should break out a separate issue for that?

/fyi also @MaryaBelanger who's done some thinking about this all too.

[devoncarew]

I think it's a good idea to wait at least until we're feel like we've converged on a link format that feels stable.

From the comments above, it sounds like the link format is dart.dev/diagnostics/always_use_package_imports. That's working now for diagnostics, but doesn't yet do the redirection (to https://dart.dev/tools/linter-rules?) for lint codes.

[bwilkerson]

Not necessarily. There's an ongoing discussion about moving all of the lint code documentation into https://dart.dev/tools/diagnostic-messages. The plans are still being discussed (temporarily on hold until the 3.0 work is done), so changes at this point are probably premature.

[devoncarew]

Gotcha, makes sense to me. It sounds like doc simplification + consolidation here is already planned, and might even happen in the near term. I'll close this PR.