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.

Practice

1. What does the command dbt docs generate do in a dbt project?

easy

A. It deletes old documentation files from your project folder.

B. It runs all your data transformations and loads data into the warehouse.

C. It starts a local server to view your documentation site.

D. It creates a website with documentation for your data models and sources.

Solution

1. Step 1: Understand the purpose of dbt docs generate

   This command builds the documentation files for your dbt project, including models and sources.

2. Step 2: Differentiate from other commands

   Unlike dbt run which runs transformations or dbt docs serve which serves the docs, dbt docs generate only creates the documentation files.

3. Final Answer:

   It creates a website with documentation for your data models and sources. -> Option D

4. Quick Check:

   dbt docs generate builds docs [OK]

Hint: Generate docs builds files; serve shows them [OK]

Common Mistakes:

• Confusing generate with run or serve commands
• Thinking it runs data transformations
• Assuming it deletes files

2. Which of the following is the correct command to view the generated documentation site locally?

easy

A. dbt docs view

B. dbt docs generate

C. dbt docs serve

D. dbt docs start

Solution

1. Step 1: Identify the command to serve docs

   The command dbt docs serve starts a local web server to view the generated documentation site.

2. Step 2: Confirm other options are incorrect

   dbt docs generate only creates docs files, while dbt docs view and dbt docs start are not valid dbt commands.

3. Final Answer:

   dbt docs serve -> Option C

4. Quick Check:

   Serve command shows docs locally [OK]

Hint: Serve command launches docs site locally [OK]

Common Mistakes:

• Using generate instead of serve to view docs
• Typing invalid commands like docs view or docs start
• Confusing generate and serve commands

3. Given the following commands run in order:

dbt docs generate
dbt docs serve

What will happen after running these commands?

medium

A. The documentation site is created and then opened in a local web browser.

B. The data models are rebuilt and the docs site is deleted.

C. Only the documentation files are created but not viewable.

D. An error occurs because docs serve must run before docs generate.

Solution

1. Step 1: Understand the effect of dbt docs generate

   This command creates the documentation files needed for the docs site.

2. Step 2: Understand the effect of dbt docs serve

   This command starts a local server and opens the docs site in a browser using the generated files.

3. Final Answer:

   The documentation site is created and then opened in a local web browser. -> Option A

4. Quick Check:

   Generate then serve shows docs [OK]

Hint: Generate first, then serve to view docs [OK]

Common Mistakes:

• Thinking docs serve deletes docs
• Believing docs serve must run before generate
• Assuming docs generate runs data models

4. You ran dbt docs serve but the documentation site does not open in your browser. What is the most likely cause?

medium

A. You need to run dbt run before serving docs.

B. You forgot to run dbt docs generate first to create the docs files.

C. The dbt docs serve command requires an internet connection.

D. Your dbt project has no models defined.

Solution

1. Step 1: Check prerequisites for serving docs

   The dbt docs serve command needs the documentation files created by dbt docs generate.

2. Step 2: Identify missing step

   If dbt docs generate was not run, the docs files don't exist, so the site won't open.

3. Final Answer:

   You forgot to run dbt docs generate first to create the docs files. -> Option B

4. Quick Check:

   Generate docs before serving [OK]

Hint: Always generate docs before serving [OK]

Common Mistakes:

• Assuming docs serve works without generated files
• Thinking internet is required for docs serve
• Believing dbt run affects docs serving

5. You want to share your dbt project's documentation site with your team without running dbt docs serve locally. Which approach is best?

hard

A. Generate the docs with dbt docs generate and upload the generated files to a web server.

B. Run dbt docs serve and share your local IP address with the team.

C. Send your team the dbt_project.yml file to generate docs themselves.

D. Use dbt run to automatically publish docs online.

Solution

1. Step 1: Understand how docs are generated and shared

   dbt docs generate creates static documentation files that can be hosted anywhere.

2. Step 2: Identify best way to share without local serving

   Uploading generated docs to a web server allows team members to access the docs anytime without running commands locally.

3. Final Answer:

   Generate the docs with dbt docs generate and upload the generated files to a web server. -> Option A

4. Quick Check:

   Upload generated docs for team access [OK]

Hint: Upload generated docs files to share site [OK]

Common Mistakes:

• Sharing local IP which may not be accessible
• Sending config files instead of docs
• Thinking dbt run publishes docs automatically