fully automate doc publication

[proppy]

It seems that the current documentation process is not fully automated:

• https://github.com/google/xls/actions/workflows/build-mkdocs-commit-html.yml is manually triggered w/ a GitHub personal access tokens.
• https://github.com/google/xls/actions/workflows/pages/pages-build-deployment is managed by GitHub w/ publication happening from the main branch:

@cdleary, @meheff any background on why things were setup that way?

We should consider streamlining the process w/ the following changes:

• switch the source from the main branch to https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow
• remove the commit step and the PAT parameters from build-mkdocs-commit
• use https://github.com/actions/upload-pages-artifact and https://github.com/actions/deploy-pages to deploy the pages directly from the workflow
• trigger the workflow on every commit

[cdleary]

I think the basic constraints/thinking that led to this kind of setup was:

• We kind of wanted the rendered docs to be available in-tree (though this isn't a hard requirement, would be reasonable to not have them in tree I think, just a preference at the time thing)
• No easy way to do it on the piper side before syncing out
• Didn't really want an automated rendering commit after every source change commit because it gunks up the commit history
• Nice to have it hosted naturally at the "github pages sister URL of the repo" google.github.io/xls/

Plus probably just "what seemed easy to do" / "automating what we were doing by hand". Other approaches are reasonable.

[cdleary]

Note that this is also why we remap the g3doc folder to docs_src and render to docs/ (because that's where pages wants to look).

[proppy]

Didn't really want an automated rendering commit after every source change commit because it gunks up the commit history

I can definitly empathize w/ that!

The nice thing, now that github has https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow, is that we can publish directly from the workflow artefacts w/o commiting anything to main or gh-pages branches.

[cdleary]

Cool, so long as there's a hosted site with docs I think it's all good options :-)