docsutils

README

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.

Documentation

Index

• Constants
• func CreateDocsPR(owner, repo, product, changelogPrefix, tag string, apiPaths ...string) error
• func CreateDocsPRFromSpec(spec *DocsPRSpec) error
• func CreateDocsPRSimple(owner, repo, tag string, paths ...string) error
• func PushDocsCli(spec *DocsPRSpec)
• type DocsPRSpec
• type File
• type Files

Constants

const (
	DocsRepo = "solo-docs"
)

Functions

func CreateDocsPR

func CreateDocsPR(owner, repo, product, changelogPrefix, tag string, apiPaths ...string) error

Example: CreateDocsPR("solo-io", "gloo", "gloo", "gloo", "v0.8.2", "docs/v1/github.com/solo-io/gloo", "docs/v1/github.com/solo-io/solo-kit", "docs/v1/gogoproto", "docs/v1/google")

func CreateDocsPRFromSpec

func CreateDocsPRFromSpec(spec *DocsPRSpec) error

func CreateDocsPRSimple

func CreateDocsPRSimple(owner, repo, tag string, paths ...string) error

Useful for cases where repo == docs product name == changelogPrefix name

func PushDocsCli

func PushDocsCli(spec *DocsPRSpec)

Types

type DocsPRSpec

type DocsPRSpec struct {
	// Repo owner, i.e. "solo-io"
	Owner string
	// Repo, i.e. "solo-projects"
	Repo string
	// Release tag, i.e. "v0.8.5"
	Tag string
	// Product in docs, i.e. "gloo"
	Product string
	// Prefix to the changelog file in the docs repo, i.e. "glooe" -> push changelog to solo-docs/<product>/docs/changelog/glooe-changelog
	ChangelogPrefix string
	// Path to the directory containing "docs", i.e. "projects/gloo/doc
	DocsParentPath string
	// Paths to generated API doc directory that should be copied into docs, i.e. "docs/v1/github.com/solo-io/gloo"
	ApiPaths []string // can be nil
	// Individual files to copy.
	Files Files
	// Prefix of the CLI docs files, i.e. "glooctl"
	CliPrefix string // empty means don't copy docs files
}

type File

type File struct {
	From string
	To   string
}

type Files

type Files []File