You follow a Docs as Code approach. You are writing documentation with the same tools that are used to code. Even the docs are already hosted on GitHub, and the revision process happens through pull requests.
Nevertheless, every time you review new contributions, you download and build the documentation locally to make sure that images and markup did not break the page. If this is the case, let's see how to automate the build of your docs PR using Netlify CI!
Note: I'll be using Sphinx as the documentation builder, but you can follow the same approach with any other framework.
Create a Netlify account
If you haven't heard about Netlify before, this service automatically builds and publishes a website for every new commit in a Git repository.
Netlify works similar to GitHub Pages. The main difference is that Netlify also deploys a website for every pull request, and not only when the
gh-pages branch is updated.
Warning: Netlify is a paid service but they also offer a starter plan for experimentation that comes with monthly credits for free.
To create a new account, open app.netlify.com/signup, and complete the registration steps, preferably with your GitHub account.
Connect Netlify to the docs repository
Now that you have created an account, let's link Netlify and the docs repository.
1. From the Dashboard, click on the "New Site from Git" button in the upper right-hand corner.
2. Under "Continuous Deployment", select GitHub and authorize your account. You might need to grant permission to an organization if the repository is not under your account.
3. Select the docs repository you want to automate the previews.
4. Go to "Build Settings", write the command you use to build the docs and the name of the directory where the output is generated.
In the case of my particular Sphinx project, the build instruction is
make html and the folder that contains the generated HTML is
5. Click on the "Deploy Site" button.
To check that the integration is working, you will need to submit a new pull request or wait until you receive a new one.
Review a pull request
Within the pull requests view, you should see a new Netlify CI badge labeled as
Once the build passes (or fails), click on the "Details" link. If everything goes well, you should see the preview of the pull requests.
Putting all together
It's normal if the build does not pass the first time. Configuring a CI system takes some time in the beginning, but in exchange, you won't cope with repetitive tasks anymore. Check on Netlify why the build has failed, apply the fix, and try to build again!
I sincerely hope that the automation of pull requests previews ensures that your docs always look perfect and saves you and your team some precious time.
Do you want to automate your docs to increase your team's productivity? Shoot me a message, and let's figure out how to enhance your documentation process together.