From adcd48ccea67f79eeaebfc998bc7c4b27ae4c55d Mon Sep 17 00:00:00 2001 From: Daniel Smith Date: Fri, 3 Jun 2016 16:49:35 -0700 Subject: [PATCH] update documentation & hooks --- docs/devel/how-to-doc.md | 24 ++++++++++++++++++------ docs/devel/pull-requests.md | 3 ++- hooks/pre-commit | 4 ++-- 3 files changed, 22 insertions(+), 9 deletions(-) diff --git a/docs/devel/how-to-doc.md b/docs/devel/how-to-doc.md index 2c50861159d..67bffe154ef 100644 --- 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) ## 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 ``` -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 ``` -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: ``` -generates the following after `hack/update-generated-docs.sh`: +generates the following after `hack/update-munge-docs.sh`: @@ -169,11 +170,11 @@ Mungers are like gofmt for md docs which we use to format documents. To use it, ``` -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. ``` +# 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. + + [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/how-to-doc.md?pixel)]() diff --git a/docs/devel/pull-requests.md b/docs/devel/pull-requests.md index 64a1c2c6eba..6803c464656 100644 --- 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 index 0553a034574..9bff62756f0 100755 --- 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"