Code blocks not rendered properly in API Documentation (Quantity)

[Jefftree]

This is a Bug Report

Problem: Code blocks not rendered properly in documentation

See https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#quantity-resource-core

The Quantity description has a code block embedded in the code https://github.com/kubernetes/kubernetes/blob/3ffdfbe286ebcea5d75617da6accaf67f815e0cf/api/openapi-spec/v3/apis__node.k8s.io__v1_openapi.json#L177

(This is the same as what is provided in the swagger.json. The swagger.json file wasn't able to be linked because it's too large for Github's code search)

This is not being rendered properly and is just dumped on one line in the documentation

Proposed Solution: I haven't really looked into the code, is this something that can be fixed in the Markdown rendering?

Page to Update:
https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#quantity-resource-core

^ Docs for future k8s versions

[sftim]

/remove-kind bug

/kind feature

We see reference doc generation as best-effort. There's definitely room for improvement.

[RA489]

/triage accepted

[sftim]

Duplicated by #36947

[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

[k8s-triage-robot]

The Kubernetes project currently lacks enough active 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 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 rotten

[Jefftree]

/remove-lifecycle rotten

[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

[sftim]

/remove-lifecycle rotten

[sftim]

Also affected: https://kubernetes.io/docs/reference/kubernetes-api/common-definitions/quantity/#Quantity

[sftim]

How I'd like this fixed:

• define and use a convention in the Go source code to mark when comments are Markdown
  I learned that OpenAPI description is always Markdown
• publish Markdown for the field descriptions using an extension
  I learned that OpenAPI description is always Markdown
• render the Markdown description to plain text for the description OpenAPI field
  I learned that OpenAPI description is always Markdown
• update the reference documentation generator to use the Markdown, not the plain text with heuristics

We should either:

• convert all the source code to use Markdown in comments that could become an OpenAPI description
• convert all the source code to a different in comments that could become an OpenAPI description, and implement a translation layer that produces Markdown (CommonMark)

Optionally, also:

• lint the hypertext embedded within k/k source code

[sftim]

Also see kubernetes-sigs/reference-docs#293

[sftim]

/triage accepted

[sftim]

/remove-kind feature
/kind bug

[sftim]

Duplicated by #47070

[robert-cronin]

I have a couple of ideas for a potential fix for this issue if no one has picked it up yet.
/assign

[sftim]

Help is (still) welcome. It may be that most of the work is around getting the OpenAPI to contain the right Markdown, and then the docs generation becomes relatively easy.