docsutils

Push Docs CLI

PushDocsCli, defined in cli.go, pushes docs changes on every release build to a pull request in solo-docs.

• If changelog is enabled on the repo, the rendered changelog is pushed to the corresponding file in the docs
• Any autogenerated docs (API or CLI) that should be published in the docs are pushed.

Requirements

This utility assumes the docs repo has been set up in the following way:

• The theme was updated with a readfile shortcode override (see solo-docs/testrepo/layouts/shortcodes)

If Using Changelogs...

• A changelog directory was added in solo-docs/<product>/docs/changelog
• The changelog directory includes an _index.md file that sets the front matter and specifies one or more files to read in
• The changelog file for a particular github project is in solo-docs/<product>/docs/changelog/<project>-changelog

If using autogenerated CLI docs

• The CLI docs are generated into docs/cli.
• The docs repo has set up docs/cli/_index.md.
• The CLI docs were generated with Hugo front matter added (see gloo)

If using autogenerated API docs

• The API docs are generated into docs/v1
• The docs repo has set up docs/v1/_index.md
• The docs were generated for Hugo

Using the CLI

Here's an example go script that creates a PR on release builds, push_docs.go in the repo root:

package main

import (
	"github.com/solo-io/go-utils/docsutils"
)

func main() {
	spec := docsutils.DocsPRSpec{
		Owner: "solo-io",
		Repo: "gloo",
		Product: "gloo",
		ChangelogPrefix: "gloo",
		ApiPaths: []string {
			"docs/v1/github.com/solo-io/gloo",
			"docs/v1/github.com/solo-io/solo-kit",
			"docs/v1/gogoproto",
			"docs/v1/google",
		},
	}
	docsutils.PushDocsCli(&spec)
}

And the corresponding make target:

.PHONY: push-docs
push-docs:
	go run push_docs.go

And finally, the cloudbuild step adds a call to push-docs:

# go-make is produced from https://github.com/solo-io/cloud-builders/go-make
- name: 'gcr.io/$PROJECT_ID/go-make'
  args: ['docker-push', 'manifest', 'release', 'push-docs']
  env:
  - 'TAGGED_VERSION=$TAG_NAME'
  - 'PROJECT_ROOT=github.com/solo-io/solo-projects'
  - 'GOPATH=/workspace/gopath'
  - 'HELM_HOME=/root/.helm' # tell helm where to find data
  dir: './gopath/src/github.com/solo-io/solo-projects'
  secretEnv: ['GITHUB_TOKEN', 'DOCKER_HUB_PASSWORD']
  id: 'release'

Make sure GITHUB_TOKEN and TAGGED_VERSION are available in the environment.