Keep the list style for generated swagger doc

[haoruan]

What type of PR is this?

/kind bug
/kind documentation

What this PR does / why we need it:

The swagger_doc_generator doesn't parse the markdown list in comments correctly, some newlines are lost in the generated strings, which breaks the list formatting in the final documentation.

Which issue(s) this PR fixes:

Fixes #111388

Special notes for your reviewer:

This PR adds the newline for list style comments to keep the formatting, and also updates the auto-generated files.

Does this PR introduce a user-facing change?

NONE

Additional documentation e.g., KEPs (Kubernetes Enhancement Proposals), usage docs, etc.:

[k8s-ci-robot]

Hi @haoruan. Thanks for your PR.

I'm waiting for a kubernetes member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

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.

[k8s-triage-robot]

This PR may require API review.

If so, when the changes are ready, complete the pre-review checklist and request an API review.

Status of requested reviews is tracked in the API Review project.

[leilajal]

/cc @Jefftree @apelisse
/triage accepted

[Jefftree]

/ok-to-test

[Jefftree]

I noticed a couple of locations have additional new lines that may be unintentional. (The bold \n in the second bullet)

• Before: "matchPolicy defines how the "rules" list is used to match incoming requests. Allowed values are "Exact" or "Equivalent".\n\n- Exact: match a request only if it exactly matches a specified rule. For example, if deployments can be ...
• After: "matchPolicy defines how the "rules" list is used to match incoming requests. Allowed values are "Exact" or "Equivalent".\n\n- Exact: match a request only if it exactly matches a specified rule.\nFor example, if deployments can be...

Perhaps bullet points should need the line = "\n" + line + "\n" wrapper and only the newline prefix is enough?

[haoruan]

It works, but the single newline in the bullet point won't break the line and there're some other generated docs with newlines in the list:

• SyncFailed: The controller encountered an error and wasn't able to compute\n the number of allowed disruptions. Therefore no disruptions are\n allowed and the status of the condition will be False.

Also from the original comment, the "For example" starts a new line with no indent, so I'm not sure if it's part of the list or if it really wants to start a new line but didn't notice that it has no effect, so keep the newline here may have some meanings.

In this case I think the line = "\n" + line + "\n" is the same as line = "\n" + line + " " (from markdown list formatting view), so I combined them into one wrapper.

[Jefftree]

Ah I see what you mean. If it's rendered in markdown, then there is no difference between the two. I think stylistically omitting the newline would look better for clients that take the raw text without rendering markdown though. Will leave this as a nit

[liggitt]

I noticed a couple of locations have additional new lines that may be unintentional. (The bold \n in the second bullet)

I'm wondering if any of these are fallout from the go1.19 doc reformatting (xref #111254 (comment)):

Sweeping what 1.19 gofmt "autocorrected" in our doc strings, there's a fair number of places we had weird indents that gofmt is turning into new paragraphs, etc. I think this PR should go ahead and merge so we can get go1.19 signal, but a followup to sweep the doc auto format changes in this PR and fix up ones that look wrong would be good.

@dims, did an issue ever get opened for that?

[liggitt]

I think we first want to make sure our API doc is compatible with go's new support for lists in godoc, and then try to make this follow similar rules (or at least a subset of them):

• https://tip.golang.org/doc/go1.19#go-doc
• https://tip.golang.org/doc/comment#lists

[liggitt]

I don't think an issue got opened for #111254 (comment), no

[haoruan]

Thanks for confirm, if it’s all done with our API doc, I’d like to get this move forward since the rebase is quite annoying

[Jefftree]

A couple things I noticed from the docs that we're definitely missing at the moment:

Gofmt reformats bullet lists to use a dash as the bullet marker, two spaces of indentation before the dash, and four spaces of indentation for continuation lines.

I see some examples of misindents and bullet points using * instead of the standardized -

Gofmt preserves but does not require a blank line between a list and the preceding paragraph. It inserts a blank line between a list and the following paragraph or heading.

This is missing in certain places that we're using * to represent bullet points

I think this PR will still be required after fixing our API docs, but maybe the diff will be easier to compare with the API docs fixed beforehand.

[Jefftree]

@liggitt Since code freeze has passed, is this still something we can still get in as a bug fix or would we need to wait until 1.26?

[liggitt]

Since it's a long-standing issue, it's hard to justify it as a high-priority / release-blocking bug. I'd be inclined to merge it for 1.26. A fixup / follow-up for #111254 (comment) would be reasonable to do for 1.25, I think

[k8s-triage-robot]

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

This bot triages issues and PRs 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 or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

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

/lifecycle stale

[haoruan]

/remove-lifecycle stale

[dims]

If you still need this PR then please rebase, if not, please close the PR

[k8s-ci-robot]

New changes are detected. LGTM label has been removed.

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: haoruan
Once this PR has been reviewed and has the lgtm label, please ask for approval from liggitt. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• api/OWNERS
• staging/src/k8s.io/api/OWNERS
• staging/src/k8s.io/apimachinery/pkg/OWNERS
• staging/src/k8s.io/apimachinery/pkg/apis/OWNERS

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

[ePaul]

Do we have any example how the final generated documentation HTML looks like?

[haoruan]

For example:

Before is:

• rules.http.paths.pathType (string), required

  pathType determines the interpretation of the path matching. PathType can be one of the following values: * Exact: Matches the URL path exactly. * Prefix: Matches based on a URL path prefix split by '/'. Matching is
  done on a path element by element basis. A path element refers is the
  list of labels in the path split by the '/' separator. A request is a
  match for path p if every p is an element-wise prefix of p of the
  request path. Note that if the last element of the path is a substring
  of the last element in request path, it is not a match (e.g. /foo/bar
  matches /foo/bar/baz, but does not match /foo/barbaz).

  • ImplementationSpecific: Interpretation of the Path matching is up to
    the IngressClass. Implementations can treat this as a separate PathType
    or treat it identically to Prefix or Exact path types.
    Implementations are required to support all path types.

Now is:

• rules.http.paths.pathType (string), required

  pathType determines the interpretation of the path matching. PathType can be one of the following values:

  • Exact: Matches the URL path exactly.
  • Prefix: Matches based on a URL path prefix split by '/'. Matching is
    done on a path element by element basis. A path element refers is the
    list of labels in the path split by the '/' separator. A request is a
    match for path p if every p is an element-wise prefix of p of the
    request path. Note that if the last element of the path is a substring
    of the last element in request path, it is not a match (e.g. /foo/bar
    matches /foo/bar/baz, but does not match /foo/barbaz).
  • ImplementationSpecific: Interpretation of the Path matching is up to
    the IngressClass. Implementations can treat this as a separate PathType
    or treat it identically to Prefix or Exact path types.
    Implementations are required to support all path types.

[haoruan]

Just found that we also need the same change in k8s.io/kube-openapi, which generated the final swagger.json for website.

@Jefftree @liggitt Is this still looks good to you?

[k8s-ci-robot]

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.

[k8s-triage-robot]

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

This bot triages PRs 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 PR is closed

You can:

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

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

/close

[k8s-ci-robot]

@k8s-triage-robot: Closed this PR.

In response to this:

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

This bot triages PRs 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 PR is closed

You can:

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

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

/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.