diff --git a/gen-apidocs/generators/Dockerfile b/gen-apidocs/generators/Dockerfile deleted file mode 100644 index 0f1ab7a0..00000000 --- a/gen-apidocs/generators/Dockerfile +++ /dev/null @@ -1,5 +0,0 @@ -# Hosts static html documentation files - -FROM nginx -MAINTAINER Phillip Wittrock -COPY build/ /usr/share/nginx/html diff --git a/gen-apidocs/generators/md.go b/gen-apidocs/generators/md.go deleted file mode 100644 index e6f0ab74..00000000 --- a/gen-apidocs/generators/md.go +++ /dev/null @@ -1,291 +0,0 @@ -/* -Copyright 2016 The Kubernetes Authors. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. -*/ - -package generators - -import ( - "encoding/json" - "fmt" - "io" - "os" - - "github.com/kubernetes-sigs/reference-docs/gen-apidocs/generators/api" -) - -type Manifest struct { - Docs []Doc `json:"docs,omitempty"` - Title string `json:"title,omitempty"` - Copyright string `json:"copyright,omitempty"` -} - -type MarkdownWriter struct { - Config *api.Config - Manifest Manifest -} - -func NewMarkdownWriter(config *api.Config, copyright, title string) DocWriter { - writer := MarkdownWriter{ - Config: config, - Manifest: Manifest{ - Copyright: copyright, - Title: title, - }, - } - return &writer -} - -func (m *MarkdownWriter) Extension() string { - return ".md" -} - -func (m *MarkdownWriter) DefaultStaticContent(title string) string { - return fmt.Sprintf("# %s\n\n----------\n\n", title) -} - -func (m *MarkdownWriter) WriteOverview() { - writeStaticFile("Overview", "_overview.md", m.DefaultStaticContent("Overview")) - if *api.BuildOps { - m.Manifest.Docs = append(m.Manifest.Docs, Doc{"_overview.md"}) - } -} - -func (m *MarkdownWriter) WriteResourceCategory(name, file string) { - writeStaticFile(name, file + ".md", m.DefaultStaticContent(name)) - m.Manifest.Docs = append(m.Manifest.Docs, Doc{file + ".md"}) -} - -func (m *MarkdownWriter) writeFields(w io.Writer, d *api.Definition) { - fmt.Fprintf(w, "Field | Description\n------------ | -----------\n") - for _, field := range d.Fields { - fmt.Fprintf(w, "`%s`", field.Name) - if field.Link() != "" { - fmt.Fprintf(w, "
*%s*", field.Link()) - } - if field.PatchStrategy != "" { - fmt.Fprintf(w, "
**patch strategy**: *%s*", field.PatchStrategy) - } - if field.PatchMergeKey != "" { - fmt.Fprintf(w, "
**patch merge key**: *%s*", field.PatchMergeKey) - } - fmt.Fprintf(w, " | %s\n", field.DescriptionWithEntities) - } -} - -func (m *MarkdownWriter) writeOtherVersions(w io.Writer, d *api.Definition) { - if d.OtherVersions.Len() != 0 { - fmt.Fprintf(w, "\n\n") - } - fmt.Fprintf(w, "%s\n\n", d.DescriptionWithEntities) -} - -func (m *MarkdownWriter) writeAppearsIn(w io.Writer, d *api.Definition) { - if d.AppearsIn.Len() != 0 { - fmt.Fprintf(w, "\n\n") - } -} - -func (m *MarkdownWriter) WriteDefinition(d *api.Definition) { - fn := "_" + definitionFileName(d) + ".md" - path := *api.ConfigDir + "/includes/" + fn - f, err := os.Create(path) - defer f.Close() - if err != nil { - os.Stderr.WriteString(fmt.Sprintf("%v", err)) - os.Exit(1) - } - fmt.Fprintf(f, "## %s %s %s\n\n", d.Name, d.Version, d.Group) - fmt.Fprintf(f, "Group | Version | Kind\n------------ | ---------- | -----------\n") - fmt.Fprintf(f, "`%s` | `%s` | `%s`\n", d.GroupDisplayName(), d.Version, d.Name) - fmt.Fprintf(f, "\n") - - m.writeOtherVersions(f, d) - m.writeAppearsIn(f, d) - m.writeFields(f, d) - m.Manifest.Docs = append(m.Manifest.Docs, Doc{fn}) -} - -func (m *MarkdownWriter) WriteResource(r *api.Resource) { - fn := "_" + conceptFileName(r.Definition) + ".md" - path := *api.ConfigDir + "/includes/" + fn - f, err := os.Create(path) - defer f.Close() - if err != nil { - os.Stderr.WriteString(fmt.Sprintf("%v", err)) - os.Exit(1) - } - - fmt.Fprintf(f, "-----------\n\n") - fmt.Fprintf(f, "# %s %s", r.Name, r.Definition.Version) - if r.Definition.ShowGroup { - fmt.Fprintf(f, " %s\n", r.Definition.GroupDisplayName()) - } else { - fmt.Fprintf(f, "\n") - } - - if r.Definition.Sample.Sample != "" { - note := r.Definition.Sample.Note - for _, t := range r.Definition.GetSamples() { - // 't' is a ExampleText - fmt.Fprintf(f, ">%s %s\n\n", t.Tab, note) - fmt.Fprintf(f, "```%s\n%s\n```\n\n", t.Type, t.Text) - } - } - - // GVK - fmt.Fprintf(f, "Group | Version | Kind\n------------ | ---------- | -----------\n") - fmt.Fprintf(f, "`%s` | `%s` | `%s`\n\n", r.Definition.GroupDisplayName(), r.Definition.Version, r.Name) - - if r.DescriptionWarning != "" { - fmt.Fprintf(f, "\n\n", r.DescriptionWarning) - } - if r.DescriptionNote != "" { - fmt.Fprintf(f, "\n\n", r.DescriptionNote) - } - - m.writeOtherVersions(f, r.Definition) - m.writeAppearsIn(f, r.Definition) - m.writeFields(f, r.Definition) - - fmt.Fprintf(f, "\n") - if r.Definition.Inline.Len() > 0 { - for _, d := range r.Definition.Inline { - fmt.Fprintf(f, "### %s %s %s\n", d.Name, d.Version, d.Group) - m.writeAppearsIn(f, d) - m.writeFields(f, d) - } - } - - if len(r.Definition.OperationCategories) > 0 { - for _, c := range r.Definition.OperationCategories { - if len(c.Operations) > 0 { - fmt.Fprintf(f, "## %s\n", c.Name) - for _, o := range c.Operations { - fmt.Fprintf(f, "\n## %s\n", o.Type.Name) - - // Example requests - requests := o.GetExampleRequests() - if len(requests) > 0 { - for _, r := range requests { - fmt.Fprintf(f, ">%s %s\n\n", r.Tab, r.Msg) - fmt.Fprintf(f, "```%s\n%s```\n\n", r.Type, r.Text) - } - } - // Example responses - responses := o.GetExampleResponses() - if len(responses) > 0 { - for _, r := range responses { - fmt.Fprintf(f, ">%s %s\n\n", r.Tab, r.Msg) - fmt.Fprintf(f, "```%s\n%s```\n\n", r.Type, r.Text) - } - } - - fmt.Fprintf(f, "%s\n", o.Description()) - fmt.Fprintf(f, "\n### HTTP Request\n\n`%s`\n", o.GetDisplayHttp()) - - // Operation path params - if o.PathParams.Len() > 0 { - fmt.Fprintf(f, "\n### Path Parameters\n\n") - fmt.Fprintf(f, "Parameter | Description\n------------ | -----------\n") - for _, p := range o.PathParams { - fmt.Fprintf(f, "`%s`", p.Name) - if p.Link() != "" { - fmt.Fprintf(f, "
*%s*", p.Link()) - } - fmt.Fprintf(f, " | %s\n", p.Description) - } - } - - // operation query params - if o.QueryParams.Len() > 0 { - fmt.Fprintf(f, "\n### Query Parameters\n\n") - fmt.Fprintf(f, "Parameter | Description\n------------ | -----------\n") - for _, p := range o.QueryParams { - fmt.Fprintf(f, "`%s`", p.Name) - if p.Link() != "" { - fmt.Fprintf(f, "
*%s*", p.Link()) - } - fmt.Fprintf(f, " | %s\n", p.Description) - } - } - // operation body params - if o.BodyParams.Len() > 0 { - fmt.Fprintf(f, "\n### Body Parameters\n\n") - fmt.Fprintf(f, "Parameter | Description\n------------ | -----------\n") - for _, p := range o.BodyParams { - fmt.Fprintf(f, "`%s`", p.Name) - if p.Link() != "" { - fmt.Fprintf(f, "
*%s*", p.Link()) - } - fmt.Fprintf(f, " | %s\n", p.Description) - } - } - - // operation response body - if o.HttpResponses.Len() > 0 { - fmt.Fprintf(f, "\n### Response\n\n") - fmt.Fprintf(f, "Code | Description\n------------ | -----------\n") - for _, r := range o.HttpResponses { - fmt.Fprintf(f, "%s ", r.Code) - if r.Field.Link() != "" { - fmt.Fprintf(f, "
*%s*", r.Field.Link()) - } - fmt.Fprintf(f, " | %s\n", r.Field.Description) - } - } - } - } - } - } - - m.Manifest.Docs = append(m.Manifest.Docs, Doc{fn}) -} - -func (m *MarkdownWriter) WriteDefinitionsOverview() { - writeStaticFile("Definitions", "_definitions.md", m.DefaultStaticContent("Definitions")) - m.Manifest.Docs = append(m.Manifest.Docs, Doc{"_definitions.md"}) -} - -func (m *MarkdownWriter) WriteOldVersionsOverview() { - writeStaticFile("Old Versions", "_oldversions.md", m.DefaultStaticContent("Old Versions")) - m.Manifest.Docs = append(m.Manifest.Docs, Doc{"_oldversions.md"}) -} - -func (m *MarkdownWriter) Finalize() { - // Write out the json manifest - jsonbytes, err := json.MarshalIndent(m.Manifest, "", " ") - if err != nil { - fmt.Printf("Could not Marshal manfiest %+v due to error: %v.\n", m.Manifest, err) - } else { - jsonfile, err := os.Create(*api.ConfigDir + "/" + JsonOutputFile) - if err != nil { - fmt.Printf("Could not create file %s due to error: %v.\n", JsonOutputFile, err) - } else { - defer jsonfile.Close() - _, err := jsonfile.Write(jsonbytes) - if err != nil { - fmt.Printf("Failed to write bytes %s to file %s: %v.\n", jsonbytes, JsonOutputFile, err) - } - } - } -} diff --git a/gen-apidocs/generators/static_includes/_cluster.md b/gen-apidocs/generators/static_includes/_cluster.md deleted file mode 100644 index 5c74168e..00000000 --- a/gen-apidocs/generators/static_includes/_cluster.md +++ /dev/null @@ -1,5 +0,0 @@ -# CLUSTER - -Cluster resources are responsible for defining configuration of the cluster itself, and are generally only used by cluster operators. - ------------- diff --git a/gen-apidocs/generators/static_includes/_config.md b/gen-apidocs/generators/static_includes/_config.md deleted file mode 100644 index 6eb87f57..00000000 --- a/gen-apidocs/generators/static_includes/_config.md +++ /dev/null @@ -1,11 +0,0 @@ -# CONFIG & STORAGE - -Config and Storage resources are responsible for injecting data into your applications and persisting data externally to your container. - -Common resource types: - -- [ConfigMaps](#configmap-v1-core) for providing text key value pairs injected into the application through environment variables, command line arguments, or files -- [Secrets](#secret-v1-core) for providing binary data injected into the application through files -- [Volumes](#volume-v1-core) for providing a filesystem external to the Container. Maybe shared across Containers within the same Pod and have a lifetime persisting beyond a Container or Pod. - ------------- diff --git a/gen-apidocs/generators/static_includes/_definitions.md b/gen-apidocs/generators/static_includes/_definitions.md deleted file mode 100644 index 337695b8..00000000 --- a/gen-apidocs/generators/static_includes/_definitions.md +++ /dev/null @@ -1,3 +0,0 @@ -# DEFINITIONS - -This section contains definitions for objects used in the Kubernetes APIs. diff --git a/gen-apidocs/generators/static_includes/_meta.md b/gen-apidocs/generators/static_includes/_meta.md deleted file mode 100644 index 9bb4fbfd..00000000 --- a/gen-apidocs/generators/static_includes/_meta.md +++ /dev/null @@ -1,12 +0,0 @@ -# METADATA - -Metadata resources are responsible for configuring behavior of your other Resources within the Cluster. - -Common resource types: - -- [HorizontalPodAutoscaler](#horizontalpodautoscaler-v1-autoscaling) (HPA) for automatically scaling the replicacount of your workloads in response to load -- [PodDisruptionBudget](#poddisruptionbudget-v1alpha1) for configuring how many replicas in a given workload maybe made concurrently unavailable when performing maintenance. -- [ThirdPartyResource](#thirdpartyresource-v1beta1) for extending the Kubernetes APIs with your own types -- [Event](#event-v1-core) for notification of resource lifecycle events in the cluster. - ------------- diff --git a/gen-apidocs/generators/static_includes/_oldversions.md b/gen-apidocs/generators/static_includes/_oldversions.md deleted file mode 100644 index 4f5580f8..00000000 --- a/gen-apidocs/generators/static_includes/_oldversions.md +++ /dev/null @@ -1,3 +0,0 @@ -# OLD API VERSIONS - -This section contains older versions of resources shown above. diff --git a/gen-apidocs/generators/static_includes/_overview.md b/gen-apidocs/generators/static_includes/_overview.md deleted file mode 100644 index b85407b6..00000000 --- a/gen-apidocs/generators/static_includes/_overview.md +++ /dev/null @@ -1,92 +0,0 @@ -# API OVERVIEW - -Welcome to the Kubernetes API. You can use the Kubernetes API to read -and write Kubernetes resource objects via a Kubernetes API endpoint. - -## Resource Categories - -This is a high-level overview of the basic types of resources provide by the Kubernetes API and their primary functions. - -**Workloads** are objects you use to manage and run your containers on the cluster. - -**Discovery & LB** resources are objects you use to "stitch" your workloads together into an externally accessible, load-balanced Service. - -**Config & Storage** resources are objects you use to inject initialization data into your applications, and to persist data that is external to your container. - -**Cluster** resources objects define how the cluster itself is configured; these are typically used only by cluster operators. - -**Metadata** resources are objects you use to configure the behavior of other resources within the cluster, such as HorizontalPodAutoscaler for scaling workloads. - ------------- - -## Resource Objects - -Resource objects typically have 3 components: - -- **ResourceSpec**: This is defined by the user and describes the desired state of system. Fill this in when creating or updating an -object. -- **ResourceStatus**: This is filled in by the server and reports the current state of the system. Only kubernetes components should fill -this in -- **Resource ObjectMeta**: This is metadata about the resource, such as its name, type, api version, annotations, and labels. This contains -fields that maybe updated both by the end user and the system (e.g. annotations) - ------------- - -## Resource Operations - -Most resources provide the following Operations: - -#### Create: -Create operations will create the resource in the storage backend. After a resource is create the system will apply -the desired state. - -#### Update: -Updates come in 2 forms: **Replace** and **Patch** - -**Replace**: -Replacing a resource object will update the resource by replacing the existing spec with the provided one. For -read-then-write operations this is safe because an optimistic lock failure will occur if the resource was modified -between the read and write. *Note*: The *Resource*Status will be ignored by the system and will not be updated. -To update the status, one must invoke the specific status update operation. - -Note: Replacing a resource object may not result immediately in changes being propagated to downstream objects. For instance -replacing a *ConfigMap* or *Secret* resource will not result in all *Pod*s seeing the changes unless the *Pod*s are -restarted out of band. - -**Patch**: -Patch will apply a change to a specific field. How the change is merged is defined per field. Lists may either be -replaced or merged. Merging lists will not preserve ordering. - -**Patches will never cause optimistic locking failures, and the last write will win.** Patches are recommended -when the full state is not read before an update, or when failing on optimistic locking is undesirable. *When patching -complex types, arrays and maps, how the patch is applied is defined on a per-field basis and may either replace -the field's current value, or merge the contents into the current value.* - -#### Read - -Reads come in 3 forms: **Get**, **List** and **Watch** - -**Get**: Get will retrieve a specific resource object by name. - -**List**: List will retrieve all resource objects of a specific type within a namespace, and the results can be restricted to resources matching a selector query. - -**List All Namespaces**: Like *List* but retrieves resources across all namespaces. - -**Watch**: Watch will stream results for an object(s) as it is updated. Similar to a callback, watch is used to respond to resource changes. - -#### Delete - -Delete will delete a resource. Depending on the specific resource, child objects may or may not be garbage collected by the server. See -notes on specific resource objects for details. - -#### Additional Operations - -Resources may define additional operations specific to that resource type. - -**Rollback**: Rollback a PodTemplate to a previous version. Only available for some resource types. - -**Read / Write Scale**: Read or Update the number of replicas for the given resource. Only available for some resource types. - -**Read / Write Status**: Read or Update the Status for a resource object. The Status can only changed through these update operations. - ------------- diff --git a/gen-apidocs/generators/static_includes/_servicediscovery.md b/gen-apidocs/generators/static_includes/_servicediscovery.md deleted file mode 100644 index 3cd6f55d..00000000 --- a/gen-apidocs/generators/static_includes/_servicediscovery.md +++ /dev/null @@ -1,13 +0,0 @@ -# DISCOVERY & LOAD BALANCING - -Discovery and Load Balancing resources are responsible for stitching your workloads together into an accessible Loadbalanced Service. By default, -[Workloads](#workloads) are only accessible within the cluster, and they must be exposed externally using a either -a *LoadBalancer* or *NodePort* [Service](#service-v1-core). For development, internally accessible -Workloads can be accessed via proxy through the api master using the `kubectl proxy` command. - -Common resource types: - -- [Services](#service-v1-core) for providing a single ip endpoint loadbalanced across multiple Workload replicas. -- [Ingress](#ingress-v1beta1-extensions) for providing a https(s) endpoint http(s) routed to one or more *Services* - ------------- diff --git a/gen-apidocs/generators/static_includes/_workloads.md b/gen-apidocs/generators/static_includes/_workloads.md deleted file mode 100644 index 381e0d34..00000000 --- a/gen-apidocs/generators/static_includes/_workloads.md +++ /dev/null @@ -1,14 +0,0 @@ -# WORKLOADS - -Workloads resources are responsible for managing and running your containers on the cluster. [Containers](#container-v1-core) are created -by Controllers through [Pods](#pod-v1-core). Pods run Containers and provide environmental dependencies such as shared or -persistent storage [Volumes](#volume-v1-core) and [Configuration](#configmap-v1-core) or [Secret](#secret-v1-core) data injected into the -container. - -The most common Controllers are: - -- [Deployments](#deployment-v1-apps) for stateless persistent apps (e.g. http servers) -- [StatefulSets](#statefulset-v1-apps) for stateful persistent apps (e.g. databases) -- [Jobs](#job-v1-batch) for run-to-completion apps (e.g. batch jobs). - ------------- diff --git a/gen-apidocs/generators/util.go b/gen-apidocs/generators/util.go index f100d29f..c4156ce4 100644 --- a/gen-apidocs/generators/util.go +++ b/gen-apidocs/generators/util.go @@ -22,8 +22,6 @@ import ( "strings" ) -const JsonOutputFile = "manifest.json" - func PrintInfo(config *api.Config) { definitions := config.Definitions @@ -84,74 +82,3 @@ func PrintInfo(config *api.Config) { // } //} } - -func PrintDebug(config *api.Config) { - operations := config.Operations - definitions := config.Definitions - - fmt.Printf("----------------------------------\n") - fmt.Printf("Operations with no Definitions:\n") - for _, o := range operations { - if o.Definition == nil { - fmt.Printf("%s\n", o.ID) - } - } - - fmt.Printf("----------------------------------\n") - fmt.Printf("\n\nDefinitions in Toc:\n") - for name, d := range definitions.All { - if d.InToc { - fmt.Printf("\n\n%s \n\tFields:\n", name) - for _, f := range d.Fields { - if f.Definition != nil { - fmt.Printf("\t\t%s:[%s](%s) - (%s)\n", f.Name, f.Type, f.Definition.Name, f.Description) - } else { - fmt.Printf("\t\t%s:%s - (%s)\n", f.Name, f.Type, f.Description) - } - } - for _, oc := range d.OperationCategories { - fmt.Printf("\t Operation Category [%s]\n", oc.Name) - for _, o := range oc.Operations { - fmt.Printf("\t\t %s (%s) Type: %s\n", o.Type.Name, o.Path, o.Definition.Name) - if len(o.PathParams) > 0 { - fmt.Printf("\t\t\t Path Params\n") - for _, p := range o.PathParams { - fmt.Printf("\t\t\t %s:%s - (%s)\n", p.Name, p.Type, p.Description) - } - } - if len(o.QueryParams) > 0 { - fmt.Printf("\t\t\t Query Params\n") - for _, p := range o.QueryParams { - fmt.Printf("\t\t\t %s:%s - (%s)\n", p.Name, p.Type, p.Description) - } - } - fmt.Printf("\t\t\t Responses\n") - for _, hr := range o.HttpResponses { - fmt.Printf("\t\t\t %s:%s - (%s)\n", hr.Code, hr.Type, hr.Definition.Name) - } - } - } - } - } - - fmt.Printf("----------------------------------\n") - fmt.Printf("\n\nOther Definitions:\n") - for name, d := range definitions.All { - if !d.InToc && d.FoundInField { - fmt.Printf("\n\n%s \n\tFields:\n", name) - for _, f := range d.Fields { - if f.Definition != nil { - fmt.Printf("\t\t%s:[%s](%s) - (%s)\n", f.Name, f.Type, f.Definition.Name, f.Description) - } else { - fmt.Printf("\t\t%s:%s - (%s)\n", f.Name, f.Type, f.Description) - } - } - for _, oc := range d.OperationCategories { - fmt.Printf("\t Operation Category [%s]\n", oc.Name) - for _, o := range oc.Operations { - fmt.Printf("\t\t %s (%s) Type: %s\n", o.Type.Name, o.Path, o.Definition.Name) - } - } - } - } -} diff --git a/gen-apidocs/generators/writer.go b/gen-apidocs/generators/writer.go index 5e358695..073db366 100644 --- a/gen-apidocs/generators/writer.go +++ b/gen-apidocs/generators/writer.go @@ -16,7 +16,6 @@ limitations under the License. package generators import ( - "flag" "fmt" "os" "path/filepath" @@ -43,9 +42,6 @@ type DocWriter interface { Finalize() } -var Backend = flag.String("backend", "go", - "Specify the backend to use for doc generation. Valid options are 'brodocs', 'go'.") - func GenerateFiles() { // Load the yaml config config := api.NewConfig() @@ -62,15 +58,7 @@ func GenerateFiles() { title = "Kubernetes API Reference Docs" } - var writer DocWriter - if *Backend == "brodocs" { - writer = NewMarkdownWriter(config, copyright, title) - } else if *Backend == "go" { - writer = NewHTMLWriter(config, copyright, title) - } else { - panic(fmt.Sprintf("Unknown backend specified: %s", *Backend)) - } - + writer := NewHTMLWriter(config, copyright, title) writer.WriteOverview() // Write resource definitions