Chapter 19 Hosting dbt generated documentation
Imagine you have put blood, sweat and tears into your book, you have said everything you wanted to say, divulged what was secret, and unearthed what was incomprehensible. Except for one thing: you can’t publish it. That would be a disaster, a mockery of your efforts, yet that would be our portion if we had not published the dbt documentation we had created in Chapter 7. After all is said and done, it has to be printed somewhere, and obviously the world wide web is our playground.
There are various ways to publish your dbt generated documentation, such as in Github, Google Cloud and Azure Devops. We would have loved to host our dbt generated documentation in Google cloud as that would have put us in the league of astute developers, but the process and costs were a bit too much. Therefore, we slid back to Github which is easier and totally free.
19.1 Preparations
19.1.1 Creating a gh-pages branch
If hosting dbt documentation were easy, then we would have simply done so from the main branch. However, including taking into account the process of hosting on a more sophisticated platform such as Google Cloud, hosting dbt process seems like a thing for the top-tier tech gurus. It is for this reason we have to create a separate branch, by the name of gh-pages. Github can autodetect the index.html file under this branch automatically compared to a branch by any other name.
To create a new branch run git checkout --orphan gh-pages.
The purpose of the --orphan command is to create a branch from a clean slate; it has no connection to previous commits.
19.1.2 Tracking the target folder
Now run dbt docs generate in order to create the dependency files of your dbt documentation under the target folder. Once the catalog.json is rewritten, we add this branch for tracking but we include the -f keyword to make the files under the target branch trackable. This is because by default they are set to not be tracked right within .gitignore file.
git add -f targetNow let’s commit our target folder contents within our local gh-pages branch.
git commit -m 'hosting dbt docs in github' targetOur terminal did get a huge list of outputs!
19.1.3 Pushing to Github
Next, we only want to take the contents of our target folder and push them into the gh_pages branch. We use the following code: git subtree push --prefix target origin gh-pages. A subtree is like a sub-folder in Github. We use subtree when we want to save certain directories from one repository into another. In our case we only want the contents of the target folder and this we specified using the --prefix keyword. Sometimes, one could have been saving their work at a higher level, such as yours truly. We got the below error when we tried:
You need to run this command from the toplevel of the working tree.In this case, just specify the top-level folder and the target folder, separated with slash(es) like so:
git subtree push --prefix dbt_book/target origin gh-pagesOnce you receive a message that the push operation was successful, you can checkout to the main branch like so: git checkout main or for any other branch for that matter.
19.2 Hosting on Github
If you go to your specific repository on Github, such as dbt_book_codes in our case, you can use the dropdown right under the repository name to move into a different branch.
Once you are within the gh-pages branch, go to the Settings tab, and click on the Pages menu. You will find that Github already auto-detected the index.html file and proceeded to create a hosted webpage going by the name of your repository.
Click on the link to go to your hosted dbt documentation. Access the dbt generated documentation for this course from here.