cobra Build Hugo site with GitHub Actions and deploy to GitHub Pages

In this PR, a GitHub Actions workflow is added for building a web site with Hugo and deploying it to GitHub Pages (branch gh-pages).

The content of the README is split to multiple markdown sources.
Markdown sources from the root and from subdir doc are moved to site/content .
- Documentation sources regarding completions are placed in site/content/completions.
- Documentation sources regarding documentation generation are placed in site/content/docgen.
Hugo configuration files are added to site. @bep's docuapi theme is used.
In a GitHub Actions workflow, Hugo is installed, the theme is installed, the site is built, and the site is uploaded as an artifact as well as pushed to branch gh-pages.
The logo from the README is used in the site (with a different font color).
Any contributor that forks the repo and pushes some change, will have the site automatically built and uploaded to username.github.io/cobra.

See:

Proposed README: https://github.com/umarcor/cobra/blob/ci-site/README.md
Proposed site: https://umarcor.github.io/cobra
Example CI run: https://github.com/umarcor/cobra/actions/runs/288401296 (note the artifact)

Ref #985 #1243 #1244

Oct 04 '20 23:10 umarcor

I've opened cobra.dev source to a few contributors. https://github.com/spf13/cobra.dev . I'd love to support however I can.

Jan 13 '21 17:01 spf13

@spf13, thanks a lot! I will repurpose this PR and probably split it between here and spf13/cobra.dev.

Just something I'm unsure about: where is cobra.dev deployed from? spf13/cobra.dev contains the sources of a Hugo site. However, I did not see any branch with the artifacts and as far as I am aware, GitHub can only build Jekyll sites from sources. Hence, I assume that the site is not hosted on GitHub Pages. Do you have some private pipeline/CI to take care of that?

Jan 15 '21 04:01 umarcor

It's currently hosted on firebase hosting. It looks like I never set up any autodeploy, but I'm happy to do that.

Doing a quick search found https://github.com/marketplace/actions/hugo-on-fire which seems like the ideal solution.

On Thu, Jan 14, 2021 at 11:44 PM Unai Martinez-Corral < [email protected]> wrote:

@spf13 https://github.com/spf13, thanks a lot! I will repurpose this PR and probably split it between here and spf13/cobra.dev.

Just something I'm unsure about: where is cobra.dev deployed from? spf13/ cobra.dev contains the sources of a Hugo site. However, I did not see any branch with the artifacts and as far as I am aware, GitHub can only build Jekyll sites from sources. Hence, I assume that the site is not hosted on GitHub Pages. Do you have some private pipeline/CI to take care of that?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/spf13/cobra/pull/1245#issuecomment-760641768, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABKKZECMQHNSVOZIDLG3VLSZ7BZRANCNFSM4SEAT2RQ .

Jan 15 '21 14:01 spf13

@spf13, nice and thanks.

For now, it's enough to know that we can handle it with an Action in a GitHub Actions workflow. I will probably propose PRs to be autodeployed to gh-pages of the contributor's fork. That will allow any contributor to push changes and see the results automatically deployed to their username.github.io/cobra or username.github.io/cobra.dev site.

We'll discuss later whether the "official" deployment needs to be done here, in spf13/cobra.dev or somewhere else; that's a minor technical thing.

Jan 15 '21 15:01 umarcor

This PR is being marked as stale due to a long period of inactivity

Mar 17 '21 00:03 github-actions[bot]

@umarcor what's the status on this. I think your new site is far superior to the existing one. I did a small amount of management to bring it up to date so it builds again, but still prefer yours.

Let me know how I can help with this.

Nov 02 '21 20:11 spf13

@spf13, see #1428. That's the first subset of this PR: moving all markdown sources related to the documentation into a single directory.

However, co-maintainers have been struggling to merge PRs in the last months, so I kept this docs/site stuff on hold until I get some other "less disruptive" modifications accepted (see https://github.com/spf13/cobra/pulls/umarcor). We are heading for a release (see https://github.com/spf13/cobra/issues/1496) and I listed all my ready-to-merge PRs there.

Then, I'll focus on #1428 (subset of this), #1245 (this) and #1430.

I'd be glad if you could review and maybe approve #1245 and #1430. The latter is not strictly related to the doc/site, but it is a minor reorganisation of the codebase.

Nov 02 '21 22:11 umarcor

This PR is not stale, but blocked by #1428. Please, remove the kind/stale label. See https://github.com/spf13/cobra/pull/1245#issuecomment-958320943.

Feb 25 '22 09:02 umarcor