Defer state in docs generate

[NiallRees]

Describe the feature

Forgive me if this already exists, but I can't see any mention of docs generate in the defer state docs.

I've run into a bit of a hitch building documentation in a CI build where I'm using deferred state. We're using the get_column_values macro in a model which works fine for the run and test steps and defers to the production table, but when it comes to docs generate I get a relation does not exist error. What's the expected behaviour here? Does dbt docs generate not support deferred state?

I'm using the DBT_DEFER_TO_STATE and DBT_ARTIFACT_STATE_PATH env vars.

[jtcohen6]

Hey @NiallRees, --defer isn't supported for docs generate today (only for run and test). It sounds like the issue you're running into is the compile step baked into the docs generate task by default.

Eventually, we'll want to add support for --defer to compile and docs generate. We've been cautious with the rollout because we know that --defer is a tricky, highly specialized feature that could have better UX (and a better name) someday (#2968).

In the meantime, I'd recommend working around it by passing the optional flag to skip execute-time compilation when generating docs—i.e., do not write a new manifest.json with updated compiled_sql, only build and write catalog.json + index.html:

$ dbt docs generate --no-compile

Your docs should still be viewable just fine, since you'll have a manifest.json from the previous run and test steps.

Does that sound like a reasonable approach?

[NiallRees]

You're a wizard @jtcohen6 thank you as always