In this PR, a GitHub Actions workflow is added for building a web sit…

…e with [Hugo](https://gohugo.io/) 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](https://github.com/bep/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 Merge spf13/cobra#1245
zulucmd · Mar 5, 2022 · f6cd32b · f6cd32b
1 parent ea54716
commit f6cd32b
Show file tree

Hide file tree

Showing 23 changed files with 318 additions and 127 deletions.
diff --git a/.github/workflows/site.yml b/.github/workflows/site.yml
@@ -0,0 +1,45 @@
+name: 'site'
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  doc:
+    runs-on: ubuntu-latest
+    steps:
+
+      - uses: actions/checkout@v2
+
+      - name: Get Hugo and Theme
+        run: |
+          curl -fsSL https://github.com/gohugoio/hugo/releases/download/v0.62.1/hugo_extended_0.62.1_Linux-64bit.tar.gz | sudo tar xzf - -C /usr/local/bin hugo
+          sudo chmod +x /usr/local/bin/hugo
+          mkdir -p site/themes
+          cd site/themes
+          git clone https://github.com/bep/docuapi
+          cd docuapi
+          npm install --only=dev
+          mv node_modules ../..
+      - name: Build site
+        run: |
+          cd site
+          hugo version
+          hugo
+      - uses: actions/upload-artifact@v2
+        with:
+          name: site
+          path: site/public
+
+      - name: Publish site to gh-pages
+        if: github.event_name != 'pull_request'
+        run: |
+          cd site/public/
+          touch .nojekyll
+          git init
+          cp ../../.git/config ./.git/config
+          git add .
+          git config --local user.email "push@gha"
+          git config --local user.name "GHA"
+          git commit -a -m "update ${{ github.sha }}"
+          git push -u origin +HEAD:gh-pages
diff --git a/README.md b/README.md
@@ -4,88 +4,8 @@ Zulu is a library for creating powerful modern CLI applications. It is forked fr
 [![Go Reference](https://pkg.go.dev/badge/github.com/gowarden/zulu.svg)](https://pkg.go.dev/github.com/gowarden/zulu)
 [![Go Report Card](https://goreportcard.com/badge/github.com/gowarden/zulu)](https://goreportcard.com/report/github.com/gowarden/zulu)
 
-# Overview
-
-Zulu is a library providing a simple interface to create powerful modern CLI
-interfaces similar to git & go tools.
-
-Zulu is also an application that will generate your application scaffolding to rapidly
-develop a Zulu-based application.
-
-Zulu provides:
-* Easy subcommand-based CLIs: `app server`, `app fetch`, etc.
-* Fully POSIX-compliant flags (including short & long versions)
-* Nested subcommands
-* Global, local and cascading flags
-* Intelligent suggestions (`app srver`... did you mean `app server`?)
-* Automatic help generation for commands and flags
-* Automatic help flag recognition of `-h`, `--help`, etc.
-* Automatically generated shell autocomplete for your application (bash, zsh, fish, powershell)
-* Automatically generated man pages for your application
-* Command aliases so you can change things without breaking them
-* The flexibility to define your own help, usage, etc.
-* Optional seamless integration with [viper](https://github.com/spf13/viper) for 12-factor apps
-
-# Concepts
-
-Zulu is built on a structure of commands, arguments & flags.
-
-**Commands** represent actions, **Args** are things and **Flags** are modifiers for those actions.
-
-The best applications read like sentences when used, and as a result, users
-intuitively know how to interact with them.
-
-The pattern to follow is
-`APPNAME VERB NOUN --ADJECTIVE.`
-    or
-`APPNAME COMMAND ARG --FLAG`
-
-A few good real world examples may better illustrate this point.
-
-In the following example, 'server' is a command, and 'port' is a flag:
-
-    hugo server --port=1313
-
-In this command we are telling Git to clone the url bare.
-
-    git clone URL --bare
-
-## Commands
-
-Command is the central point of the application. Each interaction that
-the application supports will be contained in a Command. A command can
-have children commands and optionally run an action.
-
-In the example above, 'server' is the command.
-
-[More about zulu.Command](https://pkg.go.dev/github.com/gowarden/zulu#Command)
-
-## Flags
-
-A flag is a way to modify the behavior of a command. Zulu supports
-fully POSIX-compliant flags as well as the Go [flag package](https://golang.org/pkg/flag/).
-A Zulu command can define flags that persist through to children commands
-and flags that are only available to that command.
-
-In the example above, 'port' is the flag.
-
-Flag functionality is provided by the [zflag
-library](https://github.com/gowarden/zflag), a fork of the great [spf13/pflag](https://github.com/spf13/pflag)
-library, which itself is a fork of the flag standard library which maintains the same interface while adding POSIX compliance.
-
-# Installing
-Using Zulu is easy. First, use `go get` to install the latest version
-of the library. This command will the library and its dependencies:
-
-    go get -u github.com/gowarden/zulu
-
-Next, include Zulu in your application:
-
-```go
-import "github.com/gowarden/zulu"
-```
-
 # Usage
+
 Zulu provides its own program that will create your application and add any
 commands you want. It's the easiest way to incorporate Zulu into your application.
 

diff --git a/site/.gitignore b/site/.gitignore
@@ -0,0 +1 @@
+/public
diff --git a/site/assets/scss/slate/docuapi_overrides.scss b/site/assets/scss/slate/docuapi_overrides.scss
@@ -0,0 +1,32 @@
+// Overrides
+
+// BACKGROUND COLORS
+////////////////////
+$nav-bg:#254E70 !default;
+$examples-bg: #002642  !default;
+
+
+// FONTS
+////////////////////
+@import url("https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,700&display=swap");
+
+$font-default-family: 'Source Sans Pro', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
+
+// FLEX SIDEBAR
+////////////////////
+
+.toc-wrapper {
+  display: flex;
+  flex-direction: column;
+}
+
+#toc {
+  flex-grow: 1;
+}
+
+.toc-wrapper .toc-footer {
+  margin-top: .5em;
+  li {
+    text-align: center;
+  }
+}
diff --git a/site/config.toml b/site/config.toml
@@ -0,0 +1,44 @@
+theme = "docuapi"
+languageCode = "en-us"
+baseurl = "https://spf13.github.io/cobra/"
+title = "Cobra"
+
+disableKinds = ["taxonomyTerm"]
+
+# Code higlighting settings
+pygmentsCodefences = true
+pygmentsCodeFencesGuesSsyntax = false
+pygmentsOptions = ""
+pygmentsStyle = "monokai"
+pygmentsUseClasses = false
+
+defaultContentLanguage = "en"
+
+[module]
+[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"
+
+[params]
+search = true
+
+[markup]
+[markup.goldmark]
+[markup.goldmark.parser]
+autoHeadingIDType = "github-ascii"
+[markup.goldmark.renderer]
+unsafe= true
+
+[languages]
+[languages.en]
+languageName = "English"
+weight = 2
+title = "Cobra documentation"
+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)"
+]
+[languages.en.blackfriday]
+angledQuotes = false
+hrefTargetBlank = true
diff --git a/CHANGELOG.md → site/content/changelog.md b/CHANGELOG.md → site/content/changelog.md
@@ -1,3 +1,7 @@
+---
+weight: 31
+---
+
 # Zulu Changelog
 
 ## v1.1.3
@@ -35,6 +39,7 @@
 Announcing v1.0.0 of Cobra. 🎉
 
 ### Notable Changes
+
 * Fish completion (including support for Go custom completion) @marckhouzam
 * API (urgent): Rename BashCompDirectives to ShellCompDirectives @marckhouzam
 * Remove/replace SetOutput on Command - deprecated @jpmcb