site: add gohugo configuration and CI

[umarcor]

Following #1428, this PR is a subset of #1245.

This PR adds the minimal configuration and a CI workflow to build a documentation site using hugo and push it to branch gh-pages (to be hosted at USERNAME.github.io/cobra).

[umarcor]

@marckhouzam can we please have this milestoned and merged?

[marckhouzam]

@umarcor when we merge this what should we see? Will there be a new gh site for users? Is there already one on your account?

[umarcor]

@marckhouzam the CI workflow will:

• Build an HTML site using Hugo.
• Upload it as an artifact (zipfile).
• Push it to branch gh-pages (always overwriting the content of that branch but showing the commit that it corresponds to; see https://github.com/umarcor/cobra/blob/umarcor/pages/.github/workflows/site.yml#L41 and https://github.com/umarcor/cobra/blob/umarcor/pages/.github/workflows/site.yml#L47).

GitHub Pages allows serving the content of branch gh-pages at USERNAME.github.io/REPONAME. Actually, it can be served from any branch, either from the root of the branch or from subdir /docs. However, the site might not be served by default. When the default token is used to push to gh-pages, it does not trigger the activation. A user needs to enable it through https://github.com/USERNAME/cobra/settings/pages, or push a commit to gh-pages with user credentials (just once; it does not matter if all future commits are created by the token, neither that it overwrites the commit of the user).

I suggest you push this branch to your fork, let CI run, and then check https://github.com/marckhouzam/cobra/settings/pages.

When GitHub Pages is enabled in a repo, it will show in the sidebar, in section 'Environtments'. See my fork: https://github.com/umarcor/cobra. Also, in section 'About', the website can be set to the Pages (without manually typing it). Nonetheless, both of those references can be hidden (by unchecking the 'Environments' section and leaving the URL empty). That is, we can merge this PR in order to have CI for the docs and start working on improving them, but we do not need to advertise it yet, so that users still find the "official" cobra.dev.

GitHub Pages does also support setting a custom domain. Therefore, eventually we could make spf13.github.io/cobra be an alias of cobra.dev (or the other way round). I.e. users navigating to cobra.dev will see the content of the gh-pages of this repo. Alternatively, we can make the CI of this repo push to the master branch of spf13/cobra.dev. However, that would require a token with write permissions in that repo, while doing it from the gh-pages branch of this repo allows using the default token in CI and not dealing with PATs. Overall, when the gh-pages of this repo is good enough to be served at cobra.dev, I believe we should archive spf13/cobra.dev.

Yet, I don't think this PR alone is enough to replace cobra.dev. This is just to have CI and start treating documentation-as-code (e.g. checking for broken links/refs). I believe we should then discuss what theme we want, and reorganise the (sub)sections to better use the sidebar(s).

The main reason to push this PR forward is the amount of issues and PRs related to cobra.dev being broken for several years already:

• https://github.com/spf13/cobra.dev/issues
• https://github.com/spf13/cobra.dev/pulls
• #1391
• #1410
• #1996
• #1979
• #1959
• #1951
• #1674

We could close all those issues/PRs with "The automatically generated and up-to-date content can be found in spf13.github.io/cobra. There is work-in-progress to make cobra.dev serve that content".

[umarcor]

ping @marckhouzam