New resourcesdocs generator

[feloy]

This generator is used to generate API Reference pages in Markdown format.

See kubernetes/website#23294 for more details

[k8s-ci-robot]

Thanks for your pull request. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please follow instructions at https://git.k8s.io/community/CLA.md#the-contributor-license-agreement to sign the CLA.

It may take a couple minutes for the CLA signature to be fully registered; after that, please reply here with a new comment and we'll verify. Thanks.

---

• If you've already signed a CLA, it's possible we don't have your GitHub username or you're using a different email address. Check your existing CLA data and verify that your email is set on your git commits.
• If you signed the CLA as a corporation, please sign in with your organization's credentials at https://identity.linuxfoundation.org/projects/cncf to be authorized.
• If you have done the above and are still having issues with the CLA being reported as unsigned, please log a ticket with the Linux Foundation Helpdesk: https://support.linuxfoundation.org/
• Should you encounter any issues with the Linux Foundation Helpdesk, send a message to the backup e-mail support address at: login-issues@jira.linuxfoundation.org

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. I understand the commands that are listed here.

[sftim]

I'm -0 (soft opposed) to including gen-resourcesdocs/api/v1.19/swagger.json and gen-resourcesdocs/api/v1.20/swagger.json; but that's something we could clean up later.

I'm also wary of including the configuration inside gen-resourcesdocs/config/v1.20/ in the same commit as the code that consumes it. These are two related but separate changes.
LGTM, but @feloy if you were willing to split this into multiple commits then I think that works even better.

I'd like someone familiar with Golang to confirm this change is OK to merge.

[sftim]

Would it make sense to take the version as a parameter somehow?

[feloy]

I'm -0 (soft opposed) to including gen-resourcesdocs/api/v1.19/swagger.json and gen-resourcesdocs/api/v1.20/swagger.json; but that's something we could clean up later.

It would be nice to make the build reproducible by being sure which swagger file has been used. Do you prefer we put the swagger file on the k/website repo wih the generated files?

[kbhawkey]

It would be really nice if there was a job that created a temporary k8s/k8s repo, grabbed a version of the spec, copied the spec to this repo or website.
Some of the code to create this job already exists in update-imported-docs script+reference.yml (create k8s/k8s repo) which calls updateapispec target (fetch swagger.json) in reference-docs/Makefile.

Temporarily, could add a command to the update-imported-docs script to copy a swagger file or make a new script based off parts of the update script. Drop the swagger file into website.

[tengqm]

/approve

I'm inclined to kick this in now and start the iteration.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: feloy, tengqm

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 [tengqm]

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

[kbhawkey]

I think it makes sense to get this in. I read through the code, though I have not tried to build the generator.
LGTM!!

[kbhawkey]

@sftim, What do you think about getting the source code in now? The swagger files can be removed when the build targets are updated. Is the plan to publish the 1.20 pages generated from the source?

[sftim]

@kbhawkey I agree with your LGTM from #179 (comment)

With the caveat that I haven't done code review and haven't much Golang experience.
/lgtm

[sftim]

@feloy many congratulations 🎉🎉🎉

[feloy]

@feloy many congratulations 🎉🎉🎉

Thanks to everybody 🎆🎆🎆

[kbhawkey]

Super!

[zacharysarah]

@feloy Congratulations! ✨ 🌟 ✨

[sftim]

I logged kubernetes/website#25505 to track switching k/website to use the new style API reference.