The placeholder documentation introduces a couple of problems:
- it complicates the contributor-experience (forces the CI to run
N times before the contributor finds out that they need to call an .sh
script and include certain files from docs/)
- it forces CLI related pull requests for tools like kubeadm and kubectl
to require top level approval from docs/OWNERS as such PRs still need
to touch the .generated_docs file
Stop tracking the placeholder documentation by applying the
following actions:
- remove the utility set-placeholder-gen-docs()
- make verify-generated-docs.sh only generate in a temporary folder
and not match .generated_docs
- mark generate-docs.sh as an alias for update-generated-docs.sh
- remove all current placeholder files in docs folders admin, man,
user-guide, yaml
- ignore the above folders and .generated_docs in a .gitignore file
This allows us to start building real dependencies into Makefile.
Leave old hack/* scripts in place but advise to use 'make'. There are a few
rules that call things like 'go run' or 'build/*' that I left as-is for now.
Auto generated docs are **NO LONGER CHECKED IN**, only placeholders.
To generate them, e.g. before exporting docs, run hack/generate-docs.sh.
hack/verify-generated-docs.sh ensures that generated docs are merely the
placeholder text.
hack/update-generated-docs.sh puts the placeholder text in the proper
places.
The old munge behavior is moved into hack/{update|verify}-munge-docs.sh.
SataQiu