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
Checking the exit code rather than the empty string has the advantage
that you can identify what was found (comparison consumes the string, so
it's not printed). It makes debugging much easier when something is wrong.
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.
Right now some of the hack/* tools use `go run` and build almost every
time. There are some which expect you to have already run `go install`.
And in all cases the pre-commit hook, which runs a full build wouldn't
want to do either, since it just built!
This creates a new hack/after-build/ directory and has the scripts which
REQUIRE that the binary already be built. It doesn't test and complain.
It just fails miserably. Users should not be in this directory. Users
should just use hack/verify-* which will just do the build and then call
the "after-build" version. The pre-commit hook or anything which KNOWS
the binaries have been built can use the fast version.
Lubomir I. Ivanov