Generating documentation site in dbt - Step-by-Step Execution

Concept Flow - Generating documentation site

Run dbt docs generate

↓

dbt parses project files

↓

dbt builds documentation JSON

↓

Documentation files created in target/ directory

↓

Run dbt docs serve

↓

Local web server starts

↓

Open browser to view docs site

This flow shows how dbt generates and serves a documentation website from your project files.

Execution Sample

dbt

dbt docs generate
# Generates docs JSON files

dbt docs serve
# Starts local server to view docs

These commands generate the documentation files and then serve them locally for viewing.

Execution Table

Step	Action	Process	Result
1	Run 'dbt docs generate'	dbt reads models, sources, tests, and descriptions	Creates docs JSON files in target/ directory
2	Files created	Documentation JSON files ready	Files stored in target/catalog.json and target/index.html
3	Run 'dbt docs serve'	Starts local web server on default port 8080	Server running, ready to serve docs
4	Open browser at localhost:8080	Browser requests docs site	Documentation site loads showing project docs
5	Exit	Stop server	Docs site no longer accessible locally

💡 Server stops when user interrupts; docs files remain for future use

Variable Tracker

Variable	Start	After Step 1	After Step 3	Final
docs_files	None	Created in target/	Available for serving	Remain on disk
server_status	Stopped	Stopped	Running	Stopped after exit

Key Moments - 2 Insights

Why do we need to run 'dbt docs generate' before 'dbt docs serve'?

Because 'dbt docs generate' creates the documentation files needed by the server. Without these files, 'dbt docs serve' has nothing to show. See execution_table step 1 and 3.

What happens if you stop the server after running 'dbt docs serve'?

The documentation site will no longer be accessible locally, but the generated docs files remain on disk for future use. See execution_table step 5.

Visual Quiz - 3 Questions

Look at the execution table, what is created after running 'dbt docs generate'?

A Documentation JSON files in target/ directory

B Local web server

C Browser window

D Database tables

💡 Hint

Check execution_table row 1 under Result column

At which step does the local web server start running?

A Step 1

B Step 3

C Step 4

D Step 5

💡 Hint

Look at execution_table Step 3 under Process and Result

If you skip 'dbt docs generate' and run only 'dbt docs serve', what will happen?

A dbt will generate docs automatically

B Docs site will load normally

C Error because docs files are missing

D Server will start but no docs will show

💡 Hint

Refer to key_moments about the need to generate docs before serving

Concept Snapshot

dbt docs generate: Creates documentation JSON files from your project.
dbt docs serve: Starts a local web server to view the docs site.
Docs files are stored in target/ directory.
Always generate docs before serving.
Stop server to end local docs access.

Full Transcript

To generate a documentation site in dbt, first run 'dbt docs generate'. This command reads your project files like models and sources, then creates JSON documentation files in the target/ directory. Next, run 'dbt docs serve' to start a local web server, usually on port 8080. Open your browser to localhost:8080 to view the documentation site. The server runs until you stop it. The docs files remain on disk for future use. Remember, you must generate docs before serving, or the site will not load.