kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Add clarification about API resources to the Style Guide

pull/35119/head
Rishit Dagli 2022-07-18 05:34:11 +00:00
parent bdadfbcf45
commit 989e8ac98c
1 changed files with 30 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
content/en/docs/contribute/style/style-guide.md
View File

@ -46,10 +46,6 @@ When you refer specifically to interacting with an API object, use [UpperCamelCa
When you are generally discussing an API object, use [sentence-style capitalization](https://docs.microsoft.com/en-us/style-guide/text-formatting/using-type/use-sentence-style-capitalization).
You may use the word "resource", "API", or "object" to clarify a Kubernetes resource type in a sentence.
Don't split an API object name into separate words. For example, use PodTemplateList, not Pod Template List.
The following examples focus on capitalization. For more information about formatting API object names, review the related guidance on [Code Style](#code-style-inline-code).
{{< table caption = "Do and Don't - Use Pascal case for API objects" >}}
@ -187,6 +183,36 @@ Set the value of `image` to nginx:1.16. | Set the value of `image` to `nginx:1.1
Set the value of the `replicas` field to 2. | Set the value of the `replicas` field to `2`.
{{< /table >}}
## Referring to Kubernetes API resources
This section talks about how we reference API resources in the documentation.
### Clarification about "resource"
Kubernetes uses the word "resource" to refer to API resources, such as `pod`, `deployment`, and so on. We also use "resource" to talk about CPU and memory requests and limits. Always refer to API resources as "API resources" to avoid confusion with CPU and memory resources.
### When to use Kubernetes API terminologies
The different Kubernetes API terminologies are:
- Resource type: the name used in the API URL (such as `pods`, `namespaces`)
- Resource: a single instance of a resource type (such as `pod`, `secret`)
- Object: a resource that serves as a "record of intent". An object is a desired state for a specific part of your cluster, which the Kubernetes control plane tries to maintain.
Always use "resource" or "object" when referring to an API resource in docs. For example, use "a `Secret` object" over just "a `Secret`".
### API resource names
Always format API resource names using [UpperCamelCase](https://en.wikipedia.org/wiki/Camel_case), also known as PascalCase, and code formatting.
For inline code in an HTML document, use the `<code>` tag. In a Markdown document, use the backtick (`` ` ``).
Don't split an API object name into separate words. For example, use `PodTemplateList`, not Pod Template List.
For more information about PascalCase and code formatting, please review the related guidance on [Use upper camel case for API objects](/docs/contribute/style/style-guide/#use-upper-camel-case-for-api-objects) and [Use code style for inline code, commands, and API objects](/docs/contribute/style/style-guide/#code-style-inline-code).
For more information about Kubernetes API terminologies, please review the related guidance on [Kubernetes API terminology](/docs/reference/using-api/api-concepts/#standard-api-terminology).
## Code snippet formatting
### Don't include the command prompt