docs: Transition to crd-ref-docs

[gcs278]

What type of PR is this?
/kind documentation

What this PR does / why we need it:
Update to use crd-ref-docs which is actively maintained and includes improvements over gen-crd-api-reference-docs.

Which issue(s) this PR fixes:
#3016

Does this PR introduce a user-facing change?:

NONE

WIP: Still ironing out the details to keep get the https://gateway-api.sigs.k8s.io/reference/spec page looking similar to what we have now.

[k8s-ci-robot]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: gcs278
Once this PR has been reviewed and has the lgtm label, please assign youngnick for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[gcs278]

Update: Unfortunately it's not a just-plug-it-in thing. I have a couple of things to figure out:

1. Sorting of Packages / API Versions (i.e. what docs: display beta before alpha in API spec #1345 tried to solve, may not be easily solvable/maintainable)
2. Sorting of types within a package. The current implementation puts "Kinds" (GRPCRoute, Gateway...) before individual types. It makes sense to do that. Not totally sure how that happens, but it's clear crd-ref-docs sorts alphabetically. For example, for v1 currently GRPCRoute comes first, followed by Gateway, but in our this PR it starts with AddressType
3. Since it's running through mkdocs we get a Table of Contents. That's good I suppose?
4. Inline tables: For example, GRPCRoute's spec is an inline table, but this PR doesn't create that inline table. I think there is a way to do this, just need to do some research.
5. Formatting. Headers are different sizes, tables have different columns, and information is display in a different formats.

Side note: The type in current docs GRPCRouteFilter is displaying gateway:experimental:validation:Enum=ResponseHeaderModifier;RequestHeaderModifier;RequestMirror;ExtensionRef in the description field.

I'll need to get back to some of my regular scheduled programming, but I'm going leave this here for when I get some free time to fiddle with this implementation. I won't offended if someone finds this PR and wants to pick it up from here.

[robscott]

Thanks for the work on this @gcs278! Unfortunate that it's not just a drop-in replacement, but hopefully it's possible to get past some of these limitations at some point. It's interesting to see the way Elastic uses this package with different pages for each API group. I'm not sure if that would help us out here, but it might make things a bit easier to understand. Ideally there would be an easy way to exclude types from pages and/or highlight only root objects.

I think Envoy Gateway also uses this for their reference docs, maybe @arkodg or someone else working on that project would have some tips here?

[gcs278]

It's interesting to see the way Elastic uses this package with different pages for each API group. I'm not sure if that would help us out here, but it might make things a bit easier to understand.

I like that formatting. It feels more organized to not have every API version on a single page (I use ctrl-f a lot and that can be confusing looking for a specific field).

[arkodg]

ccing @zirain here who may have asnwers to some of the questions @gcs278 had

[gcs278]

Note: elastic/crd-ref-docs#86 will be pretty important, as crd-ref-docs always returns exit code 0, even when it fails generation.

I also opened elastic/crd-ref-docs#85 as the markdown template examples had incorrect format.

[k8s-ci-robot]

PR needs rebase.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[k8s-ci-robot]

@gcs278: The following tests failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
pull-gateway-api-crds-validation-1	253a987	link	true	/test pull-gateway-api-crds-validation-1
pull-gateway-api-crds-validation-2	253a987	link	true	/test pull-gateway-api-crds-validation-2
pull-gateway-api-crds-validation-3	253a987	link	true	/test pull-gateway-api-crds-validation-3
pull-gateway-api-crds-validation-4	253a987	link	true	/test pull-gateway-api-crds-validation-4
pull-gateway-api-crds-validation-5	253a987	link	true	/test pull-gateway-api-crds-validation-5

Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[gcs278]

Unfortunately I don't have the bandwidth to keep this going, and I'd like to focus on other Gateway API items, but I am willing to help support anyone that wants to pick this back up and work on it.
/close

[k8s-ci-robot]

@gcs278: Closed this PR.

In response to this:

Unfortunately I don't have the bandwidth to keep this going, and I'd like to focus on other Gateway API items, but I am willing to help support anyone that wants to pick this back up and work on it.
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.