Distinguish between API resources vs. field definitions (subresources)

[sftim]

This is a Feature Request

What would you like to be added
Distinguish between API resources vs. field definitions in the API reference. This distinction should appear in both listings and in detailed pages such as https://k8s.io/docs/reference/kubernetes-api/workloads-resources/ephemeral-containers-v1/

Ideally the reader also understands whether and why the field definition / subresource is or isn't versioned (compare /docs/reference/kubernetes-api/workloads-resources/ephemeral-containers-v1/ to /docs/reference/kubernetes-api/workloads-resources/container/)

Why is this needed
On a page such as https://kubernetes.io/docs/reference/kubernetes-api/workloads-resources/ I can (currently) see
the first 5 items:

1. Pod Pod is a collection of containers that can run on a host.
2. Container A single application container that you want to run within a pod.
3. EphemeralContainer An EphemeralContainer is a container that may be added temporarily to an existing pod for user-initiated activities such as debugging.
4. PodTemplate PodTemplate describes a template for creating copies of a predefined pod.
5. ReplicationController ReplicationController represents the configuration of a replication controller.

I know that I can send a HTTP request to query Pod and ReplicationController resources from the API. These are indeed resources in the HTTP sense of the term. However, for others such as PodTemplateContainer, those (as I see it) define the structure of fields within other resources. It's important to document those fields and their definitions, but it's also helpful for the reader to understand which items are actually resources that they can interact with directly via the API.

Comments

[sftim]

/sig architecture
/sig api-machinery

[sftim]

/language en

[sftim]

@feloy I'd be interested to learn your thoughts on this. I think it's a matter not just for the specific API generator that you led the work on - there are also open questions about how we explain these differences more generally.

[kbhawkey]

/triage accepted

[sftim]

Relevant to #25505

[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-contributor-experience at kubernetes/community.
/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-contributor-experience at kubernetes/community.
/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-contributor-experience at kubernetes/community.
/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-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.