[Numpy-discussion] datarray repositories have diverged

Joshua Holbrook josh.holbrook@gmail....
Sat Oct 9 04:48:01 CDT 2010


On Fri, Oct 8, 2010 at 9:05 PM, Fernando Perez <fperez.net@gmail.com> wrote:
> Hi,
>
> On Fri, Oct 8, 2010 at 8:20 PM, Joshua Holbrook <josh.holbrook@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
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion@scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion
>

I have to admit to not being a big fan of the oddball 'gh-pages'
branch either. I wish there was a better way of doing gh-pages
documentation than having to put it in a separate repo, but it's
better than two branches with *completely different* files fighting
polluting each other (Or worse, dumping build files into /tmp,
checking out gh-pages, copying from /tmp back in, etc., etc., which is
what I found myself doing).  Plus, you could always make the docs a
submodule, if that's how you roll (might be a good idea, actually).

Now, if I could just find a documentation tool that I like. I'm not
huge on Sphinx, tbh, and RST doesn't really light my fire.

Anyways--I feel enlightened! Thanks!

--Josh


More information about the NumPy-Discussion mailing list