[Numpy-discussion] datarray repositories have diverged
Sat Oct 9 04:48:01 CDT 2010
On Fri, Oct 8, 2010 at 9:05 PM, Fernando Perez <firstname.lastname@example.org> wrote:
> On Fri, Oct 8, 2010 at 8:20 PM, Joshua Holbrook <email@example.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:
> 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:
> and it produces zero pollution of the main repo with gh-pages junk.
> NumPy-Discussion mailing list
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!
More information about the NumPy-Discussion