dbt Cloud enables you to generate documentation for your project and data platform, rendering it as a website. The documentation is only updated with new information after a fully successful job run, ensuring accuracy and relevance. Refer to Documentation for more details.
Set up a documentation job
You can set up documentation for a job in dbt Cloud when you edit your job settings or create a new job. You need to configure the job to generate docs when it runs, then link that job to your project.
To set up a job to generate docs:
In the top left, click Deploy and select Jobs.
Create a new job or select an existing job and click Settings.
Under "Execution Settings," select Generate docs on run.Setting up a job to generate documentation
Click Save. Proceed to configure project documentation so your project generates the documentation when this job runs.
You can also add
dbt docs generate to the list of commands in the job run steps. However, you can expect different outcomes when adding the command to the run steps compared to configuring a job selecting the Generate docs on run checkbox (shown in previous steps).
Review the following options and outcomes:
|Select the Generate docs on run checkbox to automatically generate updated project docs each time your job runs. If that particular step in your job fails, the job can still be successful if all subsequent steps are successful.
|Add as a run step
dbt docs generate to the list of commands in the job run steps, in whatever order you prefer. If that particular step in your job fails, the job will fail and all subsequent steps will be skipped.
To create and schedule documentation-only jobs at the end of your production jobs, add the
dbt compile command in the Commands section.
Configure project documentation
You configure project documentation to generate documentation when the job you set up in the previous section runs. In the project settings, specify the job that generates documentation artifacts for that project. Once you configure this setting, subsequent runs of the job will automatically include a step to generate documentation.
- Click the gear icon in the top right.
- Select Account Settings.
- Navigate to Projects and select the project that needs documentation.
- Click Edit.
- Under Artifacts, select the job that should generate docs when it runs.Configuring project documentation
- Click Save.
To generate documentation in the dbt Cloud IDE, run the
dbt docs generate command in the
Command Bar in the dbt Cloud IDE. This command will generate the Docs for your dbt project as it exists in development in your IDE session.
After generating your documentation, you can click the Book icon above the file tree, to see the latest version of your documentation rendered in a new browser window.
Once you set up a job to generate documentation for your project, you can click Documentation in the top left. Your project's documentation should open. This link will always help you find the most recent version of your project's documentation in dbt Cloud.
These generated docs always show the last fully successful run, which means that if you have any failed tasks, including tests, then you will not see changes to the docs by this run. If you don't see a fully successful run, then you won't see any changes to the documentation.
The dbt Cloud IDE makes it possible to view documentation for your dbt project while your code is still in development. With this workflow, you can inspect and verify what your project's generated documentation will look like before your changes are released to production.Project documentation