update documentation & hooks

lavalamp · Jun 9, 2016 · adcd48c · adcd48c
1 parent 8faa886
commit adcd48c
Show file tree

Hide file tree

Showing 3 changed files with 22 additions and 9 deletions.
diff --git a/docs/devel/how-to-doc.md b/docs/devel/how-to-doc.md
@@ -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 -->
diff --git a/docs/devel/pull-requests.md b/docs/devel/pull-requests.md
@@ -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
 

diff --git a/hooks/pre-commit b/hooks/pre-commit
@@ -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"