Discover the scope and requirements to refactor the K8s docs API generation process

[zacharysarah]

• Start research in the docs release playbook. Read all links and linked issues related to reference doc generation. (Make sure you understand the scope of the problem and what's required to fix it.)

• Create a new GitHub issue describing the requirements and scope of work required to refactor reference doc generation for a simple, reliable set of commands that produces output with improved, uniform formatting. (Make it easy for other stakeholders to understand the extent of the challenge and what's required to fix it.)

• Get stakeholder input, then implement a solution. (Get everyone on board, then fix the problem. The docs should be easy to generate, and the outputs should all match with better formatting.)

/sig docs
/priority important-soon
Assign to @aimeeu

[thecrudge]

This could potentially fix #15536

[aimeeu]

/assign

[aimeeu]

I learned from @kbhawkey and @tengqm that the purpose of the website/update-imported-docs/update-imported-docs tool is to automate the generation of the reference component docs. Once I had the correct versions of the required software installed, I ran the script locally and then updated the Generating Reference Pages for Kubernetes Components and Tools page (PR 16777) to reflect those versions.

Based on what I've learned, I'll talk to @jimangel about my updating the Docs Release Playbook to use the update-imported-docs tool. kbhawkey had a great idea - hold a training session for the docs release team (or person) since the process is new to the release team and many release team members are new to Docs as well.

[aimeeu]

I am testing the manual process vs the automated process to ensure the generated docs match between the two. Then I will update the docs playbook with the new process.

[aimeeu]

Testing

1. In directory 1, generate the API and kubectl references docs manually; process documented here
2. In directory 2, clone kubernetes/website and run the website/update-imported-docs/update-imported-docs.py script
3. Compare the two directories

update-imported-docs.py

1. does not create static/docs/reference/generated/kubernetes-api/<MINOR_VERSION> directory and the style files within; resolution: add to reference.yml: make copyapi, make copycli after make comp - this did not work
2. does not add the new <MINOR_VERSION> link to the content/en/docs/reference/_index.md
3. does not update the <MINOR_VERSION> in content/en/docs/reference/kubernetes-api/api-index.md

Best option for updating ref docs for a new release is to run the script and then manually update 2-3 above. For #1, best option is to copy the previous version's directory and rename for current release.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

[k8s-ci-robot]

@fejta-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/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.