mirror of
https://github.com/k3s-io/kubernetes.git
synced 2025-07-24 20:24:09 +00:00
update documentation & hooks
This commit is contained in:
parent
8faa88626d
commit
adcd48ccea
@ -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 -->
|
||||
[]()
|
||||
<!-- 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
|
||||
|
||||
|
@ -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"
|
||||
|
Loading…
Reference in New Issue
Block a user