[Numpy-discussion] datarray repositories have diverged

[Fernando Perez]

Hi,

On Fri, Oct 8, 2010 at 8:20 PM, Joshua Holbrook <josh.holbrook at gmail.com> wrote:
>
> What mechanism are you using for gh-pages, if I may ask? I would be
> interested in this for future projects.

the default github implementation relies on a 'hidden' branch called
gh-pages that lives in the main repo.  I think this is  a *horrible*
idea because it requires polluting the real repo with builds of the
documentation that are auto-generated.  Furthermore, I like keeping
live versions of the docs of a project for each release, and the
gh-pages branch is thus likely to get rather large.

Instead, I made a *separate* repo to be used only for gh-pages:

http://github.com/fperez/datarray-doc

The only purpose of this repo is to provide the docs for datarray.
The datarray doc/Makefile has a gh-pages target that updates the html
build and then runs the gh-pages script.  That's a simple code I wrote
to populate the -doc repo with a ready-to-push build of the docs.

On each release, we simply do

make gh-pages

and follow the instructions it prints, which amount to:

1. cd ../datarray-doc
2. check the docs look good
3. git push

That pushes the doc build.

This workflow is extremely simple, gives us builds of the
documentation for all releases nicely indexed with a stable url:

http://fperez.github.com/datarray-doc/

and it produces zero pollution of the main repo with gh-pages junk.

Cheers,

f