gh-pages / generated docs updates

[devoncarew]

We might consider:

• changing from hosting the docs on a separate branch (https://github.com/dart-lang/linter/tree/gh-pages) to using a specific directory in the main branch; github added the ability to do this a while ago - it's just a setting for the repo

• changing from generating html to generating markdown, and then having a jekyll template serve that as html. Jekyll is well supported by github pages; we'd be using a process slightly more similar to other github repos, and, it would give us more options in terms of doc styles and presentation

[devoncarew]

@pq - if you generate the docs into doc/lints/ (or similar) in this repo, and then update the gh-pages setting, you can switch to serving from the master branch independent of any switch to generating to markdown / using jekyll.

[parlough]

Perhaps we want to use #2362 along with Jekyll Data Files to surface lints on dart.dev similar to analyzer diagnostics?

We could use Github actions to check if the file has changes then submit a PR to site-www.

I'd be happy to work towards these if there is a solid direction we want to go.

cc @kwalrath

[bwilkerson]

There's one consideration that I know of. We have shipped versions of the SDK that produce links to the lint documentation. Those links won't update to the new location if we change where the documentation is published, which means that unless we also redirect from the old location to the new any previously published IDEs will have broken links.

Redirecting probably isn't a problem, but that needs to be part of the work.

[pq]

Thanks Brian. In addition to published SDKs there are lots of open issues w/ links to the existing docs. Having a redirect to keep them alive would be great.

[parlough]

Thanks, both those situations definitely make sense! Once the site-www version is finalized, released, and perhaps given some time to settle, I can definitely figure something out to redirect the current site links to redirect to the updated entries.

[pq]

I think we can close this as there are a few fresher issues tracking current work on doc generation.