From 5e0f47fe015cbaf0f29ee6f3a8f33bed4bd14ff2 Mon Sep 17 00:00:00 2001 From: Janet Kuo Date: Tue, 3 Nov 2015 13:27:24 -0800 Subject: [PATCH 1/2] Document how to document --- docs/devel/how-to-doc.md | 171 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 docs/devel/how-to-doc.md diff --git a/docs/devel/how-to-doc.md b/docs/devel/how-to-doc.md new file mode 100644 index 00000000000..718aa8c0094 --- /dev/null +++ b/docs/devel/how-to-doc.md @@ -0,0 +1,171 @@ + + + + +WARNING +WARNING +WARNING +WARNING +WARNING + +

PLEASE NOTE: This document applies to the HEAD of the source tree

+ +If you are using a released version of Kubernetes, you should +refer to the docs that go with that version. + + +The latest 1.0.x release of this document can be found +[here](http://releases.k8s.io/release-1.0/docs/devel/how-to-doc.md). + +Documentation for other releases can be found at +[releases.k8s.io](http://releases.k8s.io). + +-- + + + + + +Document Conventions +==================== + +Updated: 11/3/2015 + +*This document is oriented at users and developers who want to write documents for Kubernetes.* + +**Table of Contents** + + + - [What Are Mungers?](#what-are-mungers) + - [Table of Contents](#table-of-contents) + - [Writing Examples](#writing-examples) + - [Adding Links](#adding-links) + - [Auto-added Mungers](#auto-added-mungers) + - [Unversioned Warning](#unversioned-warning) + - [Is Versioned](#is-versioned) + - [Generate Analytics](#generate-analytics) + + + +## What Are Mungers? + +Mungers are like gofmt for md docs which we use to format documents. To use it, simply place + +``` + + +``` + +in your md files. Note that xxxx is the placeholder for a specific munger. Appropriate content will be generated and inserted between two brackets after you run `hack/update-generated-docs.sh`. See [munger document](../../cmd/mungedocs/) for more details. + + +## Table of Contents + +Instead of writing table of contents by hand, use the TOC munger: + +``` + + +``` + +## Writing Examples + +Sometimes you may want to show the content of certain example files. Use EXAMPLE munger whenever possible: + +``` + + +``` + +This way, you save the time to do the copy-and-paste; what's better, the content won't become out-of-date everytime you update the example file. + +For example, the following munger: + +``` + + +``` + +generates + + +```yaml +apiVersion: v1 +kind: Pod +metadata: + name: nginx + labels: + app: nginx +spec: + containers: + - name: nginx + image: nginx + ports: + - containerPort: 80 +``` + +[Download example](../user-guide/pod.yaml?raw=true) + + +## Adding Links + +Use inline link instead of url at all times. When you add internal links from `docs/` to `docs/` or `examples/`, use relative links; otherwise, use `http://releases.k8s.io/HEAD/`. For example, use: + +``` +[GCE](../getting-started-guides/gce.md) # note that it's under docs/ +[Kubernetes package](http://releases.k8s.io/HEAD/pkg/) # note that it's under pkg/ +[Kubernetes](http://kubernetes.io/) +``` + +and avoid using: + +``` +[GCE](https://github.com/kubernetes/kubernetes/blob/master/docs/getting-started-guides/gce.md) +[Kubernetes package](../../pkg/) +http://kubernetes.io/ +``` + +## Auto-added Mungers + +Some mungers are auto-added. You don't have to add them manually, and `hack/update-generated-docs.sh` does that for you. It's recommended to just read this section as a reference instead of messing up with the following mungers. + +### Unversioned Warning + +UNVERSIONED_WARNING munger inserts unversioned warning which warns the users when they're reading the document from HEAD and informs them where to find the corresponding document for a specific release. + +``` + + + + + + +``` + +### Is Versioned + +IS_VERSIONED munger inserts `IS_VERSIONED` tag in documents in each release, which stops UNVERSIONED_WARNING munger from inserting warning messages. + +``` + + + +``` + +### Generate Analytics + +ANALYTICS munger inserts a Google Anaylytics link for this page. + +``` + + +``` + + +[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/how-to-doc.md?pixel)]() + From 024df3c04cb66a3b1ca6a23cc60a5a387d680906 Mon Sep 17 00:00:00 2001 From: Janet Kuo Date: Fri, 6 Nov 2015 17:19:21 -0800 Subject: [PATCH 2/2] address comments --- docs/devel/how-to-doc.md | 109 +++++++++++++++++++++++++++------------ 1 file changed, 77 insertions(+), 32 deletions(-) diff --git a/docs/devel/how-to-doc.md b/docs/devel/how-to-doc.md index 718aa8c0094..283cab1f7ab 100644 --- a/docs/devel/how-to-doc.md +++ b/docs/devel/how-to-doc.md @@ -31,8 +31,7 @@ Documentation for other releases can be found at -Document Conventions -==================== +# Document Conventions Updated: 11/3/2015 @@ -41,10 +40,16 @@ Updated: 11/3/2015 **Table of Contents** +- [Document Conventions](#document-conventions) + - [General Concepts](#general-concepts) + - [How to Get a Table of Contents](#how-to-get-a-table-of-contents) + - [How to Write Links](#how-to-write-links) + - [How to Include an Example](#how-to-include-an-example) + - [Misc.](#misc) + - [Code formatting](#code-formatting) + - [Syntax Highlighting](#syntax-highlighting) + - [Headings](#headings) - [What Are Mungers?](#what-are-mungers) - - [Table of Contents](#table-of-contents) - - [Writing Examples](#writing-examples) - - [Adding Links](#adding-links) - [Auto-added Mungers](#auto-added-mungers) - [Unversioned Warning](#unversioned-warning) - [Is Versioned](#is-versioned) @@ -52,46 +57,63 @@ Updated: 11/3/2015 -## What Are Mungers? +## General Concepts -Mungers are like gofmt for md docs which we use to format documents. To use it, simply place +Each document needs to be munged to ensure its format is correct, links are valid, etc. To munge a document, simply run `hack/update-generated-docs.sh`. We verify that all documents have been munged using `hack/verify-generated-docs.sh`. The scripts for munging documents are called mungers, see the [mungers section](#what-are-mungers) below if you're curious about how mungers are implemented or if you want to write one. -``` - - -``` +## How to Get a Table of Contents -in your md files. Note that xxxx is the placeholder for a specific munger. Appropriate content will be generated and inserted between two brackets after you run `hack/update-generated-docs.sh`. See [munger document](../../cmd/mungedocs/) for more details. - - -## Table of Contents - -Instead of writing table of contents by hand, use the TOC munger: +Instead of writing table of contents by hand, insert the following code in your md file: ``` ``` -## Writing Examples +After running `hack/update-generated-docs.sh`, you'll see a table of contents generated for you, layered based on the headings. -Sometimes you may want to show the content of certain example files. Use EXAMPLE munger whenever possible: +## How to Write Links + +It's important to follow the rules when writing links. It helps us correctly versionize documents for each release. + +Use inline links instead of urls at all times. When you add internal links to `docs/` or `examples/`, use relative links; otherwise, use `http://releases.k8s.io/HEAD/`. For example, avoid using: + +``` +[GCE](https://github.com/kubernetes/kubernetes/blob/master/docs/getting-started-guides/gce.md) # note that it's under docs/ +[Kubernetes package](../../pkg/) # note that it's under pkg/ +http://kubernetes.io/ # external link +``` + +Instead, use: + +``` +[GCE](../getting-started-guides/gce.md) # note that it's under docs/ +[Kubernetes package](http://releases.k8s.io/HEAD/pkg/) # note that it's under pkg/ +[Kubernetes](http://kubernetes.io/) # external link +``` + +The above example generates the following links: [GCE](../getting-started-guides/gce.md), [Kubernetes package](http://releases.k8s.io/HEAD/pkg/), and [Kubernetes](http://kubernetes.io/). + +## How to Include an Example + +While writing examples, you may want to show the content of certain example files (e.g. [pod.yaml](../user-guide/pod.yaml)). In this case, insert the following code in the md file: ``` ``` -This way, you save the time to do the copy-and-paste; what's better, the content won't become out-of-date everytime you update the example file. +Note that you should replace `path/to/file` with the relative path to the example file. Then `hack/update-generated-docs.sh` will generate a code block with the content of the specified file, and a link to download it. This way, you save the time to do the copy-and-paste; what's better, the content won't become out-of-date every time you update the example file. -For example, the following munger: +For example, the following: ``` ``` -generates +generates the following after `hack/update-generated-docs.sh`: + ```yaml @@ -112,27 +134,50 @@ spec: [Download example](../user-guide/pod.yaml?raw=true) -## Adding Links +## Misc. -Use inline link instead of url at all times. When you add internal links from `docs/` to `docs/` or `examples/`, use relative links; otherwise, use `http://releases.k8s.io/HEAD/`. For example, use: +### Code formatting + +Wrap a span of code with single backticks (`` ` ``). To format multiple lines of code as its own code block, use triple backticks (```` ``` ````). + +### Syntax Highlighting + +Adding syntax highlighting to code blocks improves readability. To do so, in your fenced block, add an optional language identifier. Some useful identifier includes `yaml`, `console` (for console output), and `sh` (for shell quote format). Note that in a console output, put `$ ` at the beginning of each command and put nothing at the beginning of the output. Here's an example of console code block: ``` -[GCE](../getting-started-guides/gce.md) # note that it's under docs/ -[Kubernetes package](http://releases.k8s.io/HEAD/pkg/) # note that it's under pkg/ -[Kubernetes](http://kubernetes.io/) +```console + +$ kubectl create -f docs/user-guide/pod.yaml +pod "foo" created + +```　 ``` -and avoid using: +which renders as: + +```console +$ kubectl create -f docs/user-guide/pod.yaml +pod "foo" created +``` + +### Headings + +Add a single `#` before the document title to create a title heading, and add `##` to the next level of section title, and so on. Note that the number of `#` will determine the size of the heading. + +## What Are Mungers? + +Mungers are like gofmt for md docs which we use to format documents. To use it, simply place ``` -[GCE](https://github.com/kubernetes/kubernetes/blob/master/docs/getting-started-guides/gce.md) -[Kubernetes package](../../pkg/) -http://kubernetes.io/ + + ``` +in your md files. Note that xxxx is the placeholder for a specific munger. Appropriate content will be generated and inserted between two brackets after you run `hack/update-generated-docs.sh`. See [munger document](http://releases.k8s.io/HEAD/cmd/mungedocs/) for more details. + ## Auto-added Mungers -Some mungers are auto-added. You don't have to add them manually, and `hack/update-generated-docs.sh` does that for you. It's recommended to just read this section as a reference instead of messing up with the following mungers. +After running `hack/update-generated-docs.sh`, you may see some code / mungers in your md file that are auto-added. You don't have to add them manually. It's recommended to just read this section as a reference instead of messing up with the following mungers. ### Unversioned Warning