DbtHow-ToBeginner · 3 min read

How to Use dbt docs generate to Build Project Documentation

Use dbt docs generate to create a static documentation site for your dbt project. This command scans your project files and builds a JSON file with metadata about models, sources, and tests. You can then view the docs with dbt docs serve.

📐

Syntax

The basic syntax for generating documentation in dbt is:

dbt docs generate: Builds the documentation JSON file for your project.
dbt docs serve: Starts a local web server to view the generated docs.

You run these commands in your terminal inside your dbt project directory.

bash

dbt docs generate

💻

Example

This example shows how to generate and view documentation for a dbt project.

First, run dbt docs generate to create the docs JSON file. Then run dbt docs serve to open the docs in your browser.

bash

dbt docs generate

# Output:
# Running with dbt=1.4.0
# Found 5 models, 2 tests, 1 snapshot, 0 analyses, 123 macros, 0 operations, 0 seed files, 0 sources
# Generating documentation...
# Documentation generated successfully!

dbt docs serve

# Output:
# Serving docs at http://localhost:8080
# Press Ctrl+C to stop.

Output

Running with dbt=1.4.0 Found 5 models, 2 tests, 1 snapshot, 0 analyses, 123 macros, 0 operations, 0 seed files, 0 sources Generating documentation... Documentation generated successfully! Serving docs at http://localhost:8080 Press Ctrl+C to stop.

⚠️

Common Pitfalls

Not running inside a dbt project directory: You must run dbt docs generate where your dbt_project.yml file is located.
Forgetting to run dbt run first: Documentation reflects your compiled models, so run your models before generating docs.
Ignoring dependencies: If your models depend on sources or other models, ensure those are defined and built.
Not serving docs: dbt docs generate only creates files; use dbt docs serve to view them.

bash

## Wrong: Running docs generate outside project
$ cd ~
$ dbt docs generate
# ERROR: No dbt project found

## Right: Run inside project
$ cd my_dbt_project
$ dbt docs generate
# Documentation generated successfully!

📊

Quick Reference

Command	Description
dbt docs generate	Builds the documentation JSON file for your project
dbt docs serve	Starts a local server to view the generated docs in a browser
dbt run	Compiles and runs your models; recommended before generating docs
dbt test	Runs tests that can be included in the docs metadata

✅

Key Takeaways

Run dbt docs generate inside your dbt project directory to create docs metadata.

Always run dbt run before generating docs to ensure models are up to date.

Use dbt docs serve to view the generated documentation in your browser.

Documentation includes models, sources, tests, and descriptions from your project files.

Common errors come from running commands outside the project or skipping model runs.