workflow for publishing develop html docs as gh-pages branch

[GoogleCodeExporter]

Once the repository has been moved to GitHub (Issue #223), we need to devise a workflow that allows us to publish the html docs as a gh-pages branch in the repository.

It is important that there's a reasonably up-to-date documentation for the develop branch online because many people are using it for actual work. It also allows us to easily proof-read the docs. Should we ever get the docs to work on Read The Docs (Issue #183) then this point will become less important (although still desirable).

Original issue reported on code.google.com by orbeckst on 28 Mar 2015 at 1:42

• Blocked on: #223

[dotsdl]

The Docs currently links to our documentation hosted by PyPI. Do we intend to host doc versions as part of our gh-pages site still?

[orbeckst]

The Docs link is the documentation for the latest released version. We also want the online docs for the current development branch available. ReadTheDocs #183 would have been nice for that because it would have automatically regenerated the docs. But given that ReadTheDocs is unlikely to ever work we have to come up with something else.

Using GitHub pages to host the docs seemed like a sensible idea so we would need a feasible protocol to

1. generate the docs on the develop branch with Sphinx (cd doc/sphinx && make html)
2. insert the doc/html directory into the top level of the gh-pages branch (that's the sticky/messy part)
3. push gh-pages so that the docs appear as http://mdanalysis.github.io/mdanalysis (or if we can do some redirection magic, maybe as docs.mdanalysis.org or www.mdanalysis.org/docs)

In the past I used a pretty horrific protocol for this, as described under Preparing Online Docs of GromacsWrapper. Someone should be able to come up with something better or to at least automate it in a sensible fashion.

[orbeckst]

I just created the gh-pages branch, added the obligatory .nojekyll file (to keep all the important sphinx underscore directories...) and pushed: Development branch docs are online at http://www.mdanalysis.org/mdanalysis/package/doc/html/ — it's not the nicest path name but it might do and it's as easy as merging the current develop into gh-pages and pushing. (GitHub does not allow any redirects or URL rewriting so I can't think of a way to automatically make this nice unless we can use the Jekyll redirect-from plugin). So right now the procedure for publishing the online docs for the development branch is (very verbosely — feel free to add the concise version)

git checkout develop
git pull
git checkout gh-pages
git pull origin gh-pages
git merge develop
git push origin gh-pages

and check that http://www.mdanalysis.org/mdanalysis/package/doc/html/ looks ok. Once we're happy with the procedure, we should open a wiki page for it. I am closing the issue for now; it can be re-opened if we want to change things or problems appear.