docs: doc generation

[lgadban]

• general docs generation requirements?
• license summary
• followup to cleanup doc-related content from this PR Remove docs directory #10346

[artberger]

Reference docs that are currently generated from docs or were in Edge.

Published doc	Code generation	Description
Current API docs	tbd	divided into top-level and components, but how many of these would still be relevant to and generated from kgateway? Right now, this is created manually because we could not generate all the subcomponents into the top-level API doc format. There is a solo-projects followup issue. Create a detailed list of requirements for the API docs gen, see comment in this issue.
CLI docs	generate CLI in gloo	assume we will not have a kgateway CLI? and these docs will be removed to the GG docs. These were also manually copied.
Helm ref docs	helm gen in gloo	still need
OSA	tbd	still need
security posture	not sure?	not sure?
security vulnerabilities (Edge)	security scan utils in docs dir	still need, but still working through what this should look like. We might not need Trivy. The code would need to be updated.
changelog (Edge)	Pull releases here, changelog bot repo here	Changelog is being discussed and re-evaluated. #10381

After we figure out the code generation in the code repo, then we need to get it into the docs repo.

• We could do something like a GH Action.
• See related Slack with Tim and Nathan

[lgadban]

technical notes

helm generation

https://github.com/solo-io/gloo/blob/376ba9016cbb6a344667c6403040e4ebf3f92fd2/install/helm/gloo/generate.go#L91-L101

[artberger]

@lgadban @Nadine2016 following up on our kgateway API doc gen conversation, here is some more detail for the API doc design.

Kgateway API docs

Proposal for generating the Kgateway API docs from code.

Previous process in Edge API docs

Published page: https://docs.solo.io/gloo-edge/latest/reference/api/

Source markdown files: https://github.com/solo-io/gloo/tree/main/docs/content/reference/api

Source proto files where the docs live as comments with the code: https://github.com/solo-io/gloo/tree/main/projects/gloo/api

Process to generate markdown content from source files:

