TLDR: If you edit
builtins.go, you might need to
make generate PKG=./docs/... before you PR.
In an effort to ensure our docs generation pipeline always works with the code from which it generates its docs and ensure that that content is kept up to date, I’ve pulled the generated docs tools and their output into the repo in https://github.com/cockroachdb/cockroach/pull/18917. Furthermore, I’ve included re-generation in the CI that verifies that running our various generators does not produce a diff, meaning that a PR that affects the sources for said generation should also include that re-generation as well.
Concretely, if you’re changing sql/parser, you might need to regenerate some docs. A
make generate PKG=./docs/... should do what you need. In some situations, it may do more work than needed though, so if you make
sql/parser changes often, you might find these useful:
- If you only changed builtins, and didn’t touch sql.y, just re-gen the markdown functions/operators docs (takes seconds) and skip the diagrams (minutes, but we’re looking at ways to improve this) with
make generate PKG=./docs/generated/sql.
Employees who edit
sql.yfrequently and will thus regenerate the diagrams often should grab
Railroad.jarfrom the internal Google Drive and place it in
build/to speed up generation (it falls back to a calling a public web service for each diagram if it isn’t present. We’re also looking at ways to improve this).