From f49317d7e4c0b96d45d1efad404ef4d77115ea64 Mon Sep 17 00:00:00 2001 From: Matt Moyer Date: Mon, 31 Aug 2020 11:27:39 -0500 Subject: [PATCH] Add some generated API documentation. (#81) Add some generated API documentation using https://github.com/elastic/crd-ref-docs which is now packaged in the codegen image. --- apis/README.md | 5 + apis/crdpinniped/v1alpha1/register.go.tmpl | 1 - apis/pinniped/register.go.tmpl | 1 - apis/pinniped/v1alpha1/register.go.tmpl | 1 - generated/1.17/README.adoc | 199 ++++++++++++++++++ .../apis/crdpinniped/v1alpha1/register.go | 1 - generated/1.17/apis/pinniped/register.go | 1 - .../1.17/apis/pinniped/v1alpha1/register.go | 1 - generated/1.18/README.adoc | 199 ++++++++++++++++++ .../apis/crdpinniped/v1alpha1/register.go | 1 - generated/1.18/apis/pinniped/register.go | 1 - .../1.18/apis/pinniped/v1alpha1/register.go | 1 - generated/1.19/README.adoc | 199 ++++++++++++++++++ .../apis/crdpinniped/v1alpha1/register.go | 1 - generated/1.19/apis/pinniped/register.go | 1 - .../1.19/apis/pinniped/v1alpha1/register.go | 1 - go.sum | 7 - hack/lib/docs/config.yaml | 12 ++ hack/lib/docs/templates/gv_details.tpl | 19 ++ hack/lib/docs/templates/gv_list.tpl | 19 ++ hack/lib/docs/templates/type.tpl | 35 +++ hack/lib/docs/templates/type_members.tpl | 8 + hack/lib/update-codegen.sh | 10 + 23 files changed, 705 insertions(+), 19 deletions(-) create mode 100644 apis/README.md create mode 100644 generated/1.17/README.adoc create mode 100644 generated/1.18/README.adoc create mode 100644 generated/1.19/README.adoc create mode 100644 hack/lib/docs/config.yaml create mode 100644 hack/lib/docs/templates/gv_details.tpl create mode 100644 hack/lib/docs/templates/gv_list.tpl create mode 100644 hack/lib/docs/templates/type.tpl create mode 100644 hack/lib/docs/templates/type_members.tpl diff --git a/apis/README.md b/apis/README.md new file mode 100644 index 00000000..2855f3d1 --- /dev/null +++ b/apis/README.md @@ -0,0 +1,5 @@ +# API Generation Templates + +This directory contains a template for generating our Kubernetes API code across several Kubernetes versions. + +See the [`./generated`](../generated) directory for the rendered output. diff --git a/apis/crdpinniped/v1alpha1/register.go.tmpl b/apis/crdpinniped/v1alpha1/register.go.tmpl index 1a7cd407..95eae6f9 100644 --- a/apis/crdpinniped/v1alpha1/register.go.tmpl +++ b/apis/crdpinniped/v1alpha1/register.go.tmpl @@ -3,7 +3,6 @@ Copyright 2020 VMware, Inc. SPDX-License-Identifier: Apache-2.0 */ -//nolint:gochecknoglobals,gochecknoinits package v1alpha1 import ( diff --git a/apis/pinniped/register.go.tmpl b/apis/pinniped/register.go.tmpl index c6570bc7..765cfc0d 100644 --- a/apis/pinniped/register.go.tmpl +++ b/apis/pinniped/register.go.tmpl @@ -3,7 +3,6 @@ Copyright 2020 VMware, Inc. SPDX-License-Identifier: Apache-2.0 */ -//nolint:gochecknoglobals package pinniped import ( diff --git a/apis/pinniped/v1alpha1/register.go.tmpl b/apis/pinniped/v1alpha1/register.go.tmpl index b1ae3aea..c4256ec2 100644 --- a/apis/pinniped/v1alpha1/register.go.tmpl +++ b/apis/pinniped/v1alpha1/register.go.tmpl @@ -3,7 +3,6 @@ Copyright 2020 VMware, Inc. SPDX-License-Identifier: Apache-2.0 */ -//nolint:gochecknoglobals,gochecknoinits package v1alpha1 import ( diff --git a/generated/1.17/README.adoc b/generated/1.17/README.adoc new file mode 100644 index 00000000..70c3317e --- /dev/null +++ b/generated/1.17/README.adoc @@ -0,0 +1,199 @@ +// Generated documentation. Please do not edit. +:anchor_prefix: k8s-api + +[id="{p}-api-reference"] +== API Reference + +.Packages +- xref:{anchor_prefix}-crd-pinniped-dev-v1alpha1[$$crd.pinniped.dev/v1alpha1$$] +- xref:{anchor_prefix}-pinniped-dev-v1alpha1[$$pinniped.dev/v1alpha1$$] + + +[id="{anchor_prefix}-crd-pinniped-dev-v1alpha1"] +=== crd.pinniped.dev/v1alpha1 + +Package v1alpha1 is the v1alpha1 version of the API. + + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-crdpinniped-v1alpha1-credentialissuerconfig"] +==== CredentialIssuerConfig + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-crdpinniped-v1alpha1-credentialissuerconfiglist[$$CredentialIssuerConfigList$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`metadata`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.17/#objectmeta-v1-meta[$$ObjectMeta$$]__ | Refer to Kubernetes API documentation for fields of `metadata`. + +| *`status`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-crdpinniped-v1alpha1-credentialissuerconfigstatus[$$CredentialIssuerConfigStatus$$]__ | +|=== + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-crdpinniped-v1alpha1-credentialissuerconfigkubeconfiginfo"] +==== CredentialIssuerConfigKubeConfigInfo + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-crdpinniped-v1alpha1-credentialissuerconfigstatus[$$CredentialIssuerConfigStatus$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`server`* __string__ | The K8s API server URL. Required. +| *`certificateAuthorityData`* __string__ | The K8s API server CA bundle. Required. +|=== + + + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-crdpinniped-v1alpha1-credentialissuerconfigstatus"] +==== CredentialIssuerConfigStatus + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-crdpinniped-v1alpha1-credentialissuerconfig[$$CredentialIssuerConfig$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`strategies`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-crdpinniped-v1alpha1-credentialissuerconfigstrategy[$$CredentialIssuerConfigStrategy$$] array__ | +| *`kubeConfigInfo`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-crdpinniped-v1alpha1-credentialissuerconfigkubeconfiginfo[$$CredentialIssuerConfigKubeConfigInfo$$]__ | +|=== + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-crdpinniped-v1alpha1-credentialissuerconfigstrategy"] +==== CredentialIssuerConfigStrategy + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-crdpinniped-v1alpha1-credentialissuerconfigstatus[$$CredentialIssuerConfigStatus$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`type`* __StrategyType__ | +| *`status`* __StrategyStatus__ | +| *`reason`* __StrategyReason__ | +| *`message`* __string__ | +| *`lastUpdateTime`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.17/#time-v1-meta[$$Time$$]__ | +|=== + + + +[id="{anchor_prefix}-pinniped-dev-v1alpha1"] +=== pinniped.dev/v1alpha1 + +Package v1alpha1 is the v1alpha1 version of the API. + + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-pinniped-v1alpha1-credentialrequest"] +==== CredentialRequest + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-pinniped-v1alpha1-credentialrequestlist[$$CredentialRequestList$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`metadata`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.17/#objectmeta-v1-meta[$$ObjectMeta$$]__ | Refer to Kubernetes API documentation for fields of `metadata`. + +| *`spec`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-pinniped-v1alpha1-credentialrequestspec[$$CredentialRequestSpec$$]__ | +| *`status`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-pinniped-v1alpha1-credentialrequeststatus[$$CredentialRequestStatus$$]__ | +|=== + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-pinniped-v1alpha1-credentialrequestcredential"] +==== CredentialRequestCredential + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-pinniped-v1alpha1-credentialrequeststatus[$$CredentialRequestStatus$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`expirationTimestamp`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.17/#time-v1-meta[$$Time$$]__ | ExpirationTimestamp indicates a time when the provided credentials expire. +| *`token`* __string__ | Token is a bearer token used by the client for request authentication. +| *`clientCertificateData`* __string__ | PEM-encoded client TLS certificates (including intermediates, if any). +| *`clientKeyData`* __string__ | PEM-encoded private key for the above certificate. +|=== + + + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-pinniped-v1alpha1-credentialrequestspec"] +==== CredentialRequestSpec + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-pinniped-v1alpha1-credentialrequest[$$CredentialRequest$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`type`* __CredentialType__ | Type of credential. +| *`token`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-pinniped-v1alpha1-credentialrequesttokencredential[$$CredentialRequestTokenCredential$$]__ | Token credential (when Type == TokenCredentialType). +|=== + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-pinniped-v1alpha1-credentialrequeststatus"] +==== CredentialRequestStatus + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-pinniped-v1alpha1-credentialrequest[$$CredentialRequest$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`credential`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-pinniped-v1alpha1-credentialrequestcredential[$$CredentialRequestCredential$$]__ | A Credential will be returned for a successful credential request. +| *`message`* __string__ | An error message will be returned for an unsuccessful credential request. +|=== + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-pinniped-v1alpha1-credentialrequesttokencredential"] +==== CredentialRequestTokenCredential + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-17-apis-pinniped-v1alpha1-credentialrequestspec[$$CredentialRequestSpec$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`value`* __string__ | Value of the bearer token supplied with the credential request. +|=== + + diff --git a/generated/1.17/apis/crdpinniped/v1alpha1/register.go b/generated/1.17/apis/crdpinniped/v1alpha1/register.go index 1a7cd407..95eae6f9 100644 --- a/generated/1.17/apis/crdpinniped/v1alpha1/register.go +++ b/generated/1.17/apis/crdpinniped/v1alpha1/register.go @@ -3,7 +3,6 @@ Copyright 2020 VMware, Inc. SPDX-License-Identifier: Apache-2.0 */ -//nolint:gochecknoglobals,gochecknoinits package v1alpha1 import ( diff --git a/generated/1.17/apis/pinniped/register.go b/generated/1.17/apis/pinniped/register.go index c6570bc7..765cfc0d 100644 --- a/generated/1.17/apis/pinniped/register.go +++ b/generated/1.17/apis/pinniped/register.go @@ -3,7 +3,6 @@ Copyright 2020 VMware, Inc. SPDX-License-Identifier: Apache-2.0 */ -//nolint:gochecknoglobals package pinniped import ( diff --git a/generated/1.17/apis/pinniped/v1alpha1/register.go b/generated/1.17/apis/pinniped/v1alpha1/register.go index b1ae3aea..c4256ec2 100644 --- a/generated/1.17/apis/pinniped/v1alpha1/register.go +++ b/generated/1.17/apis/pinniped/v1alpha1/register.go @@ -3,7 +3,6 @@ Copyright 2020 VMware, Inc. SPDX-License-Identifier: Apache-2.0 */ -//nolint:gochecknoglobals,gochecknoinits package v1alpha1 import ( diff --git a/generated/1.18/README.adoc b/generated/1.18/README.adoc new file mode 100644 index 00000000..23e90b60 --- /dev/null +++ b/generated/1.18/README.adoc @@ -0,0 +1,199 @@ +// Generated documentation. Please do not edit. +:anchor_prefix: k8s-api + +[id="{p}-api-reference"] +== API Reference + +.Packages +- xref:{anchor_prefix}-crd-pinniped-dev-v1alpha1[$$crd.pinniped.dev/v1alpha1$$] +- xref:{anchor_prefix}-pinniped-dev-v1alpha1[$$pinniped.dev/v1alpha1$$] + + +[id="{anchor_prefix}-crd-pinniped-dev-v1alpha1"] +=== crd.pinniped.dev/v1alpha1 + +Package v1alpha1 is the v1alpha1 version of the API. + + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-crdpinniped-v1alpha1-credentialissuerconfig"] +==== CredentialIssuerConfig + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-crdpinniped-v1alpha1-credentialissuerconfiglist[$$CredentialIssuerConfigList$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`metadata`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#objectmeta-v1-meta[$$ObjectMeta$$]__ | Refer to Kubernetes API documentation for fields of `metadata`. + +| *`status`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-crdpinniped-v1alpha1-credentialissuerconfigstatus[$$CredentialIssuerConfigStatus$$]__ | +|=== + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-crdpinniped-v1alpha1-credentialissuerconfigkubeconfiginfo"] +==== CredentialIssuerConfigKubeConfigInfo + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-crdpinniped-v1alpha1-credentialissuerconfigstatus[$$CredentialIssuerConfigStatus$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`server`* __string__ | The K8s API server URL. Required. +| *`certificateAuthorityData`* __string__ | The K8s API server CA bundle. Required. +|=== + + + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-crdpinniped-v1alpha1-credentialissuerconfigstatus"] +==== CredentialIssuerConfigStatus + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-crdpinniped-v1alpha1-credentialissuerconfig[$$CredentialIssuerConfig$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`strategies`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-crdpinniped-v1alpha1-credentialissuerconfigstrategy[$$CredentialIssuerConfigStrategy$$] array__ | +| *`kubeConfigInfo`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-crdpinniped-v1alpha1-credentialissuerconfigkubeconfiginfo[$$CredentialIssuerConfigKubeConfigInfo$$]__ | +|=== + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-crdpinniped-v1alpha1-credentialissuerconfigstrategy"] +==== CredentialIssuerConfigStrategy + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-crdpinniped-v1alpha1-credentialissuerconfigstatus[$$CredentialIssuerConfigStatus$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`type`* __StrategyType__ | +| *`status`* __StrategyStatus__ | +| *`reason`* __StrategyReason__ | +| *`message`* __string__ | +| *`lastUpdateTime`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#time-v1-meta[$$Time$$]__ | +|=== + + + +[id="{anchor_prefix}-pinniped-dev-v1alpha1"] +=== pinniped.dev/v1alpha1 + +Package v1alpha1 is the v1alpha1 version of the API. + + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-pinniped-v1alpha1-credentialrequest"] +==== CredentialRequest + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-pinniped-v1alpha1-credentialrequestlist[$$CredentialRequestList$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`metadata`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#objectmeta-v1-meta[$$ObjectMeta$$]__ | Refer to Kubernetes API documentation for fields of `metadata`. + +| *`spec`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-pinniped-v1alpha1-credentialrequestspec[$$CredentialRequestSpec$$]__ | +| *`status`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-pinniped-v1alpha1-credentialrequeststatus[$$CredentialRequestStatus$$]__ | +|=== + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-pinniped-v1alpha1-credentialrequestcredential"] +==== CredentialRequestCredential + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-pinniped-v1alpha1-credentialrequeststatus[$$CredentialRequestStatus$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`expirationTimestamp`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#time-v1-meta[$$Time$$]__ | ExpirationTimestamp indicates a time when the provided credentials expire. +| *`token`* __string__ | Token is a bearer token used by the client for request authentication. +| *`clientCertificateData`* __string__ | PEM-encoded client TLS certificates (including intermediates, if any). +| *`clientKeyData`* __string__ | PEM-encoded private key for the above certificate. +|=== + + + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-pinniped-v1alpha1-credentialrequestspec"] +==== CredentialRequestSpec + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-pinniped-v1alpha1-credentialrequest[$$CredentialRequest$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`type`* __CredentialType__ | Type of credential. +| *`token`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-pinniped-v1alpha1-credentialrequesttokencredential[$$CredentialRequestTokenCredential$$]__ | Token credential (when Type == TokenCredentialType). +|=== + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-pinniped-v1alpha1-credentialrequeststatus"] +==== CredentialRequestStatus + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-pinniped-v1alpha1-credentialrequest[$$CredentialRequest$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`credential`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-pinniped-v1alpha1-credentialrequestcredential[$$CredentialRequestCredential$$]__ | A Credential will be returned for a successful credential request. +| *`message`* __string__ | An error message will be returned for an unsuccessful credential request. +|=== + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-pinniped-v1alpha1-credentialrequesttokencredential"] +==== CredentialRequestTokenCredential + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-18-apis-pinniped-v1alpha1-credentialrequestspec[$$CredentialRequestSpec$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`value`* __string__ | Value of the bearer token supplied with the credential request. +|=== + + diff --git a/generated/1.18/apis/crdpinniped/v1alpha1/register.go b/generated/1.18/apis/crdpinniped/v1alpha1/register.go index 1a7cd407..95eae6f9 100644 --- a/generated/1.18/apis/crdpinniped/v1alpha1/register.go +++ b/generated/1.18/apis/crdpinniped/v1alpha1/register.go @@ -3,7 +3,6 @@ Copyright 2020 VMware, Inc. SPDX-License-Identifier: Apache-2.0 */ -//nolint:gochecknoglobals,gochecknoinits package v1alpha1 import ( diff --git a/generated/1.18/apis/pinniped/register.go b/generated/1.18/apis/pinniped/register.go index c6570bc7..765cfc0d 100644 --- a/generated/1.18/apis/pinniped/register.go +++ b/generated/1.18/apis/pinniped/register.go @@ -3,7 +3,6 @@ Copyright 2020 VMware, Inc. SPDX-License-Identifier: Apache-2.0 */ -//nolint:gochecknoglobals package pinniped import ( diff --git a/generated/1.18/apis/pinniped/v1alpha1/register.go b/generated/1.18/apis/pinniped/v1alpha1/register.go index b1ae3aea..c4256ec2 100644 --- a/generated/1.18/apis/pinniped/v1alpha1/register.go +++ b/generated/1.18/apis/pinniped/v1alpha1/register.go @@ -3,7 +3,6 @@ Copyright 2020 VMware, Inc. SPDX-License-Identifier: Apache-2.0 */ -//nolint:gochecknoglobals,gochecknoinits package v1alpha1 import ( diff --git a/generated/1.19/README.adoc b/generated/1.19/README.adoc new file mode 100644 index 00000000..dd0c7471 --- /dev/null +++ b/generated/1.19/README.adoc @@ -0,0 +1,199 @@ +// Generated documentation. Please do not edit. +:anchor_prefix: k8s-api + +[id="{p}-api-reference"] +== API Reference + +.Packages +- xref:{anchor_prefix}-crd-pinniped-dev-v1alpha1[$$crd.pinniped.dev/v1alpha1$$] +- xref:{anchor_prefix}-pinniped-dev-v1alpha1[$$pinniped.dev/v1alpha1$$] + + +[id="{anchor_prefix}-crd-pinniped-dev-v1alpha1"] +=== crd.pinniped.dev/v1alpha1 + +Package v1alpha1 is the v1alpha1 version of the API. + + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-crdpinniped-v1alpha1-credentialissuerconfig"] +==== CredentialIssuerConfig + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-crdpinniped-v1alpha1-credentialissuerconfiglist[$$CredentialIssuerConfigList$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`metadata`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#objectmeta-v1-meta[$$ObjectMeta$$]__ | Refer to Kubernetes API documentation for fields of `metadata`. + +| *`status`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-crdpinniped-v1alpha1-credentialissuerconfigstatus[$$CredentialIssuerConfigStatus$$]__ | +|=== + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-crdpinniped-v1alpha1-credentialissuerconfigkubeconfiginfo"] +==== CredentialIssuerConfigKubeConfigInfo + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-crdpinniped-v1alpha1-credentialissuerconfigstatus[$$CredentialIssuerConfigStatus$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`server`* __string__ | The K8s API server URL. Required. +| *`certificateAuthorityData`* __string__ | The K8s API server CA bundle. Required. +|=== + + + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-crdpinniped-v1alpha1-credentialissuerconfigstatus"] +==== CredentialIssuerConfigStatus + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-crdpinniped-v1alpha1-credentialissuerconfig[$$CredentialIssuerConfig$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`strategies`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-crdpinniped-v1alpha1-credentialissuerconfigstrategy[$$CredentialIssuerConfigStrategy$$] array__ | +| *`kubeConfigInfo`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-crdpinniped-v1alpha1-credentialissuerconfigkubeconfiginfo[$$CredentialIssuerConfigKubeConfigInfo$$]__ | +|=== + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-crdpinniped-v1alpha1-credentialissuerconfigstrategy"] +==== CredentialIssuerConfigStrategy + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-crdpinniped-v1alpha1-credentialissuerconfigstatus[$$CredentialIssuerConfigStatus$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`type`* __StrategyType__ | +| *`status`* __StrategyStatus__ | +| *`reason`* __StrategyReason__ | +| *`message`* __string__ | +| *`lastUpdateTime`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#time-v1-meta[$$Time$$]__ | +|=== + + + +[id="{anchor_prefix}-pinniped-dev-v1alpha1"] +=== pinniped.dev/v1alpha1 + +Package v1alpha1 is the v1alpha1 version of the API. + + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-pinniped-v1alpha1-credentialrequest"] +==== CredentialRequest + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-pinniped-v1alpha1-credentialrequestlist[$$CredentialRequestList$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`metadata`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#objectmeta-v1-meta[$$ObjectMeta$$]__ | Refer to Kubernetes API documentation for fields of `metadata`. + +| *`spec`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-pinniped-v1alpha1-credentialrequestspec[$$CredentialRequestSpec$$]__ | +| *`status`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-pinniped-v1alpha1-credentialrequeststatus[$$CredentialRequestStatus$$]__ | +|=== + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-pinniped-v1alpha1-credentialrequestcredential"] +==== CredentialRequestCredential + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-pinniped-v1alpha1-credentialrequeststatus[$$CredentialRequestStatus$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`expirationTimestamp`* __link:https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#time-v1-meta[$$Time$$]__ | ExpirationTimestamp indicates a time when the provided credentials expire. +| *`token`* __string__ | Token is a bearer token used by the client for request authentication. +| *`clientCertificateData`* __string__ | PEM-encoded client TLS certificates (including intermediates, if any). +| *`clientKeyData`* __string__ | PEM-encoded private key for the above certificate. +|=== + + + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-pinniped-v1alpha1-credentialrequestspec"] +==== CredentialRequestSpec + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-pinniped-v1alpha1-credentialrequest[$$CredentialRequest$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`type`* __CredentialType__ | Type of credential. +| *`token`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-pinniped-v1alpha1-credentialrequesttokencredential[$$CredentialRequestTokenCredential$$]__ | Token credential (when Type == TokenCredentialType). +|=== + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-pinniped-v1alpha1-credentialrequeststatus"] +==== CredentialRequestStatus + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-pinniped-v1alpha1-credentialrequest[$$CredentialRequest$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`credential`* __xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-pinniped-v1alpha1-credentialrequestcredential[$$CredentialRequestCredential$$]__ | A Credential will be returned for a successful credential request. +| *`message`* __string__ | An error message will be returned for an unsuccessful credential request. +|=== + + +[id="{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-pinniped-v1alpha1-credentialrequesttokencredential"] +==== CredentialRequestTokenCredential + + + +.Appears In: +**** +- xref:{anchor_prefix}-github-com-suzerain-io-pinniped-generated-1-19-apis-pinniped-v1alpha1-credentialrequestspec[$$CredentialRequestSpec$$] +**** + +[cols="25a,75a", options="header"] +|=== +| Field | Description +| *`value`* __string__ | Value of the bearer token supplied with the credential request. +|=== + + diff --git a/generated/1.19/apis/crdpinniped/v1alpha1/register.go b/generated/1.19/apis/crdpinniped/v1alpha1/register.go index 1a7cd407..95eae6f9 100644 --- a/generated/1.19/apis/crdpinniped/v1alpha1/register.go +++ b/generated/1.19/apis/crdpinniped/v1alpha1/register.go @@ -3,7 +3,6 @@ Copyright 2020 VMware, Inc. SPDX-License-Identifier: Apache-2.0 */ -//nolint:gochecknoglobals,gochecknoinits package v1alpha1 import ( diff --git a/generated/1.19/apis/pinniped/register.go b/generated/1.19/apis/pinniped/register.go index c6570bc7..765cfc0d 100644 --- a/generated/1.19/apis/pinniped/register.go +++ b/generated/1.19/apis/pinniped/register.go @@ -3,7 +3,6 @@ Copyright 2020 VMware, Inc. SPDX-License-Identifier: Apache-2.0 */ -//nolint:gochecknoglobals package pinniped import ( diff --git a/generated/1.19/apis/pinniped/v1alpha1/register.go b/generated/1.19/apis/pinniped/v1alpha1/register.go index b1ae3aea..c4256ec2 100644 --- a/generated/1.19/apis/pinniped/v1alpha1/register.go +++ b/generated/1.19/apis/pinniped/v1alpha1/register.go @@ -3,7 +3,6 @@ Copyright 2020 VMware, Inc. SPDX-License-Identifier: Apache-2.0 */ -//nolint:gochecknoglobals,gochecknoinits package v1alpha1 import ( diff --git a/go.sum b/go.sum index 78ebdb00..d4860b50 100644 --- a/go.sum +++ b/go.sum @@ -207,8 +207,6 @@ github.com/golang/mock v1.1.1/go.mod h1:oTYuIxOrZwtPieC+H1uAHpcLFnEyAGVDL/k47Jfb github.com/golang/mock v1.2.0/go.mod h1:oTYuIxOrZwtPieC+H1uAHpcLFnEyAGVDL/k47Jfbm0A= github.com/golang/mock v1.3.1 h1:qGJ6qTW+x6xX/my+8YUVl4WNpX9B7+/l2tRsHGZ7f2s= github.com/golang/mock v1.3.1/go.mod h1:sBzyDLLjw3U8JLTeZvSv8jJB+tU5PVekmnlKIyFUx0Y= -github.com/golang/mock v1.4.3 h1:GV+pQPG/EUUbkh47niozDcADz6go/dUwhVzdUQHIVRw= -github.com/golang/mock v1.4.3/go.mod h1:UOMv5ysSaYNkG+OFQykRIcU/QvvxJf3p21QfJ2Bt3cw= github.com/golang/mock v1.4.4 h1:l75CXGRSwbaYNpl/Z2X1XIIAMSCquvXgpVZDhwEIJsc= github.com/golang/mock v1.4.4/go.mod h1:l3mdAwkq5BuhzHwde/uurv3sEJeZMXNpwsxVWU71h+4= github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U= @@ -707,7 +705,6 @@ golang.org/x/sys v0.0.0-20200519105757-fe76b779f299/go.mod h1:h1NjWce9XRLGQEsW7w golang.org/x/sys v0.0.0-20200615200032-f1bc736245b1/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20200622214017-ed371f2e16b4 h1:5/PjkGUjvEU5Gl6BxmvKRPpqo2uNMv4rcHBMwzk/st8= golang.org/x/sys v0.0.0-20200622214017-ed371f2e16b4/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= -golang.org/x/text v0.0.0-20170915032832-14c0d48ead0c/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= golang.org/x/text v0.3.1-0.20180807135948-17ff2d5776d2/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk= @@ -886,10 +883,6 @@ mvdan.cc/lint v0.0.0-20170908181259-adc824a0674b/go.mod h1:2odslEg/xrtNQqCYg2/jC mvdan.cc/unparam v0.0.0-20190720180237-d51796306d8f h1:Cq7MalBHYACRd6EesksG1Q8EoIAKOsiZviGKbOLIej4= mvdan.cc/unparam v0.0.0-20190720180237-d51796306d8f/go.mod h1:4G1h5nDURzA3bwVMZIVpwbkw+04kSxk3rAtzlimaUJw= rsc.io/binaryregexp v0.2.0/go.mod h1:qTv7/COck+e2FymRvadv62gMdZztPaShugOCi3I+8D8= -rsc.io/quote/v3 v3.1.0 h1:9JKUTTIUgS6kzR9mK1YuGKv6Nl+DijDNIc0ghT58FaY= -rsc.io/quote/v3 v3.1.0/go.mod h1:yEA65RcK8LyAZtP9Kv3t0HmxON59tX3rD+tICJqUlj0= -rsc.io/sampler v1.3.0 h1:7uVkIFmeBqHfdjD+gZwtXXI+RODJ2Wc4O7MPEh/QiW4= -rsc.io/sampler v1.3.0/go.mod h1:T1hPZKmBbMNahiBKFy5HrXp6adAjACjK9JXDnKaTXpA= sigs.k8s.io/apiserver-network-proxy/konnectivity-client v0.0.9 h1:rusRLrDhjBp6aYtl9sGEvQJr6faoHoDLd0YcUBTZguI= sigs.k8s.io/apiserver-network-proxy/konnectivity-client v0.0.9/go.mod h1:dzAXnQbTRyDlZPJX2SUPEqvnB+j7AJjtlox7PEwigU0= sigs.k8s.io/structured-merge-diff/v4 v4.0.1 h1:YXTMot5Qz/X1iBRJhAt+vI+HVttY0WkSqqhKxQ0xVbA= diff --git a/hack/lib/docs/config.yaml b/hack/lib/docs/config.yaml new file mode 100644 index 00000000..9ecc75a2 --- /dev/null +++ b/hack/lib/docs/config.yaml @@ -0,0 +1,12 @@ +# Configuration file for https://github.com/elastic/crd-ref-docs +processor: + + # Ignore internal API versions + ignoreGroupVersions: + - "crd.pinniped.dev/crdpinniped" + - "pinniped.dev/pinniped" + ignoreFields: + - "TypeMeta$" + +render: + kubernetesVersion: KUBE_MINOR_VERSION diff --git a/hack/lib/docs/templates/gv_details.tpl b/hack/lib/docs/templates/gv_details.tpl new file mode 100644 index 00000000..e039850f --- /dev/null +++ b/hack/lib/docs/templates/gv_details.tpl @@ -0,0 +1,19 @@ +{{- define "gvDetails" -}} +{{- $gv := . -}} +[id="{{ asciidocGroupVersionID $gv | asciidocRenderAnchorID }}"] +=== {{ $gv.GroupVersionString }} + +{{ $gv.Doc }} + +{{- if $gv.Kinds }} +.Resource Types +{{- range $gv.SortedKinds }} +- {{ $gv.TypeForKind . | asciidocRenderTypeLink }} +{{- end }} +{{ end }} + +{{ range $gv.SortedTypes }} +{{ template "type" . }} +{{ end }} + +{{- end -}} diff --git a/hack/lib/docs/templates/gv_list.tpl b/hack/lib/docs/templates/gv_list.tpl new file mode 100644 index 00000000..41c5f59b --- /dev/null +++ b/hack/lib/docs/templates/gv_list.tpl @@ -0,0 +1,19 @@ +{{- define "gvList" -}} +{{- $groupVersions := . -}} + +// Generated documentation. Please do not edit. +:anchor_prefix: k8s-api + +[id="{p}-api-reference"] +== API Reference + +.Packages +{{- range $groupVersions }} +- {{ asciidocRenderGVLink . }} +{{- end }} + +{{ range $groupVersions }} +{{ template "gvDetails" . }} +{{ end }} + +{{- end -}} diff --git a/hack/lib/docs/templates/type.tpl b/hack/lib/docs/templates/type.tpl new file mode 100644 index 00000000..24592b54 --- /dev/null +++ b/hack/lib/docs/templates/type.tpl @@ -0,0 +1,35 @@ +{{- define "type" -}} +{{- $type := . -}} +{{- if asciidocShouldRenderType $type -}} + +[id="{{ asciidocTypeID $type | asciidocRenderAnchorID }}"] +==== {{ $type.Name }} {{ if $type.IsAlias }}({{ asciidocRenderTypeLink $type.UnderlyingType }}) {{ end }} + +{{ $type.Doc }} + +{{ if $type.References -}} +.Appears In: +**** +{{- range $type.SortedReferences }} +- {{ asciidocRenderTypeLink . }} +{{- end }} +**** +{{- end }} + +{{ if $type.Members -}} +[cols="25a,75a", options="header"] +|=== +| Field | Description +{{ if $type.GVK -}} +| *`apiVersion`* __string__ | `{{ $type.GVK.Group }}/{{ $type.GVK.Version }}` +| *`kind`* __string__ | `{{ $type.GVK.Kind }}` +{{ end -}} + +{{ range $type.Members -}} +| *`{{ .Name }}`* __{{ asciidocRenderType .Type }}__ | {{ template "type_members" . }} +{{ end -}} +|=== +{{ end -}} + +{{- end -}} +{{- end -}} diff --git a/hack/lib/docs/templates/type_members.tpl b/hack/lib/docs/templates/type_members.tpl new file mode 100644 index 00000000..89f6db0e --- /dev/null +++ b/hack/lib/docs/templates/type_members.tpl @@ -0,0 +1,8 @@ +{{- define "type_members" -}} +{{- $field := . -}} +{{- if eq $field.Name "metadata" -}} +Refer to Kubernetes API documentation for fields of `metadata`. +{{ else -}} +{{ $field.Doc }} +{{- end -}} +{{- end -}} diff --git a/hack/lib/update-codegen.sh b/hack/lib/update-codegen.sh index fa2f7ea3..4cde8901 100755 --- a/hack/lib/update-codegen.sh +++ b/hack/lib/update-codegen.sh @@ -66,6 +66,7 @@ echo "running in container to generate ${KUBE_VERSION} into ${OUTPUT_DIR}..." # variables in the template files and renaming them to strip the `.tmpl` extension. cp -R "${ROOT}/apis" "${OUTPUT_DIR}/apis" find "${OUTPUT_DIR}" -type f -exec sed -i "s|GENERATED_PKG|generated/${KUBE_MINOR_VERSION}|g" {} \; +find "${OUTPUT_DIR}" -type f -not -name '*.tmpl' -exec rm {} \; find "${OUTPUT_DIR}" -type f -name '*.tmpl' -exec bash -c 'mv "$0" "${0%.tmpl}"' {} \; # Make the generated API code its own Go module. @@ -142,3 +143,12 @@ echo "generating client code for our public API groups..." # Tidy up the .../client module echo "tidying ${OUTPUT_DIR}/client/go.mod..." (cd client && go mod tidy 2>&1 | sed "s|^|go-mod-tidy > |") + +# Generate API documentation +sed "s|KUBE_MINOR_VERSION|${KUBE_MINOR_VERSION}|g" < "${ROOT}/hack/lib/docs/config.yaml" > /tmp/docs-config.yaml +crd-ref-docs \ + --source-path="${ROOT}/generated/${KUBE_MINOR_VERSION}/apis" \ + --config=/tmp/docs-config.yaml \ + --renderer=asciidoctor \ + --templates-dir="${ROOT}/hack/lib/docs/templates" \ + --output-path="${ROOT}/generated/${KUBE_MINOR_VERSION}/README.adoc" \ No newline at end of file