update documentation & hooks

This commit is contained in:
Daniel Smith 2016-06-03 16:49:35 -07:00
parent 8faa88626d
commit adcd48ccea
3 changed files with 22 additions and 9 deletions

View File

@ -50,12 +50,13 @@ Updated: 11/3/2015
- [Unversioned Warning](#unversioned-warning)
- [Is Versioned](#is-versioned)
- [Generate Analytics](#generate-analytics)
- [Generated documentation](#generated-documentation)
<!-- END MUNGE: GENERATED_TOC -->
## General Concepts
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.
Each document needs to be munged to ensure its format is correct, links are valid, etc. To munge a document, simply run `hack/update-munge-docs.sh`. We verify that all documents have been munged using `hack/verify-munge-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
@ -66,7 +67,7 @@ Instead of writing table of contents by hand, insert the following code in your
<!-- END MUNGE: GENERATED_TOC -->
```
After running `hack/update-generated-docs.sh`, you'll see a table of contents generated for you, layered based on the headings.
After running `hack/update-munge-docs.sh`, you'll see a table of contents generated for you, layered based on the headings.
## How to Write Links
@ -99,7 +100,7 @@ While writing examples, you may want to show the content of certain example file
<!-- END MUNGE: EXAMPLE path/to/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.
Note that you should replace `path/to/file` with the relative path to the example file. Then `hack/update-munge-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:
@ -108,7 +109,7 @@ For example, the following:
<!-- END MUNGE: EXAMPLE ../user-guide/pod.yaml -->
```
generates the following after `hack/update-generated-docs.sh`:
generates the following after `hack/update-munge-docs.sh`:
<!-- BEGIN MUNGE: EXAMPLE ../user-guide/pod.yaml -->
@ -169,11 +170,11 @@ Mungers are like gofmt for md docs which we use to format documents. To use it,
<!-- END MUNGE: xxxx -->
```
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.
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-munge-docs.sh`. See [munger document](http://releases.k8s.io/HEAD/cmd/mungedocs/) for more details.
## Auto-added 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.
After running `hack/update-munge-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
@ -207,6 +208,17 @@ ANALYTICS munger inserts a Google Anaylytics link for this page.
<!-- END MUNGE: GENERATED_ANALYTICS -->
```
# Generated documentation
Some documents can be generated automatically. Run `hack/generate-docs.sh` to
populate your repository with these generated documents, and a list of the files
it generates is placed in `.generated_docs`. To reduce merge conflicts, we do
not want to check these documents in; however, to make the link checker in the
munger happy, we check in a placeholder. `hack/update-generated-docs.sh` puts a
placeholder in the location where each generated document would go, and
`hack/verify-generated-docs.sh` verifies that the placeholder is in place.
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/how-to-doc.md?pixel)]()
<!-- END MUNGE: GENERATED_ANALYTICS -->

View File

@ -69,8 +69,9 @@ Additionally, for infrequent or new contributors, we require the on call to appl
The following will save time for both you and your reviewer:
* Enable [pre-commit hooks](development.md#committing-changes-to-your-fork) and verify they pass.
* Verify `hack/verify-generated-docs.sh` passes.
* Verify `hack/verify-all.sh` passes.
* Verify `hack/test-go.sh` passes.
* Verify `hack/test-integration.sh` passes.
## Release Notes

View File

@ -123,11 +123,11 @@ fi
echo "${reset}"
echo -ne "Checking for docs that need updating... "
if ! hack/verify-generated-docs.sh > /dev/null; then
if ! hack/verify-munge-docs.sh > /dev/null; then
echo "${red}ERROR!"
echo "Some docs are out of sync between CLI and markdown."
echo "To regenerate docs, run:"
echo " hack/update-generated-docs.sh"
echo " hack/update-munge-docs.sh"
exit_code=1
else
echo "${green}OK"