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
• 404 links on https://cobra.dev/ #1391
• [cobra.dev] Invalid link #1410
• Link on doc does not work #1996
• Broken link #1979
• Broken links in cobra.dev site #1959
• Doc bug: link to generator page is broken #1951
• cobra.dev update required #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

[marckhouzam]

I’m finally going to give this PR some attention. I’ve just started but I’ll continue in the next little while

sorry for all the delay @umarcor

[marckhouzam]

@v4

[marckhouzam]

Let's name it github.com/spf13/cobra/site

If you could remove this file and do a hugo mod init github.com/spf13/cobra/site && hugo mod tidy we'd get something more up-to-date

[marckhouzam]

Ok, I'm on board with this.
Sorry @umarcor this took sooo long: I hadn't used Hugo before so I kept pushing this off as I needed to ramp up.

It has been so long that some parts of the PR would benefit with modernizing. I've put comments in those locations.

Some of my comments may be off as I don't have much experience with Hugo, but hopefully we can work out the details together.

[marckhouzam]

My VScode is interpreting a file name site.yml to be an Ansible playbook and its trying to parse it as such.
There is surely a way for me to fix this, but I was wondering if it wouldn't be better for other contributors to rename this file so this "problem" doesn't happen?

[marckhouzam]

How about giving it a more descriptive name? Maybe build website:?

[marckhouzam]

I'm getting this warning: WARN DEPRECATED: Kind "taxonomyterm" used in disableKinds is deprecated, use "taxonomy" instead.

[marckhouzam]

How about importing the theme we use (and removing the comment)? github.com/bep/docuapi/v2
Then I don't seem to need to git clone the docuapi repo.

[marckhouzam]

config.toml is the old naming scheme (https://gohugo.io/getting-started/configuration/).
Let's rename to hugo.toml.
Actually, would you ming using yaml instead? Since that is what we use for our other configurations?
Here is the converted content using an online converter (including the suggested changes in my comments):
hugo.yml:

# Seems not work with modules: theme: docuapi
languageCode: en-us
baseurl: 'https://spf13.github.io/cobra/'
title: Cobra

disableKinds: [taxonomy]

# Code higlighting settings
pygmentsCodefences: true
pygmentsCodeFencesGuessSyntax: false
pygmentsOptions: ''
pygmentsStyle: monokai
pygmentsUseClasses: false

defaultContentLanguage: en

module:
  hugoVersion: {}
  imports:
    - path: github.com/bep/docuapi/v2

params:
  search: true

markup:
  goldmark:
    parser:
      autoHeadingIDType: github-ascii
    renderer:
      unsafe: true

languages:
  en:
    languageName: English
    weight: 2
    title: Cobra documentation
    params:
      toc_footers:
        - >-
          [![github.com/spf13/cobra](https://img.shields.io/badge/-spf13/cobra-323131.svg?logo=github&style=flat-square&longCache=true)](https://github.com/spf13/cobra)
        - >-
          Built with [Hugo](https://gohugo.io/) theme
          [DocuAPI](https://github.com/bep/docuapi) by
          [bep](https://github.com/bep)
      blackfriday:
        angledQuotes: false
        hrefTargetBlank: true

[marckhouzam]

pygmentsCodeFencesGuesSsyntax -> pygmentsCodeFencesGuessSyntax

[marckhouzam]

I've been playing around with this and having the theme line is not working for me unless I git clone the docuapi repo. But I find it simpler to add docuapi as a module dependency, but then the theme line give me an error. If I remove the theme line is seems to work.

[marckhouzam]

How about using a github action?
This seems to be the most popular: https://github.com/marketplace/actions/hugo-setup
This example should suit our needs I think: https://github.com/peaceiris/actions-hugo?tab=readme-ov-file#%EF%B8%8F-workflow-for-autoprefixer-and-postcss-cli

[marckhouzam]

I wanted to discuss this approach with you, but I'll wait to see what you think about the GH Action, which may change this approach.