search

kubernetes / website

Kubernetes website and documentation repo:
https://kubernetes.io
Creative Commons Attribution 4.0 International
4.47k stars 14.38k forks source link

Autogenerator code update in k/website for page weight issues #37486

Closed natalisucks closed 2 weeks ago

natalisucks commented 1 year ago

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 commented 1 year ago

/triage accepted

sftim commented 1 year ago

/priority important-soon

a-mccarthy commented 1 year ago

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 commented 1 year ago

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:

tengqm commented 1 year ago

@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 commented 1 year ago

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

tengqm commented 1 year ago

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 commented 1 year ago

@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 commented 1 year ago

@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 commented 1 year ago

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 commented 1 year ago

@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 commented 1 year ago

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 commented 1 year ago

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

a-mccarthy commented 1 year ago

@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 commented 1 year ago

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:

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

/remove-triage accepted

sftim commented 1 year ago

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

sftim commented 1 year ago

/remove-priority important-soon

k8s-triage-robot commented 5 months ago

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

You can:

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

/remove-triage accepted

k8s-triage-robot commented 2 months ago

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

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

You can:

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

/lifecycle stale

k8s-triage-robot commented 1 month ago

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:

You can:

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

/lifecycle rotten

k8s-triage-robot commented 2 weeks ago

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:

You can:

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

/close not-planned

k8s-ci-robot commented 2 weeks ago

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

In response to [this](https://github.com/kubernetes/website/issues/37486#issuecomment-2381057562): >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][1] > >Please send feedback to sig-contributor-experience at [kubernetes/community](https://github.com/kubernetes/community). > >/close not-planned > >[1]: https://www.kubernetes.dev/docs/guide/issue-triage/ Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes-sigs/prow](https://github.com/kubernetes-sigs/prow/issues/new?title=Prow%20issue:) repository.