gh-pages-release branch needs to be existing prior to docs build?

[jgosmann]

It seems that the gh-pages-release branch needs to be created prior to building the docs? Not entirely sure, though, because it seems like the docs were built anyways, but then the built was reported as failed after that.

[drasmuss]

Yes that is correct (that the gh-pages-release branch needs to be manually created).

[jgosmann]

Should it be empty or branch off of master?

[drasmuss]

It should be empty, and then docs from future releases will be added to that branch. Or, if you wanted to initialize it with some past releases, you can manually generate those past release builds like

sphinx-build -b html docs <docs-dir>/<release-tag>

where <release-tag> is the tag for the release whose documentation you're building, e.g. v0.5.0, and <docs-dir> is what will become the base of gh-pages-release. So you should end up with a directory structure like

<docs-dir>
    /v0.4.0
    /v0.5.0
    /v0.6.0