Creating a Sphinx Documentation Builder with AWS CodeBuild

AWS CodeBuild is an AWS service that manages software builds and automated testing. It can also be utilized to create a Sphinx documentation builder that, in conjunction with AWS CodePipeline, can become part of a complete system to automatically publish documentation source changes to a live website.

AWS CodeBuild can build your source from files that exist in AWS CodeCommit, Amazon S3, GitHub, or on Bitbucket. In this example, I'll be using AWS CodeCommit.

How documentation is built with Sphinx

Sphinx builds documentation with the command-line sphinx-build program, similarly to this:

sphinx-build -b <builder> <doc-source> <destination>

Many users of Sphinx will run this directly on their local system, but what if I wanted to automate the process so that any changes to my repository will be automatically built and published to my website, and perhaps to even run tests on the source or documentation source files?

What are the build requirements?

To design a remote build, I'll need to first think about what is required to run sphinx-build, as well as any Sphinx extensions that I may want to use in my documentation set.

sphinx-build has the following requirements:

To run in AWS CodeBuild, I'll need to make sure that I can create a build environment that includes all of the necessary bits to run my build. The complete list of build environments provided by AWS CodeBuild is listed in Docker Images Provided by CodeBuild in the CodeBuild User Guide.

Create a docker image

docker pull amazonlinux

Create a CodeBuild build project

Using the AWS CLI:

aws codebuild create-project --name myproject