Generating documentation site in dbt - Mini Project: Build & Apply

Generating documentation site

📖 Scenario: You are working on a data analytics project using dbt (data build tool). To help your team understand the data models and transformations, you want to create a documentation website that shows the details of your dbt models.

🎯 Goal: Build a dbt project that generates a documentation site using the dbt docs generate command and then serves it locally with dbt docs serve.

📋 What You'll Learn

Create a basic dbt project with a sample model

Configure the project with a profile

Run dbt docs generate to create the documentation site

Run dbt docs serve to view the documentation site locally

💡 Why This Matters

🌍 Real World

Generating documentation sites helps data teams understand data models, lineage, and transformations clearly, improving collaboration and trust in data.

💼 Career

Data analysts, engineers, and scientists use dbt documentation sites to communicate data workflows and ensure data quality in their projects.

1

Create a basic dbt project with a sample model

Create a dbt project folder named my_dbt_project and inside it create a model file models/sample_model.sql with the exact SQL query: select 1 as id, 'example' as name.

dbt

# Create the folder my_dbt_project and inside it create models/sample_model.sql
# Add the SQL query: select 1 as id, 'example' as name

Need a hint?

Make sure the SQL query is exactly select 1 as id, 'example' as name inside the file models/sample_model.sql.

2

Configure the dbt project with a profile

Inside the my_dbt_project folder, create a dbt_project.yml file with the project name my_dbt_project and set the version to 1.0. Also, create a profiles.yml file in the default location with a profile named my_profile that connects to a local database (you can use a placeholder connection).

dbt

-- Add dbt_project.yml and profiles.yml configuration files
# Your code here

Need a hint?

Ensure the dbt_project.yml has the correct project name and profile. The profiles.yml should define a profile named my_profile with connection details.

3

Generate the documentation site using dbt

Run the command dbt docs generate inside the my_dbt_project folder to generate the documentation site files.

dbt

# Run the command dbt docs generate in the terminal inside my_dbt_project
# Your code here

Need a hint?

Use the terminal to run dbt docs generate inside the project folder.

4

Serve and view the documentation site locally

Run the command dbt docs serve inside the my_dbt_project folder to start a local web server. Then open the URL shown in the terminal (usually http://localhost:8080) in your web browser to view the documentation site.

dbt

# Run the command dbt docs serve in the terminal inside my_dbt_project
# Your code here

Need a hint?

Run dbt docs serve and open the URL shown in the terminal to see the documentation site.