Compiling a Sphinx document on Wercker

Posted: , Modified:   sphinx wercker
Copyright certificate by blockai

After import your repository, application page looks like this. Move on the workflow tab.

Fig. 1

Open configuration of the build pipeline.

Fig. 2

In the configuration of the build pipeline, scroll down to Permission level.

Fig. 3

And choose execute pipeline in order to prevent someone starting pipeline and see detailed logs. Also set gh-pages to Ignore branches so that Wercker will not start building documents after pushing to gh-pages branch.

Fig. 4

Then, back to the workflow tab and add a new pipeline.

Fig. 5

Now, we name the new pipeline deploy, and hook type should be default to be chained to the build pipeline.

Fig. 6

In order to push built documents to GitHub, this pipeline should know an access token of GitHub. Add such key with name GIT_TOKEN and protected option in the environment variables section of deploy pipeline.

Fig. 7

The token can be obtained in https://github.com/settings/tokens. If your repository is public, you only need a token with public_repo scope. Otherwise, you may need a token with repo scope.

Fig. 8

After adding GIT_TOKEN, check Permission level is Execute pipelines.

Fig. 9

Next, make a workflow connecting the deploy pipeline to the build one in Workflow tab. Make sure this workflow only runs on master branch.

Fig. 10

In the end, the workflow looks like the followings.

Fig. 11

Next, you need to add wercker.yml in your branch root. You use Sphinx to build documents of which sources are in docs. wercker.yml may be there.

box: jkawamoto/ghp-box
build:
  steps:
    - jkawamoto/sphinx:
        basedir: docs
        packages: sphinx_rtd_theme
deploy:
  steps:
    - jkawamoto/ghp-import:
        token: $GIT_TOKEN
        basedir: docs/build/html

It also specifies to install sphinx_rtd_theme. Make sure after running make html in doc folder, your documents are in docs/build/html. Otherwise, edit basedir in the last line.

References