Reorganize `Hosting Documentation`

[aviatesk]

From the slack discussion:

Shuhei Kadowaki 4 minutes ago By the way, the section Authentication: SSH Deploy Keys should be in the parent section of GitHub, not in the Travis CI section? It often confuses me that I need to jump to the Travis section when I try to read through the instructions for GitHub actions (and I guess most people use GH actions more than Travis these days?)

Morten Piibeleht 2 minutes ago Yeah, that's an artifact from the Travis days :older_adult: In principle, that page should be reorganized and rewritten.

The main goal of this issue to make it easier to read through the instructions for GitHub Actions. Currently it is a bit confusing since a part of the instructions currently redirects to the Travis section, that is used rarely these days.

[adrhill]

Adding to this, the outline of the hosting documentation in the side-bar is currently a bit confusing:

As mentioned above, the subsection "Authentication: SSH Deploy Keys" deserves a bullet-point and the section on Travis could probably be moved to the back of the page.

Talking with @gdalle, we were also confused whether the DOCUMENTER_KEY SSH Deploy Key is even needed anymore? Guillaume tells me he "never had to set up any token for any doc ever".

[goerz]

I'm pretty sure it's still needed. I forget how the various "secrets" interact with each other, but without setting up anything, a tag created by TagBot won't trigger any workflows that would normally run on tag creation, and thus you'd presumably get no documentation for a tagged release.

[gdalle]

Could THAT be why my tagged releases never work properly?

[gdalle]

I regularly find myself having to push a manual tag for the docs build

[goerz]

Yes!!! 😊

[gdalle]

Well I guess if the section hadn't been under Travis I would have found it sooner 🤣

Sounds like something we could add to PkgTemplates.jl too? The current template for docs doesn't include a documenter key, see https://github.com/JuliaCI/PkgTemplates.jl/blob/master/test/fixtures/DocumenterGitHubActions/.github/workflows/CI.yml

[goerz]

I'll probably not be able to resist giving the entire "Guide" and "Hosting Documentation" a proper rewrite sometime soonish, and I'll have a look at PkgTemplates at that time.

I agree that the keys should be in the template, although there's always going to be a manual step of setting them up properly.