site: add gohugo configuration and CI #1984

umarcor · 2023-06-20T23:13:28Z

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 · 2023-07-17T20:29:44Z

@marckhouzam can we please have this milestoned and merged?

marckhouzam · 2023-07-18T11:07:05Z

@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 · 2023-07-18T14:03:52Z

@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:

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 · 2023-08-05T09:27:40Z

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 · 2023-12-23T21:59:05Z

.github/workflows/site.yml

+    runs-on: ubuntu-latest
+    steps:
+
+    - uses: actions/checkout@v3


marckhouzam · 2023-12-23T22:11:33Z

site/go.mod

@@ -0,0 +1,10 @@
+module github.com/bep/docuapi


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 · 2023-12-24T19:14:19Z

.github/workflows/site.yml

@@ -0,0 +1,47 @@
+name: 'site'


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 · 2023-12-24T19:17:36Z

.github/workflows/site.yml

+  pull_request:
+
+jobs:
+  doc:


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

marckhouzam · 2023-12-26T16:05:48Z

site/config.toml

+baseurl = "https://spf13.github.io/cobra/"
+title = "Cobra"
+
+disableKinds = ["taxonomyTerm"]


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

marckhouzam · 2023-12-26T16:06:40Z

site/config.toml

+[module.hugoVersion]
+[[module.imports]]
+# We need one module import for Hugo to detect us as a Hugo Module.
+path="github.com/bep/empty-hugo-module"


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 · 2023-12-26T16:24:00Z

site/config.toml

@@ -0,0 +1,45 @@
+theme = "docuapi"


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 · 2023-12-26T16:42:00Z

site/config.toml

+
+# Code higlighting settings
+pygmentsCodefences = true
+pygmentsCodeFencesGuesSsyntax = false


pygmentsCodeFencesGuesSsyntax -> pygmentsCodeFencesGuessSyntax

marckhouzam · 2023-12-26T16:49:42Z

site/config.toml

@@ -0,0 +1,45 @@
+theme = "docuapi"


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 · 2023-12-26T17:41:31Z

.github/workflows/site.yml

+
+    - name: Get Hugo and Theme
+      run: |
+        curl -fsSL https://github.com/gohugoio/hugo/releases/download/v0.114.0/hugo_extended_0.114.0_Linux-64bit.tar.gz | sudo tar xzf - -C /usr/local/bin hugo


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 · 2023-12-26T17:53:46Z

.github/workflows/site.yml

+      run: |
+        cd site/public/
+        touch .nojekyll
+        git init


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.

github-actions bot added the area/github For changes to Github specific things not shipped in the library label Jun 20, 2023

umarcor force-pushed the umarcor/pages branch from 3fc7dcf to a3c9f45 Compare July 17, 2023 20:24

marckhouzam added this to the 1.8.0 milestone Jul 18, 2023

umarcor mentioned this pull request Aug 6, 2023

404 links on https://cobra.dev/ #1391

Open

umarcor added 2 commits August 29, 2023 16:08

site: add gohugo configuration

501f8c7

ci: add GitHub Actions workflow 'site'

89c1e0d

umarcor force-pushed the umarcor/pages branch from a3c9f45 to 89c1e0d Compare August 29, 2023 14:08

marckhouzam modified the milestones: 1.8.0, 1.9.0 Nov 15, 2023

marckhouzam reviewed Dec 23, 2023

View reviewed changes

marckhouzam reviewed Dec 26, 2023

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

site: add gohugo configuration and CI #1984

site: add gohugo configuration and CI #1984

umarcor commented Jun 20, 2023

umarcor commented Jul 17, 2023

marckhouzam commented Jul 18, 2023 •

edited

umarcor commented Jul 18, 2023 •

edited

umarcor commented Aug 5, 2023

marckhouzam left a comment

marckhouzam Dec 23, 2023

marckhouzam Dec 23, 2023 •

edited

marckhouzam left a comment

marckhouzam Dec 24, 2023

marckhouzam Dec 24, 2023

marckhouzam Dec 26, 2023

marckhouzam Dec 26, 2023

marckhouzam Dec 26, 2023

marckhouzam Dec 26, 2023

marckhouzam Dec 26, 2023

marckhouzam Dec 26, 2023

marckhouzam Dec 26, 2023

site: add gohugo configuration and CI #1984

Are you sure you want to change the base?

site: add gohugo configuration and CI #1984

Conversation

umarcor commented Jun 20, 2023

umarcor commented Jul 17, 2023

marckhouzam commented Jul 18, 2023 • edited

umarcor commented Jul 18, 2023 • edited

umarcor commented Aug 5, 2023

marckhouzam left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marckhouzam Dec 23, 2023 • edited

Choose a reason for hiding this comment

marckhouzam left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marckhouzam commented Jul 18, 2023 •

edited

umarcor commented Jul 18, 2023 •

edited

marckhouzam Dec 23, 2023 •

edited