Permalink
Browse files

update documentation & hooks

  • Loading branch information...
lavalamp committed Jun 3, 2016
1 parent 8faa886 commit adcd48ccea67f79eeaebfc998bc7c4b27ae4c55d
Showing with 22 additions and 9 deletions.
  1. +18 −6 docs/devel/how-to-doc.md
  2. +2 −1 docs/devel/pull-requests.md
  3. +2 −2 hooks/pre-commit
View
@@ -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 -->
@@ -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
@@ -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"

0 comments on commit adcd48c

Please sign in to comment.