Merge pull request #90 from pwittrock/master

Various: Create docs examples and samples with resource.  Move where certs are generated.

cmd/apiserver-boot/boot/build/build_resource_config.go

@@ -21,14 +21,14 @@ import (
 	"io/ioutil"
 	"log"
 	"os"
+	"os/exec"
 	"path"
 	"path/filepath"
 	"regexp"
 
 	"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,33 +91,28 @@ func getBase64(file string) string {
 
 func buildResourceConfig() {
 	initVersionedApis()
+	dir := filepath.Join(ResourceConfigDir, "certificates")
 
 	a := resourceConfigTemplateArgs{
 		Name:       Name,
 		Namespace:  Namespace,
 		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.")
 	}
 }
 
 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) {

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/<kind>/<kind.yaml
+
+# Start a new server, get the swagger.json, and generate docs from the swagger.json
 apiserver-boot build executables
 apiserver-boot build docs
 
@@ -106,6 +109,7 @@ func RunDocs(cmd *cobra.Command, args []string) {
 		log.Fatal("Must specifiy --server or --build-openapi=false")
 	}
 
+	os.RemoveAll(filepath.Join("docs", "includes"))
 	exec.Command("mkdir", "-p", filepath.Join("docs", "openapi-spec")).CombinedOutput()
 	exec.Command("mkdir", "-p", filepath.Join("docs", "static_includes")).CombinedOutput()
 	exec.Command("mkdir", "-p", filepath.Join("docs", "examples")).CombinedOutput()

cmd/apiserver-boot/boot/create/resource.go

@@ -27,6 +27,7 @@ import (
 	"github.com/kubernetes-incubator/apiserver-builder/cmd/apiserver-boot/boot/util"
 	"github.com/markbates/inflect"
 	"github.com/spf13/cobra"
+	"os/exec"
 )
 
 var kindName string
@@ -125,6 +126,26 @@ func createResource(boilerplate string) {
 		}
 	}
 
+	exec.Command("mkdir", "-p", filepath.Join("docs", "examples")).CombinedOutput()
+	docpath := filepath.Join("docs", "examples", strings.ToLower(kindName), fmt.Sprintf("%s.yaml", strings.ToLower(kindName)))
+	created = util.WriteIfNotFound(docpath, "example-template", exampleTemplate, a)
+	if !created {
+		if !found {
+			log.Printf("Example %s already exists.", docpath)
+			found = true
+		}
+	}
+
+	exec.Command("mkdir", "-p", filepath.Join("sample")).CombinedOutput()
+	samplepath := filepath.Join("sample", fmt.Sprintf("%s.yaml", strings.ToLower(kindName)))
+	created = util.WriteIfNotFound(samplepath, "sample-template", sampleTemplate, a)
+	if !created {
+		if !found {
+			log.Printf("Sample %s already exists.", docpath)
+			found = true
+		}
+	}
+
 	// write the suite if it is missing
 	typesFileName = fmt.Sprintf("%s_suite_test.go", strings.ToLower(versionName))
 	path = filepath.Join(dir, "pkg", "apis", groupName, versionName, typesFileName)
@@ -533,3 +554,19 @@ var _ = Describe("{{ .Kind }} controller", func() {
 	})
 })
 `
+
+var exampleTemplate = `note: {{ .Kind }} Example
+sample: |
+  apiVersion: {{ .Group }}.{{ .Domain }}/{{ .Version }}
+  kind: {{ .Kind }}
+  metadata:
+    name: {{ lower .Kind }}-example
+  spec:
+`
+
+var sampleTemplate = `apiVersion: {{ .Group }}.{{ .Domain }}/{{ .Version }}
+kind: {{ .Kind }}
+metadata:
+  name: {{ lower .Kind }}-example
+spec:
+`

cmd/apiserver-boot/boot/run/in_cluster.go

@@ -38,7 +38,12 @@ apiserver-boot run in-cluster --name example --namespace default --image gcr.io/
 rm -rf ~/.kube/cache/discovery/
 
 # Run kubectl and check for the new version
-kubectl api-versions`,
+kubectl api-versions
+
+# Create an instance and fetch it
+nano -w samples/<type>.yaml
+kubectl apply -f samples/<type>.yaml
+kubectl get <type>`,
 	Run: RunInCluster,
 }
 

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/<type>.yaml
+kubectl --kubeconfig kubeconfig apply -f samples/<type>.yaml
+kubectl --kubeconfig kubeconfig get <type>`,
 	Run: RunLocal,
 }
 

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/_<group>.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/<type-name>/<type-name>.yaml`
+
+```yaml
+note: Description of your example.
+sample: |
+  apiVersion: <version>
+  kind: <kind>
+  metadata:
+    name: <name>
+  spec:
+    <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: <resource-name>
+namespace: <resource-namespace>
+request: |
+  <request-yaml>
+response: |
+  <response-json>
+```
+
+The docs framework will automatically create per-language / tool example tabs
+using this input.
+
+Locations for operation examples:
+
+- create: `docs/examples/<type-name>/create.yaml`
+- delete: `docs/examples/<type-name>/delete.yaml`
+- list: `docs/examples/<type-name>/list.yaml`
+- patch: `docs/examples/<type-name>/patch.yaml`
+- read: `docs/examples/<type-name>/read.yaml`
+  - **Note:** read does not have a request section
+- replace: `docs/examples/<type-name>/replace.yaml`
+- watch: `docs/examples/<type-name>/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)

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