backlinks from example manifests to guides

[kundan2707]

/kind documentation

What this PR does / why we need it:

Which issue(s) this PR fixes:

Fixes #446

Does this PR introduce a user-facing change?:

None

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: kundan2707
To complete the pull request process, please assign dcbw after the PR has been reviewed.
You can assign the PR to them by writing /assign @dcbw in a comment when ready.

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

[youngnick]

Nice work!

/lgtm but will leave for someone else to hit the approve button.

[robscott]

Thanks for the work on this @kundan2707! This looks great, but unfortunately it had some unintended consequences :(. All of these comments end up being included in the docs as well: https://deploy-preview-1083--kubernetes-sigs-gateway-api.netlify.app/v1alpha2/guides/traffic-splitting/#guide. I spent a bit of time trying to figure out if there was a workaround here that would allow us to exclude comments from the rendered docs, but couldn't find a great solution for this.

Looking back at the original issue, it seems like the goal was to prevent code snippets from being updated without first considering all the files that would be affected by the change. Maybe a better solution here would be to have some kind of GitHub action/presubmit that did the following:

1. Check to see if any examples had been modified
2. Search to see if those examples have been included in any markdown
3. If 1 and 2 are true, add a comment on the PR with a list of examples that have been changed + where they are referenced in docs

I realize that's significantly more complicated than this approach, so open to alternatives. Unfortunately I think having these comments visible in our docs would be too distracting, so I want to put a hold on this until we can find a way around that or build some kind of automation like I suggested above.

/hold

[hbagdi]

Great work.
Rob's concern is fair.
Another path would be to play around with the plugin to see if we can exclude some (not all maybe) comments from the YAML.
For example: https://pypi.org/project/mkdocs-include-markdown-plugin/
This would require a bit more work on the tooling side.

[kundan2707]

Thanks for the work on this @kundan2707! This looks great, but unfortunately it had some unintended consequences :(. All of these comments end up being included in the docs as well: https://deploy-preview-1083--kubernetes-sigs-gateway-api.netlify.app/v1alpha2/guides/traffic-splitting/#guide. I spent a bit of time trying to figure out if there was a workaround here that would allow us to exclude comments from the rendered docs, but couldn't find a great solution for this.

Looking back at the original issue, it seems like the goal was to prevent code snippets from being updated without first considering all the files that would be affected by the change. Maybe a better solution here would be to have some kind of GitHub action/presubmit that did the following:

1. Check to see if any examples had been modified
2. Search to see if those examples have been included in any markdown
3. If 1 and 2 are true, add a comment on the PR with a list of examples that have been changed + where they are referenced in docs

I realize that's significantly more complicated than this approach, so open to alternatives. Unfortunately I think having these comments visible in our docs would be too distracting, so I want to put a hold on this until we can find a way around that or build some kind of automation like I suggested above.

/hold

@robscott Thanks for you suggestion. I will look for an alternative and discuss once found.

[k8s-ci-robot]

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

[youngnick]

I think that something like this is a good idea, but we need a way to not have the links show up in the rendered site version. I'm going to close this out for now, and encourage @kundan2707 to open a new issue to talk about the approach first.

Thanks for the work @kundan2707, hopefully we can work together to figure out the right way to proceed.

/close

[k8s-ci-robot]

@youngnick: Closed this PR.

In response to this:

I think that something like this is a good idea, but we need a way to not have the links show up in the rendered site version. I'm going to close this out for now, and encourage @kundan2707 to open a new issue to talk about the approach first.

Thanks for the work @kundan2707, hopefully we can work together to figure out the right way to proceed.

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