• Readme overview, generate.go file, and markdown template: https://github.com/solo-io/gloo/tree/main/docs/content/crds
• Locally make the API docs: make install-go-tools``, then make generate-crd-reference-docs`
• Generated during CI as part of the make generated-code command

Issues with previous process

Each component is generated as a separate markdown page. Users cannot find a single page for the CRs that they actually create, just these components.

For example, there is an Address component, but it is difficult to tell what CR you actually create that uses this component.

It also leads to cases such as with the Ratelimit component where separate pages are created for the different packages, even though they have the same name and so adds to the confusion.

Proposal

Generate a single page for the top-level CRs that users can create, such as GatewayParameters. Currently, this is done manually in the Kgateway API docs, in a section called Top-level APIs: https://kgateway.dev/docs/reference/api/top-level/

Markdown example of what the page might look like:

# CR name

Short description of the custom resource.

* Package: `gateway.kgateway.dev` or similar
* Source file: hyperlink to the file on GitHub, such as `github.com/kgateway-dev/kgateway/projects/gateway/api/v1/http_listener_options.proto`

Components:

* [$COMPONENT_NAME](#component-$NAME)
* [$COMPONENT_NAME](#component-$NAME)

## Example YAML file

An example YAML file, potentially generated from the code or manually created. This example provides a starting point for users to copy, and includes the proper indentation for each subcomponent of the CR.

   apiVersion: gloo.solo.io/v1
   kind: Upstream
   metadata:
     name: example-upstream
     namespace: default
   spec:
     kube:
       serviceName: httpbin
       serviceNamespace: httpbin
       servicePort: 8000

## Component name, such as Upstream {#component-$NAME}

Short description of the component. 

Example: Upstreams represent destination for routing HTTP requests. Upstreams can be compared to clusters in Envoy terminology. Each upstream in kgateway has a type. Supported types include static, kubernetes, aws, consul, and more. Each upstream type is handled by a corresponding plugin. (plugins currently need to be compiled into Gloo)

Table with the description of each field, such as:

| Field | Description |
| ----- | ----------- |
| [`sslConfig`]($LINK, if any), _$TYPE_ (string, int, bool, etc., if any) | Configure the SSL settings to original TLS to an upstream. |
| [`healthChecks`]($LINK, if any), _$TYPE_ (string, int, bool, etc., if any) | Configure the health checks for the upstream. |

[Back to top](/)
<!-- Backlinks for components go back to top of page-->

### Subcomponent name, such as SslConfig

Same description as from the parent component.

Table with the description of each subcomponent field, such as:

| Field | Type | Description |
| ----- | ---- | ----------- |
| [`secretRef`]($LINK, if any), _$TYPE_ (string, int, bool, etc., if any) | SecretRef contains the secret ref to a kgatewaytls secret or a kubernetes tls secret. kgatewaytls secret can contain a root ca as well if verification is needed. Only one of secretRef, sslFiles, or sds can be set. |
| [`sslFiles`]($LINK, if any), _$TYPE_ (string, int, bool, etc., if any) | SSLFiles reference paths to certificates which are local to the proxy. Only one of sslFiles, secretRef, or sds can be set. |

[Back to $COMPONENT_NAME](#component-$NAME)
<!-- Backlinks for subcomponents go back to component-->

## Component name such as ClusterProtocolSelection

Short description of the component. 

Table with the description of each field, such as:

| Field | Description |
| ----- | ----------- |
| [`USE_CONFIGURED_PROTOCOL`]($LINK, if any), _$TYPE_ (string, int, bool, etc., if any) |Cluster can only operate on one of the possible upstream protocols (HTTP1.1, HTTP2). If http2_protocol_options are present, HTTP2 will be used, otherwise HTTP1.1 will be used. |
| [`USE_DOWNSTREAM_PROTOCOL`]($LINK, if any), _$TYPE_ (string, int, bool, etc., if any) | Use HTTP1.1 or HTTP2, depending on which one is used on the downstream connection. |

[Back to top](/)
<!-- Backlinks for components go back to top of page-->

[artberger]

@lgadban @Nadine2016 following up on our kgateway Helm doc gen conversation, here is some more detail for the Helm doc design.

Kgateway Helm docs

Proposal for generating the Kgateway Helm docs from code.

Previous process in Edge Helm docs

Published page: https://docs.solo.io/gloo-edge/latest/reference/helm_chart_values/open_source_helm_chart_values/

Source files:

• Markdown: https://github.com/solo-io/gloo/blob/main/docs/content/reference/helm_chart_values/enterprise_helm_chart_values.md
• Docs as comments in source file values.go: https://github.com/solo-io/gloo/blob/main/install/helm/gloo/generate/values.go
• Possible fields determined by values-template.yaml: https://github.com/solo-io/gloo/blob/main/install/helm/gloo/values-template.yaml

Process to generate markdown content from source files:

• generate.go file, starting around generateValueDocs here: https://github.com/solo-io/gloo/blob/main/install/helm/gloo/generate.go#L91
• Formatting of the content into markdown done by this docs.go in the k8s-utils repo: https://github.com/solo-io/k8s-utils/blob/main/installutils/helmchart/docs.go
• Locally make the Helm docs: make install-go-tools, then make generate-helm-files
• Generated during CI as part of the make generated-code command

Issues with previous process

All of the Helm values are part of a single table. The table has many rows, leading to "endless scrolling" for users.

The Option names include all of the components, so those become quite long. Depending on the browser, such column widths force users to scroll sideways.

Example: kubeGateway.gatewayParameters.glooGateway.envoyContainer.image.repository

Proposal

Generate H2s for each top-level component of the Helm chart. The field names should wrap so as not to force the column width to be excessive.

The default values can be included in the description column, to reduce the column width further.

Markdown example of what the page might look like:

# Helm chart values

Short description of the Helm chart.

Resources:

* [Installation guide]($LINK)
* [Helm template]($LINK)

Components:

* [$COMPONENT_NAME](#component-$NAME)
* [$COMPONENT_NAME](#component-$NAME)

## Component name, such as kubeGateway {#component-$NAME}

Short description of the component. 

Example: Use the Kubernetes Gateway API controller.

Table with the description of each subcomponent field. Includes the table shortcode that we use in the Hugo theme for formatting long tables.

{{< table >}}
| Field | Type | Description |
| ----- | ---- | ----------- |
| gatewayParameters | _$TYPE_ (string, int, bool, etc., if any) | Configure the gateway parameters to use with the Kubernetes Gateway API controller. The default value is $DEFAULT_VALUE. |
| portal | _$TYPE_ (string, int, bool, etc., if any) | Enable the developer portal controller and web server. The default value is $DEFAULT_VALUE. |
{{< /table >}}
[Back to top](/)
<!-- Backlinks for components go back to top of page-->