Update docs to use v1beta1

[EmilyShepherd]

[EDIT: In light of @robscott's suggestion, the change of the documentation reference to v1beta1 has been removed from this PR - all examples will continue to use v1alpha2 for the moment.]

What type of PR is this?
/kind documentation

What this PR does / why we need it:
This PR is part of #1229 which requires updating examples and documentation to use the newer v1beta1 versions of resources, where appropriate. It does the following:

• Adds v1beta1 examples to hack/invalid-examples
• Adds v1beta1 examples to examples/experimental
• Updates the api-docs auto generator scripts to generate both v1beta1 and v1alpha2
• Updates the documentation to refer to v1beta1 examples were possible.
• Updates the documentation's file structure to remove the v1alpha2 prefix (v1alpha2 symlinks have been left in place to ensure that links to the old URLs still work).
• Updates the "Used In" metadata headers in all examples (either by removing them for examples that are no longer used, or by ensuring that their path does not contain the old-style v1alpha2 prefix).

Notable points:

• The hack/api-docs/generate.sh script had to be refactored slightly to have to generate both versions of the api
• The apis/docs.go stub had to be added to get gen-crd-api-reference-docs to recognise apis as a go package and therefore scan its subdirectories.
• Gateway, GatewayClass, and HTTPRoute have been explictly excluded from the v1alpha2 api-docs generation, as they already appear in v1beta1. It is debatable if this is "correct" behaviour as they do, of course, still exist in the v1alpha2 version, but it felt redundant to include them twice in the docs.

Which issue(s) this PR fixes:
Addresses #1229

Does this PR introduce a user-facing change?:

Add examples and documentation for v1beta1

[k8s-ci-robot]

Welcome @EmilyShepherd!

It looks like this is your first PR to kubernetes-sigs/gateway-api 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/gateway-api has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

[k8s-ci-robot]

Hi @EmilyShepherd. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

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/test-infra repository.

[keithmattix]

I don't have enough context to validate the approach here, but I spent some time clicking through the Netlify preview, and it looks correct from what I saw!

[robscott]

Thanks @EmilyShepherd, this is great! Now that I'm realizing that our actual release date is 2 weeks away (July 12), I'm realizing that we could result in a confusing state of our docs if we're not careful.

Specifically if our examples all show the v1beta1 API group but our getting started section still recommends installing v0.4.3 (without v1beta1). I think that leaves us with two options:

1. Update docs to recommend installing v0.5.0 release candidate
2. Hold off on this specific part of the change until we release v0.5.0

I think 2 is the much safer option. If that makes sense to you, do you mind keeping the last 2 commits of this PR for a later PR that we can merge right after we release v0.5.0?

[robscott]

/ok-to-test

[EmilyShepherd]

Thanks @EmilyShepherd, this is great! Now that I'm realizing that our actual release date is 2 weeks away (July 12), I'm realizing that we could result in a confusing state of our docs if we're not careful.

Specifically if our examples all show the v1beta1 API group but our getting started section still recommends installing v0.4.3 (without v1beta1). I think that leaves us with two options:

1. Update docs to recommend installing v0.5.0 release candidate
2. Hold off on this specific part of the change until we release v0.5.0

I think 2 is the much safer option. If that makes sense to you, do you mind keeping the last 2 commits of this PR for a later PR that we can merge right after we release v0.5.0?

If it were one of my own projects, I'd normally just go straight to recommending the latest version, but that is most definately not a call for me to make.

So I am therefore more than happy to take the last two commits out and split them into a seperate PR. I'll have to update the api-docs gen code to no longer exclude HTTPRoute, Gateway and GatewayClass from the v1alpha2 version (as without the change in the docs, many pages will still be referencing the v1alpha2 versions, so it is important that they exist in the spec).

I'll pull those commits out, make that change (and also do an intermediate repair of "Used By" headers, which will be wrong if we merge just the first few commits in) now.

If you would like, I could also amend this PR to still include the dropping of the v1alpha2 url prefix (but not change any of the examples / spec references) as that feels like it would be safe to do pre-release?

[robscott]

This is really great, thanks @EmilyShepherd! Just a couple nits but otherwise LGTM.

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: EmilyShepherd, robscott

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

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [robscott]

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

[robscott]

If it were one of my own projects, I'd normally just go straight to recommending the latest version

I'd usually agree, but since we still only have a release candidate, we historically have recommended installing the latest stable release until we get another full release out.

[robscott]

Thanks @EmilyShepherd!

/lgtm