From fedf1603726bb2f1c17c818012ca21f986a160e2 Mon Sep 17 00:00:00 2001 From: Daneyon Hansen Date: Thu, 9 Feb 2023 03:40:17 +0100 Subject: [PATCH] Adds API Docs Tooling (#980) Signed-off-by: danehans (cherry picked from commit d5a5b25933e1d486b04e307f2b4bb6239db0cd00) Signed-off-by: bitliu --- api/config/doc.go | 6 + api/config/v1alpha1/doc.go | 11 + api/config/v1alpha1/groupversion_info.go | 4 - api/doc.go | 6 + api/v1alpha1/doc.go | 10 + api/v1alpha1/groupversion_info.go | 4 - api/v1alpha1/ratelimitfilter_types.go | 7 +- docs/latest/api/config_types.md | 282 ++++++++++++++++++ docs/latest/api/extension_types.md | 240 +++++++++++++++ docs/latest/api_docs.rst | 10 + docs/latest/index.rst | 1 + ...ateway.envoyproxy.io_ratelimitfilters.yaml | 6 +- tools/crd-ref-docs/config.yaml | 12 + tools/hack/docs-headings.sh | 26 ++ tools/make/docs.mk | 25 +- tools/make/tools.mk | 1 + tools/src/crd-ref-docs/go.mod | 55 ++++ tools/src/crd-ref-docs/go.sum | 160 ++++++++++ tools/src/crd-ref-docs/pin.go | 12 + 19 files changed, 860 insertions(+), 18 deletions(-) create mode 100644 api/config/doc.go create mode 100644 api/config/v1alpha1/doc.go create mode 100644 api/doc.go create mode 100644 api/v1alpha1/doc.go create mode 100644 docs/latest/api/config_types.md create mode 100644 docs/latest/api/extension_types.md create mode 100644 docs/latest/api_docs.rst create mode 100644 tools/crd-ref-docs/config.yaml create mode 100755 tools/hack/docs-headings.sh create mode 100644 tools/src/crd-ref-docs/go.mod create mode 100644 tools/src/crd-ref-docs/go.sum create mode 100644 tools/src/crd-ref-docs/pin.go diff --git a/api/config/doc.go b/api/config/doc.go new file mode 100644 index 00000000000..a9b235ea604 --- /dev/null +++ b/api/config/doc.go @@ -0,0 +1,6 @@ +// Copyright Envoy Gateway Authors +// SPDX-License-Identifier: Apache-2.0 +// The full text of the Apache license is available in the LICENSE file at +// the root of the repo. + +package config diff --git a/api/config/v1alpha1/doc.go b/api/config/v1alpha1/doc.go new file mode 100644 index 00000000000..689a481106d --- /dev/null +++ b/api/config/v1alpha1/doc.go @@ -0,0 +1,11 @@ +// Copyright Envoy Gateway Authors +// SPDX-License-Identifier: Apache-2.0 +// The full text of the Apache license is available in the LICENSE file at +// the root of the repo. + +// Package v1alpha1 contains API Schema definitions for the config.gateway.envoyproxy.io +// API group. +// +// +kubebuilder:object:generate=true +// +groupName=config.gateway.envoyproxy.io +package v1alpha1 diff --git a/api/config/v1alpha1/groupversion_info.go b/api/config/v1alpha1/groupversion_info.go index a2bac6e4026..b8d005fb16e 100644 --- a/api/config/v1alpha1/groupversion_info.go +++ b/api/config/v1alpha1/groupversion_info.go @@ -3,10 +3,6 @@ // The full text of the Apache license is available in the LICENSE file at // the root of the repo. -// Package v1alpha1 contains API Schema definitions for the config v1alpha1 API group. -// -// +kubebuilder:object:generate=true -// +groupName=config.gateway.envoyproxy.io package v1alpha1 import ( diff --git a/api/doc.go b/api/doc.go new file mode 100644 index 00000000000..912e4dd16e6 --- /dev/null +++ b/api/doc.go @@ -0,0 +1,6 @@ +// Copyright Envoy Gateway Authors +// SPDX-License-Identifier: Apache-2.0 +// The full text of the Apache license is available in the LICENSE file at +// the root of the repo. + +package api diff --git a/api/v1alpha1/doc.go b/api/v1alpha1/doc.go new file mode 100644 index 00000000000..593b004a232 --- /dev/null +++ b/api/v1alpha1/doc.go @@ -0,0 +1,10 @@ +// Copyright Envoy Gateway Authors +// SPDX-License-Identifier: Apache-2.0 +// The full text of the Apache license is available in the LICENSE file at +// the root of the repo. + +// Package v1alpha1 contains API Schema definitions for the gateway.envoyproxy.io API group. +// +// +kubebuilder:object:generate=true +// +groupName=gateway.envoyproxy.io +package v1alpha1 diff --git a/api/v1alpha1/groupversion_info.go b/api/v1alpha1/groupversion_info.go index 648ba679293..1b13b602e87 100644 --- a/api/v1alpha1/groupversion_info.go +++ b/api/v1alpha1/groupversion_info.go @@ -3,10 +3,6 @@ // The full text of the Apache license is available in the LICENSE file at // the root of the repo. -// Package v1alpha1 contains API Schema definitions for the gateway.envoyproxy.io API group. -// -// +kubebuilder:object:generate=true -// +groupName=gateway.envoyproxy.io package v1alpha1 import ( diff --git a/api/v1alpha1/ratelimitfilter_types.go b/api/v1alpha1/ratelimitfilter_types.go index 1365628e278..fa08d6de97c 100644 --- a/api/v1alpha1/ratelimitfilter_types.go +++ b/api/v1alpha1/ratelimitfilter_types.go @@ -148,12 +148,7 @@ type RateLimitValue struct { } // RateLimitUnit specifies the intervals for setting rate limits. -// Valid RateLimitUnit values are: -// -// * "Second" -// * "Minute" -// * "Hour" -// * "Day" +// Valid RateLimitUnit values are "Second", "Minute", "Hour", and "Day". // // +kubebuilder:validation:Enum=Second;Minute;Hour;Day type RateLimitUnit string diff --git a/docs/latest/api/config_types.md b/docs/latest/api/config_types.md new file mode 100644 index 00000000000..233a0df20d8 --- /dev/null +++ b/docs/latest/api/config_types.md @@ -0,0 +1,282 @@ +# API Reference + +## Packages +- [config.gateway.envoyproxy.io/v1alpha1](#configgatewayenvoyproxyiov1alpha1) + + +## config.gateway.envoyproxy.io/v1alpha1 + +Package v1alpha1 contains API Schema definitions for the config.gateway.envoyproxy.io +API group. + + +### Resource Types +- [EnvoyGateway](#envoygateway) +- [EnvoyProxy](#envoyproxy) + + + +## EnvoyGateway + + + +EnvoyGateway is the Schema for the envoygateways API. + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `config.gateway.envoyproxy.io/v1alpha1` +| `kind` _string_ | `EnvoyGateway` +| `EnvoyGatewaySpec` _[EnvoyGatewaySpec](#envoygatewayspec)_ | EnvoyGatewaySpec defines the desired state of Envoy Gateway. | + + +## EnvoyGatewaySpec + + + +EnvoyGatewaySpec defines the desired state of Envoy Gateway. + +_Appears in:_ +- [EnvoyGateway](#envoygateway) + +| Field | Description | +| --- | --- | +| `gateway` _[Gateway](#gateway)_ | Gateway defines desired Gateway API specific configuration. If unset, default configuration parameters will apply. | +| `provider` _[Provider](#provider)_ | Provider defines the desired provider and provider-specific configuration. If unspecified, the Kubernetes provider is used with default configuration parameters. | +| `rateLimit` _[RateLimit](#ratelimit)_ | RateLimit defines the configuration associated with the Rate Limit service deployed by Envoy Gateway required to implement the Global Rate limiting functionality. The specific rate limit service used here is the reference implementation in Envoy. For more details visit https://github.com/envoyproxy/ratelimit. This configuration will not be needed to enable Local Rate limiitng. | + + +## EnvoyProxy + + + +EnvoyProxy is the Schema for the envoyproxies API + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `config.gateway.envoyproxy.io/v1alpha1` +| `kind` _string_ | `EnvoyProxy` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[EnvoyProxySpec](#envoyproxyspec)_ | | + + +## EnvoyProxySpec + + + +EnvoyProxySpec defines the desired state of EnvoyProxy. + +_Appears in:_ +- [EnvoyProxy](#envoyproxy) + +| Field | Description | +| --- | --- | +| `provider` _[ResourceProvider](#resourceprovider)_ | Provider defines the desired resource provider and provider-specific configuration. If unspecified, the "Kubernetes" resource provider is used with default configuration parameters. | +| `logging` _[ProxyLogging](#proxylogging)_ | Logging defines logging parameters for managed proxies. If unspecified, default settings apply. | + + + + +## FileProvider + + + +FileProvider defines configuration for the File provider. + +_Appears in:_ +- [Provider](#provider) + + + +## Gateway + + + +Gateway defines the desired Gateway API configuration of Envoy Gateway. + +_Appears in:_ +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Description | +| --- | --- | +| `controllerName` _string_ | ControllerName defines the name of the Gateway API controller. If unspecified, defaults to "gateway.envoyproxy.io/gatewayclass-controller". See the following for additional details: + https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.GatewayClass | + + +## KubernetesDeploymentSpec + + + +KubernetesDeploymentSpec defines the desired state of the Kubernetes deployment resource. + +_Appears in:_ +- [KubernetesResourceProvider](#kubernetesresourceprovider) + +| Field | Description | +| --- | --- | +| `replicas` _integer_ | Replicas is the number of desired pods. Defaults to 1. | + + +## KubernetesProvider + + + +KubernetesProvider defines configuration for the Kubernetes provider. + +_Appears in:_ +- [Provider](#provider) + + + +## KubernetesResourceProvider + + + +KubernetesResourceProvider defines configuration for the Kubernetes resource provider. + +_Appears in:_ +- [ResourceProvider](#resourceprovider) + +| Field | Description | +| --- | --- | +| `envoyDeployment` _[KubernetesDeploymentSpec](#kubernetesdeploymentspec)_ | EnvoyDeployment defines the desired state of the Envoy deployment resource. If unspecified, default settings for the manged Envoy deployment resource are applied. | + + +## LogComponent + +_Underlying type:_ `string` + +LogComponent defines a component that supports a configured logging level. + +_Appears in:_ +- [ProxyLogging](#proxylogging) + + + +## LogLevel + +_Underlying type:_ `string` + +LogLevel defines a log level for system logs. + +_Appears in:_ +- [ProxyLogging](#proxylogging) + + + +## Provider + + + +Provider defines the desired configuration of a provider. + +_Appears in:_ +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Description | +| --- | --- | +| `type` _[ProviderType](#providertype)_ | Type is the type of provider to use. Supported types are: + * Kubernetes: A provider that provides runtime configuration via the Kubernetes API. | +| `kubernetes` _[KubernetesProvider](#kubernetesprovider)_ | Kubernetes defines the configuration of the Kubernetes provider. Kubernetes provides runtime configuration via the Kubernetes API. | +| `file` _[FileProvider](#fileprovider)_ | File defines the configuration of the File provider. File provides runtime configuration defined by one or more files. | + + +## ProviderType + +_Underlying type:_ `string` + +ProviderType defines the types of providers supported by Envoy Gateway. + +_Appears in:_ +- [Provider](#provider) +- [ResourceProvider](#resourceprovider) + + + +## ProxyLogging + + + +ProxyLogging defines logging parameters for managed proxies. + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Field | Description | +| --- | --- | +| `level` _object (keys:[LogComponent](#logcomponent), values:[LogLevel](#loglevel))_ | Level is a map of logging level per component, where the component is the key and the log level is the value. If unspecified, defaults to "System: Info". | + + +## RateLimit + + + +RateLimit defines the configuration associated with the Rate Limit Service used for Global Rate Limiting. + +_Appears in:_ +- [EnvoyGatewaySpec](#envoygatewayspec) + +| Field | Description | +| --- | --- | +| `backend` _[RateLimitDatabaseBackend](#ratelimitdatabasebackend)_ | Backend holds the configuration associated with the database backend used by the rate limit service to store state associated with global ratelimiting. | + + +## RateLimitDatabaseBackend + + + +RateLimitDatabaseBackend defines the configuration associated with the database backend used by the rate limit service. + +_Appears in:_ +- [RateLimit](#ratelimit) + +| Field | Description | +| --- | --- | +| `type` _[RateLimitDatabaseBackendType](#ratelimitdatabasebackendtype)_ | Type is the type of database backend to use. Supported types are: * Redis: Connects to a Redis database. | +| `redis` _[RateLimitRedisSettings](#ratelimitredissettings)_ | Redis defines the settings needed to connect to a Redis database. | + + +## RateLimitDatabaseBackendType + +_Underlying type:_ `string` + +RateLimitDatabaseBackendType specifies the types of database backend to be used by the rate limit service. + +_Appears in:_ +- [RateLimitDatabaseBackend](#ratelimitdatabasebackend) + + + +## RateLimitRedisSettings + + + +RateLimitRedisSettings defines the configuration for connecting to a Redis database. + +_Appears in:_ +- [RateLimitDatabaseBackend](#ratelimitdatabasebackend) + +| Field | Description | +| --- | --- | +| `url` _string_ | URL of the Redis Database. | + + +## ResourceProvider + + + +ResourceProvider defines the desired state of a resource provider. + +_Appears in:_ +- [EnvoyProxySpec](#envoyproxyspec) + +| Field | Description | +| --- | --- | +| `type` _[ProviderType](#providertype)_ | Type is the type of resource provider to use. A resource provider provides infrastructure resources for running the data plane, e.g. Envoy proxy, and optional auxiliary control planes. Supported types are: + * Kubernetes: Provides infrastructure resources for running the data plane, e.g. Envoy proxy. | +| `kubernetes` _[KubernetesResourceProvider](#kubernetesresourceprovider)_ | Kubernetes defines the desired state of the Kubernetes resource provider. Kubernetes provides infrastructure resources for running the data plane, e.g. Envoy proxy. If unspecified and type is "Kubernetes", default settings for managed Kubernetes resources are applied. | + + diff --git a/docs/latest/api/extension_types.md b/docs/latest/api/extension_types.md new file mode 100644 index 00000000000..c398dccb96a --- /dev/null +++ b/docs/latest/api/extension_types.md @@ -0,0 +1,240 @@ +# API Reference + +## Packages +- [gateway.envoyproxy.io/v1alpha1](#gatewayenvoyproxyiov1alpha1) + + +## gateway.envoyproxy.io/v1alpha1 + +Package v1alpha1 contains API Schema definitions for the gateway.envoyproxy.io API group. + + +### Resource Types +- [AuthenticationFilter](#authenticationfilter) +- [RateLimitFilter](#ratelimitfilter) + + + +## AuthenticationFilter + + + + + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `gateway.envoyproxy.io/v1alpha1` +| `kind` _string_ | `AuthenticationFilter` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[AuthenticationFilterSpec](#authenticationfilterspec)_ | Spec defines the desired state of the AuthenticationFilter type. | + + +## AuthenticationFilterSpec + + + +AuthenticationFilterSpec defines the desired state of the AuthenticationFilter type. + +_Appears in:_ +- [AuthenticationFilter](#authenticationfilter) + +| Field | Description | +| --- | --- | +| `type` _[AuthenticationFilterType](#authenticationfiltertype)_ | Type defines the type of authentication provider to use. Supported provider types are: + * JWT: A provider that uses JSON Web Token (JWT) for authenticating requests. | +| `jwtProviders` _[JwtAuthenticationFilterProvider](#jwtauthenticationfilterprovider) array_ | JWT defines the JSON Web Token (JWT) authentication provider type. When multiple jwtProviders are specified, the JWT is considered valid if any of the providers successfully validate the JWT. For additional details, see: + https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter.html | + + +## AuthenticationFilterType + +_Underlying type:_ `string` + +AuthenticationFilterType is a type of authentication provider. + +_Appears in:_ +- [AuthenticationFilterSpec](#authenticationfilterspec) + + + +## GlobalRateLimit + + + +GlobalRateLimit defines the global rate limit configuration. + +_Appears in:_ +- [RateLimitFilterSpec](#ratelimitfilterspec) + +| Field | Description | +| --- | --- | +| `rules` _[RateLimitRule](#ratelimitrule) array_ | Rules are a list of RateLimit selectors and limits. Each rule and its associated limit is applied in a mutually exclusive way i.e. if multiple rules get selected, each of their associated limits get applied, so a single traffic request might increase the rate limit counters for multiple rules if selected. | + + +## HeaderMatch + + + +HeaderMatch defines the match attributes within the HTTP Headers of the request. + +_Appears in:_ +- [RateLimitSelectCondition](#ratelimitselectcondition) + +| Field | Description | +| --- | --- | +| `type` _[HeaderMatchType](#headermatchtype)_ | Type specifies how to match against the value of the header. | +| `name` _string_ | Name of the HTTP header. | +| `value` _string_ | Value within the HTTP header. Due to the case-insensitivity of header names, "foo" and "Foo" are considered equivalent. Do not set this field when Type="Distinct", implying matching on any/all unique values within the header. | + + +## HeaderMatchType + +_Underlying type:_ `string` + +HeaderMatchType specifies the semantics of how HTTP header values should be compared. Valid HeaderMatchType values are: + - "Exact": Use this type to match the exact value of the Value field against the value of the specified HTTP Header. - "RegularExpression": Use this type to match a regular expression against the value of the specified HTTP Header. The regex string must adhere to the syntax documented in https://github.com/google/re2/wiki/Syntax. - "Distinct": Use this type to match any and all possible unique values encountered in the specified HTTP Header. Note that each unique value will receive its own rate limit bucket. + +_Appears in:_ +- [HeaderMatch](#headermatch) + + + +## JwtAuthenticationFilterProvider + + + +JwtAuthenticationFilterProvider defines the JSON Web Token (JWT) authentication provider type and how JWTs should be verified: + +_Appears in:_ +- [AuthenticationFilterSpec](#authenticationfilterspec) + +| Field | Description | +| --- | --- | +| `name` _string_ | Name defines a unique name for the JWT provider. A name can have a variety of forms, including RFC1123 subdomains, RFC 1123 labels, or RFC 1035 labels. | +| `issuer` _string_ | Issuer is the principal that issued the JWT and takes the form of a URL or email address. For additional details, see: + URL format: https://tools.ietf.org/html/rfc7519#section-4.1.1 Email format: https://rfc-editor.org/rfc/rfc5322.html + URL Example: issuer: https://auth.example.com + Email Example: issuer: jdoe@example.com + If not provided, the JWT issuer is not checked. | +| `audiences` _string array_ | Audiences is a list of JWT audiences allowed to access. For additional details, see: + https://tools.ietf.org/html/rfc7519#section-4.1.3 + Example: audiences: - foo.apps.example.com bar.apps.example.com + If not provided, JWT audiences are not checked. | +| `remoteJWKS` _[RemoteJWKS](#remotejwks)_ | RemoteJWKS defines how to fetch and cache JSON Web Key Sets (JWKS) from a remote HTTP/HTTPS endpoint. | + + +## RateLimitFilter + + + +RateLimitFilter allows the user to limit the number of incoming requests to a predefined value based on attributes within the traffic flow. + + + +| Field | Description | +| --- | --- | +| `apiVersion` _string_ | `gateway.envoyproxy.io/v1alpha1` +| `kind` _string_ | `RateLimitFilter` +| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | +| `spec` _[RateLimitFilterSpec](#ratelimitfilterspec)_ | Spec defines the desired state of RateLimitFilter. | + + +## RateLimitFilterSpec + + + +RateLimitFilterSpec defines the desired state of RateLimitFilter. + +_Appears in:_ +- [RateLimitFilter](#ratelimitfilter) + +| Field | Description | +| --- | --- | +| `type` _[RateLimitType](#ratelimittype)_ | Type decides the scope for the RateLimits. Valid RateLimitType values are: + * "Global" - In this mode, the rate limits are applied across all Envoy proxy instances. | +| `global` _[GlobalRateLimit](#globalratelimit)_ | Global rate limit configuration. | + + +## RateLimitRule + + + +RateLimitRule defines the semantics for matching attributes from the incoming requests, and setting limits for them. + +_Appears in:_ +- [GlobalRateLimit](#globalratelimit) + +| Field | Description | +| --- | --- | +| `clientSelectors` _[RateLimitSelectCondition](#ratelimitselectcondition) array_ | ClientSelectors holds the list of select conditions to select specific clients using attributes from the traffic flow. All individual select conditions must hold True for this rule and its limit to be applied. If this field is empty, it is equivalent to True, and the limit is applied. | +| `limit` _[RateLimitValue](#ratelimitvalue)_ | Limit holds the rate limit values. This limit is applied for traffic flows when the selectors compute to True, causing the request to be counted towards the limit. The limit is enforced and the request is ratelimited, i.e. a response with 429 HTTP status code is sent back to the client when the selected requests have reached the limit. | + + +## RateLimitSelectCondition + + + +RateLimitSelectCondition specifies the attributes within the traffic flow that can be used to select a subset of clients to be ratelimited. All the individual conditions must hold True for the overall condition to hold True. + +_Appears in:_ +- [RateLimitRule](#ratelimitrule) + +| Field | Description | +| --- | --- | +| `headers` _[HeaderMatch](#headermatch) array_ | Headers is a list of request headers to match. Multiple header values are ANDed together, meaning, a request MUST match all the specified headers. | + + +## RateLimitType + +_Underlying type:_ `string` + +RateLimitType specifies the types of RateLimiting. + +_Appears in:_ +- [RateLimitFilterSpec](#ratelimitfilterspec) + + + +## RateLimitUnit + +_Underlying type:_ `string` + +RateLimitUnit specifies the intervals for setting rate limits. Valid RateLimitUnit values are "Second", "Minute", "Hour", and "Day". + +_Appears in:_ +- [RateLimitValue](#ratelimitvalue) + + + +## RateLimitValue + + + +RateLimitValue defines the limits for rate limiting. + +_Appears in:_ +- [RateLimitRule](#ratelimitrule) + +| Field | Description | +| --- | --- | +| `requests` _integer_ | | +| `unit` _[RateLimitUnit](#ratelimitunit)_ | | + + +## RemoteJWKS + + + +RemoteJWKS defines how to fetch and cache JSON Web Key Sets (JWKS) from a remote HTTP/HTTPS endpoint. + +_Appears in:_ +- [JwtAuthenticationFilterProvider](#jwtauthenticationfilterprovider) + +| Field | Description | +| --- | --- | +| `uri` _string_ | URI is the HTTPS URI to fetch the JWKS. Envoy's system trust bundle is used to validate the server certificate. + Example: uri: https://www.foo.com/oauth2/v1/certs | + + diff --git a/docs/latest/api_docs.rst b/docs/latest/api_docs.rst new file mode 100644 index 00000000000..b470527c50c --- /dev/null +++ b/docs/latest/api_docs.rst @@ -0,0 +1,10 @@ +API Docs +============== + +API reference documentation for Envoy Gateway. + +.. toctree:: + :maxdepth: 1 + + Config APIs + Extension APIs diff --git a/docs/latest/index.rst b/docs/latest/index.rst index 7da20035f47..b31be95cc01 100644 --- a/docs/latest/index.rst +++ b/docs/latest/index.rst @@ -18,6 +18,7 @@ you are interested in using or contributing to Envoy Gateway, the following reso user_docs design_docs dev_docs + api_docs releases roadmap about_docs diff --git a/internal/provider/kubernetes/config/crd/bases/gateway.envoyproxy.io_ratelimitfilters.yaml b/internal/provider/kubernetes/config/crd/bases/gateway.envoyproxy.io_ratelimitfilters.yaml index 8aa43e98a1e..96bb3dddf7b 100644 --- a/internal/provider/kubernetes/config/crd/bases/gateway.envoyproxy.io_ratelimitfilters.yaml +++ b/internal/provider/kubernetes/config/crd/bases/gateway.envoyproxy.io_ratelimitfilters.yaml @@ -118,9 +118,9 @@ spec: requests: type: integer unit: - description: "RateLimitUnit specifies the intervals - for setting rate limits. Valid RateLimitUnit values - are: \n * \"Second\" * \"Minute\" * \"Hour\" * \"Day\"" + description: RateLimitUnit specifies the intervals for + setting rate limits. Valid RateLimitUnit values are + "Second", "Minute", "Hour", and "Day". enum: - Second - Minute diff --git a/tools/crd-ref-docs/config.yaml b/tools/crd-ref-docs/config.yaml new file mode 100644 index 00000000000..ed1661d5e7f --- /dev/null +++ b/tools/crd-ref-docs/config.yaml @@ -0,0 +1,12 @@ +processor: + # RE2 regular expressions describing types that should be excluded from the generated documentation. + ignoreTypes: + - "(EnvoyProxy|AuthenticationFilter|RateLimitFilter)List$" + # RE2 regular expressions describing type fields that should be excluded from the generated documentation. + ignoreFields: + - "status$" + - "TypeMeta$" + +render: + # Version of Kubernetes to use when generating links to Kubernetes API documentation. + kubernetesVersion: 1.26 diff --git a/tools/hack/docs-headings.sh b/tools/hack/docs-headings.sh new file mode 100755 index 00000000000..7311c46092e --- /dev/null +++ b/tools/hack/docs-headings.sh @@ -0,0 +1,26 @@ +#!/usr/bin/env bash + +set -o errexit +set -o nounset +set -o pipefail + +# Wrap sed to deal with GNU and BSD sed flags. +run::sed() { + if sed --version &1 | grep -q GNU; then + # GNU sed + sed -i "$@" + else + # assume BSD sed + sed -i '' "$@" + fi +} + +files=(docs/latest/api/config_types.md docs/latest/api/extension_types.md) + +# Required since Sphinx mst does not link to h4 headings. +for file in "${files[@]}" ; do + run::sed \ + "-es|####|##|" \ + "$file" + echo "updated markdown headings for $file" +done diff --git a/tools/make/docs.mk b/tools/make/docs.mk index 042182336cb..a065a3493fa 100644 --- a/tools/make/docs.mk +++ b/tools/make/docs.mk @@ -4,7 +4,7 @@ RELEASE_VERSIONS ?= $(foreach v,$(wildcard ${ROOT_DIR}/docs/*),$(notdir ${v})) ##@ Docs .PHONY: docs -docs: docs.clean $(tools/sphinx-build) ## Generate Envoy Gateway Docs Sources +docs: docs.clean $(tools/sphinx-build) docs-api ## Generate Envoy Gateway Docs Sources @$(LOG_TARGET) mkdir -p $(DOCS_OUTPUT_DIR) cp docs/index.html $(DOCS_OUTPUT_DIR)/index.html @@ -32,6 +32,29 @@ docs.clean: @$(LOG_TARGET) rm -rf $(DOCS_OUTPUT_DIR) +.PHONY: docs-api +docs-api: docs-api-gen docs-api-headings + +.PHONY: docs-api-gen +docs-api-gen: $(tools/crd-ref-docs) + $(tools/crd-ref-docs) \ + --source-path=api/config \ + --config=tools/crd-ref-docs/config.yaml \ + --output-path=docs/latest/api/config_types.md \ + --max-depth 10 \ + --renderer=markdown + $(tools/crd-ref-docs) \ + --source-path=api/v1alpha1 \ + --config=tools/crd-ref-docs/config.yaml \ + --output-path=docs/latest/api/extension_types.md \ + --max-depth 10 \ + --renderer=markdown + +.PHONY: docs-api-headings # Required since sphinx mst does not link to h4 headings. +docs-api-headings: + @$(LOG_TARGET) + tools/hack/docs-headings.sh + .PHONY: docs-release-prepare docs-release-prepare: @$(LOG_TARGET) diff --git a/tools/make/tools.mk b/tools/make/tools.mk index d945caf79e8..8eb31e2443f 100644 --- a/tools/make/tools.mk +++ b/tools/make/tools.mk @@ -17,6 +17,7 @@ tools/golangci-lint = $(tools.bindir)/golangci-lint tools/kustomize = $(tools.bindir)/kustomize tools/kind = $(tools.bindir)/kind tools/setup-envtest = $(tools.bindir)/setup-envtest +tools/crd-ref-docs = $(tools.bindir)/crd-ref-docs $(tools.bindir)/%: $(tools.srcdir)/%/pin.go $(tools.srcdir)/%/go.mod cd $(