From 0998119010881fbe45789bb94721cdacc2651e24 Mon Sep 17 00:00:00 2001 From: Phillip Wittrock Date: Wed, 28 Jun 2017 12:14:25 -0700 Subject: [PATCH 1/3] Update reference docs glide --- docs/building_docs.md | 107 ++++++++++++++++++ ...creating_docs.md => running_in_cluster.md} | 0 glide.yaml | 2 +- 3 files changed, 108 insertions(+), 1 deletion(-) create mode 100644 docs/building_docs.md rename docs/{creating_docs.md => running_in_cluster.md} (100%) diff --git a/docs/building_docs.md b/docs/building_docs.md new file mode 100644 index 0000000000..5f4348e40b --- /dev/null +++ b/docs/building_docs.md @@ -0,0 +1,107 @@ +# Creating reference documentation + +This document describes how to build reference documentation for +a Kubernetes apiserver. + +## Building default reference documentation + + +### If using the apiserver-builder framework for your apiserver + +1. Build the apiserver binary + - `apiserver-builder build executables` +2. Generate the docs from the swagger.json + - `apiserver-build build docs` + - This will automatically start a server and get the swagger.json from it + - **Note:** to include docs for operations, use the flag `--operations=true` +3. Open `docs/build/index.html` in a browser + +### If *not* using the apiserver-builder framework for your apiserver + +1. Get the openapi json + - Fetch a copy of the "swagger.json" file from your apiserver (located at url /swagger.json), and copy it to docs/ and specify + the `--build-openapi=false` flag. +2. Generate the docs for your swagger + - `apiserver-build build docs --build-openapi=false` + +## Customizing group descriptions + +To add custom descriptions and content to an API group, modify the docs/static_include/_.md file +with your content. These files are created once when the docs are first generated, but will not overwrite +your changes. + +After adding your content, rerun `apiserver-boot build docs`. + +## Adding examples + +It is highly recommended to add examples of your types to the right-most column. + +After adding your content, rerun `apiserver-boot build docs`. + +### Type examples + +Add an example for your type using in a file + +`docs/examples//.yaml` + +```yaml +note: Description of your example. +sample: | + apiVersion: + kind: + metadata: + name: + spec: + +``` + +### Operation examples + +**Note:** Building operations requires providing the `--operations=true` flag. + +You can also provide example for operations. Example operations +contain: + +- resource instance name +- resource instance namespace +- yaml request body to the +- json response body from the apiserver + +```yaml +name: +namespace: +request: | + +response: | + +``` + +The docs framework will automatically create per-language / tool example tabs +using this input. + +Locations for operation examples: + +- create: `docs/examples//create.yaml` +- delete: `docs/examples//delete.yaml` +- list: `docs/examples//list.yaml` +- patch: `docs/examples//patch.yaml` +- read: `docs/examples//read.yaml` + - **Note:** read does not have a request section +- replace: `docs/examples//replace.yaml` +- watch: `docs/examples//watch.yaml` + +## Customizing dynamic sections + +Some of the dynamicly generated sections of the docs maybe statically configured +by provided a `config.yaml` in the docs directory and providing the flag +`--generate-toc=false` when running `build docs`. + +Using a config.yaml supports: + +- Statically defining the table of contents with customized groupings +- Defining which types are inlined into parent types (e.g. Spec, Status, List) +- Adding notes and warnings to resources +- Grouping subresources +- Redefining display names for operations + +See an example [here](https://github.com/kubernetes-incubator/reference-docs/blob/master/gen-apidocs/generators/config.yaml) diff --git a/docs/creating_docs.md b/docs/running_in_cluster.md similarity index 100% rename from docs/creating_docs.md rename to docs/running_in_cluster.md diff --git a/glide.yaml b/glide.yaml index 2c80800710..93a86c9f22 100644 --- a/glide.yaml +++ b/glide.yaml @@ -40,6 +40,6 @@ import: subpackages: - cmd/libs/go2idl - package: github.com/kubernetes-incubator/reference-docs - version: 96204a551e6fceeed37f844f8598ad1cb60d7eed + version: 9000d782e8f8dbfd670b9c48bd4b47af8f6adb49 subpackages: - gen-apidocs From 42b6a1ad8afbb3e49f37bfcc3e25efb9fd678932 Mon Sep 17 00:00:00 2001 From: Phillip Wittrock Date: Wed, 28 Jun 2017 12:14:56 -0700 Subject: [PATCH 2/3] - Create sample docs and config when creating a resource - Create certs under config/ instead of bin/ --- .../boot/build/build_resource_config.go | 17 +++------ cmd/apiserver-boot/boot/build/docs.go | 6 ++- cmd/apiserver-boot/boot/create/resource.go | 37 +++++++++++++++++++ cmd/apiserver-boot/boot/run/in_cluster.go | 7 +++- cmd/apiserver-boot/boot/run/local.go | 7 +++- 5 files changed, 60 insertions(+), 14 deletions(-) diff --git a/cmd/apiserver-boot/boot/build/build_resource_config.go b/cmd/apiserver-boot/boot/build/build_resource_config.go index 6ee3f059de..f9406ce7bf 100644 --- a/cmd/apiserver-boot/boot/build/build_resource_config.go +++ b/cmd/apiserver-boot/boot/build/build_resource_config.go @@ -21,6 +21,7 @@ import ( "io/ioutil" "log" "os" + "os/exec" "path" "path/filepath" "regexp" @@ -28,7 +29,6 @@ import ( "github.com/kubernetes-incubator/apiserver-builder/cmd/apiserver-boot/boot/util" "github.com/spf13/cobra" "k8s.io/apimachinery/pkg/runtime/schema" - "os/exec" ) var Name, Namespace string @@ -91,6 +91,7 @@ func getBase64(file string) string { func buildResourceConfig() { initVersionedApis() + dir := filepath.Join(ResourceConfigDir, "certificates") a := resourceConfigTemplateArgs{ Name: Name, @@ -98,13 +99,12 @@ func buildResourceConfig() { Image: Image, Domain: util.Domain, Versions: Versions, - ClientKey: getBase64(filepath.Join("bin", "certificates", "apiserver.key")), - CACert: getBase64(filepath.Join("bin", "certificates", "apiserver_ca.crt")), - ClientCert: getBase64(filepath.Join("bin", "certificates", "apiserver.crt")), + ClientKey: getBase64(filepath.Join(dir, "apiserver.key")), + CACert: getBase64(filepath.Join(dir, "apiserver_ca.crt")), + ClientCert: getBase64(filepath.Join(dir, "apiserver.crt")), } path := filepath.Join(ResourceConfigDir, "apiserver.yaml") - util.DoCmd("mkdir", "-p", ResourceConfigDir) created := util.WriteIfNotFound(path, "config-template", resourceConfigTemplate, a) if !created { log.Fatalf("Resource config already exists.") @@ -112,12 +112,7 @@ func buildResourceConfig() { } func createCerts() { - dir, err := os.Getwd() - if err != nil { - log.Fatal(err) - } - dir = filepath.Join(dir, "bin", "certificates") - + dir := filepath.Join(ResourceConfigDir, "certificates") util.DoCmd("mkdir", "-p", dir) if _, err := os.Stat(filepath.Join(dir, "apiserver_ca.crt")); os.IsNotExist(err) { diff --git a/cmd/apiserver-boot/boot/build/docs.go b/cmd/apiserver-boot/boot/build/docs.go index 72ca0a3a04..399d1fd98c 100644 --- a/cmd/apiserver-boot/boot/build/docs.go +++ b/cmd/apiserver-boot/boot/build/docs.go @@ -34,7 +34,10 @@ var docsCmd = &cobra.Command{ Use: "docs", Short: "Generate API reference docs from the openapi spec.", Long: `Generate API reference docs from the openapi spec.`, - Example: `# Start a new server, get the swagger.json, and generate docs from the swagger.json + Example: `# Edit docs examples +nano -w docs/examples//.yaml +kubectl apply -f samples/.yaml +kubectl get `, Run: RunInCluster, } diff --git a/cmd/apiserver-boot/boot/run/local.go b/cmd/apiserver-boot/boot/run/local.go index 0f0fd89499..7e84c0a7a2 100644 --- a/cmd/apiserver-boot/boot/run/local.go +++ b/cmd/apiserver-boot/boot/run/local.go @@ -42,7 +42,12 @@ apiserver-boot run local kubectl --kubeconfig kubeconfig api-versions # Run locally without rebuilding -apiserver-boot run local --build=false`, +apiserver-boot run local --build=false + +# Create an instance and fetch it +nano -w samples/.yaml +kubectl --kubeconfig kubeconfig apply -f samples/.yaml +kubectl --kubeconfig kubeconfig get `, Run: RunLocal, } From d2a69ef9f2c3461b31447cbe46727e71b2c677d8 Mon Sep 17 00:00:00 2001 From: Phillip Wittrock Date: Wed, 28 Jun 2017 12:42:04 -0700 Subject: [PATCH 3/3] Update glide.lock for ref-docs --- glide.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/glide.lock b/glide.lock index 87e4c5a257..909f0fd52d 100644 --- a/glide.lock +++ b/glide.lock @@ -1,5 +1,5 @@ -hash: a87b96f9245075dd204a9eba558a74c76041211f89dde2866a4c1635dc6232ae -updated: 2017-06-26T17:28:37.142700636-07:00 +hash: 3ef7fdd27f258df3c3eb48d0335ae1bbbf9b432e8b716db4b0bfcce7037eb7a2 +updated: 2017-06-28T12:18:13.132153406-07:00 imports: - name: bitbucket.org/ww/goautoneg version: 75cd24fc2f2c2a2088577d12123ddee5f54e0675 @@ -169,7 +169,7 @@ imports: - name: github.com/juju/ratelimit version: 5b9ff866471762aa2ab2dced63c9fb6f53921342 - name: github.com/kubernetes-incubator/reference-docs - version: 96204a551e6fceeed37f844f8598ad1cb60d7eed + version: 9000d782e8f8dbfd670b9c48bd4b47af8f6adb49 subpackages: - gen-apidocs - name: github.com/mailru/easyjson