Publish github pages to external repository

[maurermi]

This PR addresses the growing gh-pages branch and re-writes the github pages action to direct pages to an external repository. Rather than cloning a single branch to avoid pulling down gh-pages which can be annoying to work with when the repo has multiple branches, having gh-pages in a separate repository may be more useful.

This also makes gh-pages opt-in instead of opt-out.

PRing this for consideration and discussion, as making this change would require slightly more than merging upstream.

cc: @madars

[HalosGhost]

Immense Concept-ACK. What steps do we need to take to tACK / deploy? Does the repo need to be created in-advance and are any permissions changes necessary?

[maurermi]

This is a good question, I believe the repo does need to be created in advance, and it looks like the github_token affiliated with the action in this repo would not work for pushing to an external repo. It looks like the way to go about doing this would be to create a SSH deploy key, and give the GH action permission to write to the newly created 'pages' repo.

(Potentially Useful Links: ) https://github.com/peaceiris/actions-gh-pages?tab=readme-ov-file#%EF%B8%8F-deploy-to-external-repository-external_repository https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys https://github.com/peaceiris/actions-gh-pages?tab=readme-ov-file#%EF%B8%8F-create-ssh-deploy-key

[HalosGhost]

Okay, I've just tested this using a couple of basic repos to make sure I understand the flow. Here's a checklist for us to implement:

• [X] Create documentation repository
• [X] Generate deployment key
• [X] Add deployment secret key to -tx, and deployment public key to docs repo
• [x] Update workflow to target new repo
  • to potentially make it easier to host docs for multiple repos later on, I think we should target a branch specific to the origin (e.g., tx) keeping suggested repo name for now (potentially revisit for unified documentation in the future)
• [x] Unpublish the gh-pages deployment from -tx, and publish the new gh-pages deployment from the docs repo
• [x] Delete the gh-pages branch from this repo

@maurermi mind taking a brief look at my docs MVP (https://github.com/HalosGhost/doc-test and https://github.com/HalosGhost/doc-test-ext) to see if you agree?

[maurermi]

@HalosGhost Those experimental repos look good on my end

[HalosGhost]

@maurermi I'm not bothered by it in this case, but note that git-trailers are expected to be in a contiguous block separated from the commit-body by a newline. This has bitten us before.