Autogenerator code update in k/website for page weight issues

[natalisucks]

This is a Feature Request

During the KubeCon/CloudNativeCon NA 2022 SIG Docs sprint, a group of enthusiastic contributors worked on updating page weights as per the following bug report: Issue #35093. Our standard is that page weights are included in increments of 10 (10, 20, 30, etc.).

However, some of the pages that needed updating are auto-generated, which @sftim helpfully informed us of. After some discussion during the sprint and in the following Slack thread, it's been deemed worthwhile for us to update the page generator to produce our preferred values instead.

The generator code can be found here: website/update-imported-docs/update-imported-docs.py

Why is this needed

We need this to be updated so that page weights for auto-generated docs are following the standard that we're setting across docs. This is also worth prioritizing before the 1.26 release, thus is a high priority (and needs to be tracked by the Release 1.26 team).

/sig docs

[sftim]

/triage accepted

[sftim]

/priority important-soon

[a-mccarthy]

I also wanted to add a note that the new page https://github.com/kubernetes/website/blob/main/content/en/docs/reference/instrumentation/metrics.md does not have a page weight. It's the only page in that folder, but we should add a weight to the page to make sure we are following a new guidelines. This is a different autogenerated file than the reference/kubernetes-api docs, so it will need to be updated in a different place.

If we want I can open a separate issue about updating the page weight on this page. But i wanted to at least make a quick note about it while reviewing the remaining work for #35093

[a-mccarthy]

I was going through the reference folder and tried to make a list of all the autogenerated pages that need page weight changes. I'm not sure where all these pages are generated from however.

List of auto-generated pages that need page weights updates:

• https://github.com/kubernetes/website/tree/main/content/en/docs/reference/kubernetes-api All the folders and files in the folders are autogenerated (except the _index.md file) and should have the weights adjusted from using single digits to tens. For example, change weights of 1,2,3,4 to 10,20,30,40.
• /reference/command-line-tools-reference All these pages are in the same folder and have a page weight of 30
  • https://github.com/kubernetes/website/blob/main/content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
  • https://github.com/kubernetes/website/blob/main/content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
  • https://github.com/kubernetes/website/blob/main/content/en/docs/reference/command-line-tools-reference/kube-proxy.md
  • https://github.com/kubernetes/website/blob/main/content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
• https://github.com/kubernetes/website/tree/main/content/en/docs/reference/config-api These pages do not have page weights.
• https://github.com/kubernetes/website/blob/main/content/en/docs/reference/instrumentation/metrics.md: Needs page weight (my previous comment also talks about this page)

[tengqm]

@a-mccarthy I'll take a look at the page weight issue. There is a manually maintained index page for the config APIs, so page weights there don't matter that much. I'll check the command line tools references.

[a-mccarthy]

@tengqm, following up here, did you get a chance to look into this? thanks!

[tengqm]

For command line tools (aka, kubernetes components), I'm not sure which order is better. Maybe the default order (sorting the reference by component names) is already good enough? That means we can remove the weight or assign the same weight value.

[a-mccarthy]

@tengqm I'm not sure what section you are referring to re: command line tools (aka, kubernetes components). Can you share a link to the section you mean?

In general, we should be making sure that the page weights are all different, so that the page ordering is the same in localized content. From our style guide: https://kubernetes.io/docs/contribute/style/content-organization/#page-order

Note: For page weights, it can be smart not to use 1, 2, 3 ..., but some other interval, say 10, 20, 30... This allows you to insert pages where you want later. Additionally, each weight within the same directory (section) should not be overlapped with the other weights. This makes sure that content is always organized correctly, especially in localized content.

If the page weights are the same or missing, the site will use alphabetically order to list the pages. Which is different in each localization.

In the case of the https://kubernetes.io/docs/reference/kubernetes-api/, It seems like the pages are given a page weight based on a counter. If so, then I think we can do one of 2 things

1. Leave the page weights alone, because if a new page is added, it will automatically get a different page weight bc the page counter will adjust the page weights when the pages are generated again.
2. Update the page counter to count by 10s instead of 1s. This will set the weights to match the style guide recommendation to have pages separated by a weight of 10.

[tengqm]

@a-mccarthy I was talking about this page https://kubernetes.io/docs/reference/command-line-tools-reference/. The collection of the pages under that directory is stable.

For the files under /reference/command-line-tools-reference, they all have a page weight of 30 ..

This is not an issue IMO. I don't think any localization team would translate kube-apiserver.md into something else. The file name is the binary name and the binary name is always the same across all languages.

[sftim]

There is https://kubernetes.io/ko/docs/reference/command-line-tools-reference/kube-proxy/ as an example. The weights being the same is a small issue because the names of these tools don't get localized.

[a-mccarthy]

@sftim and @tengqm thanks for explaining! If those pages titles aren't going to be changed, then its probably a low priority to change the page weights.

Is that true for the other sections of the reference section? Looking at the config-api section in english https://kubernetes.io/docs/reference/config-api/ and chinese https://kubernetes.io/zh-cn/docs/reference/config-api/, some of the page titles are localized and the page ordering is different because those pages dont have page weights.

[tengqm]

It is probably true for other localization that the ordering of the reference pages are not consistent across languages, but I don't think that is an important issue. There is no inherent order among these reference pages anyway.

[sftim]

Are we happy to drop this to important-longterm priority? It feels lower priority than some of the other important-soon issues.

[a-mccarthy]

@sftim I think it's ok to move down in priority as long as all the changes needed in this section are in autogenerated code.

This seem like a good candidate to break up into "good first issues" because they are relatively small updates (i believe). But we need to have a clear way to point folks to the changes that need to be made. Do you think a tech lead or someone more familiar with the code base need to make these changes?

[k8s-triage-robot]

This issue is labeled with priority/important-soon but has not been updated in over 90 days, and should be re-triaged.
Important-soon issues must be staffed and worked on either currently, or very soon, ideally in time for the next release.

You can:

• Confirm that this issue is still relevant with /triage accepted (org members only)
• Deprioritize it with /priority important-longterm or /priority backlog
• Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted

[sftim]

//remove-priority important-soon
/priority backlog
/triage accepted

[sftim]

/remove-priority important-soon

[k8s-triage-robot]

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

• Confirm that this issue is still relevant with /triage accepted (org members only)
• Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle rotten
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

[k8s-ci-robot]

@k8s-triage-robot: Closing this issue, marking it as "Not Planned".

In response to this:

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

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.