Documenting Code¶
Looking for a template?
//todo
Words requiring code formatting¶
Apply code formatting only to special-purpose text:
- Filenames
- Path names
- Fields and values from a YAML file
- Any text that goes into a CLI
- CLI names
Specify the programming language¶
Specify the language your code is in as part of the code block
Specify non-language specific code, like CLI commands, with ```bash. See the following examples for formatting.
package main
import "fmt"
func main() {
fmt.Println("hello world")
}
package main
import "fmt"
func main() {
fmt.Println("hello world")
}
```go
package main
import "fmt"
func main() {
fmt.Println("hello world")
}
```
```bash
package main
import "fmt"
func main() {
fmt.Println("hello world")
}
```
Documenting commands¶
The standard line is “X the Y by running the command:”
It meets these criteria:
- It explicitly mentions running the command, which isn’t always obvious
- It uses “run”; not “type”, “execute”, etc -- we want consistency
- It describes what the command does before stating the command.
- It's as short as possible
If you must deviate from the standard line, ensure you still meet these criteria.
Create the service by running the command:
kn create service <service-name>
<service-name> is the name of your Knative Service.
Example 1:
Create the service:
kn create service <service-name>
<service-name> is the name of your Knative Service.
Example 2:
Run:
kn create service <service-name>
<service-name> is the name of your Knative Service.
Example 3:
Run the following command to create a service:
kn create service <service-name>
<service-name> is the name of your Knative Service.
Documenting YAML¶
When documenting YAML, use two steps. Use step 1 to create the YAML file, and step 2 to apply the YAML file.
Use kubectl apply for files/objects that the user creates: it works for both “create” and “update”, and the source of truth is their local files.
Use kubectl edit for files which are shipped as part of the Knative software, like the Knative Serving and Knative Eventing ConfigMaps.
Write ```yaml at the beginning of your code block if you are typing YAML code as part of a CLI command.
-
Creating or updating a resource:
-
Create a YAML file using the following template:
# YAML FILE CONTENTS -
Apply the YAML file by running the command:
Wherekubectl apply -f <filename>.yaml<filename>is the name of the file you created in the previous step.
-
-
Editing a ConfigMap:
kubectl -n <namespace> edit configmap <resource-name>
Example 1:
cat <<EOF | kubectl create -f -
# code
EOF
Example 2:
kubectl apply -f - <<EOF
# code
EOF
Referencing variables in code blocks¶
Format variables in code blocks like so:
- All lowercase
- Hyphens between words
- Explanation for each variable below code block
- Explanation format is “Where...
<service-name>is…"
Single variable¶
kn create service <service-name>
<service-name> is the name of your Knative Service.
kn create service {SERVICE_NAME}
Multiple variables¶
kn create service <service-name> --revision-name <revision-name>
<service-name>is the name of your Knative Service.<revision-name>is the desired name of your revision.
kn create service <service-name> --revision-name <revision-name>
<service-name> is the name of your Knative Service.Where
<revision-name> is the desired name of your revision.
Indicating code excerpts¶
If you are documenting an excerpt of a YAML file, rather than an entire working YAML example, include
...in places where context is missing to indicate that the example is only a part of the required file.
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
...
spec:
...
traffic:
- percent: 54
revisionName: config-00008
...
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
spec:
traffic:
- percent: 54
revisionName: config-00008
CLI output¶
CLI Output should include the custom css "{ .bash .no-copy }" in place of "bash" which removes the "Copy to clipboard button" on the right side of the code block
<some-code>
<some-code>
```{ .bash .no-copy }
<some-code>
```
```bash
<some-code>
```