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.mdfile 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 ¶
const (
DocsRepo = "solo-docs"
)
Variables ¶
This section is empty.
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
}
Source Files