PSA: Generated SQL Docs

TLDR: If you edit sql.y or 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.y frequently and will thus regenerate the diagrams often should grab Railroad.jar from 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).