[SciPy-Dev] Problem building html docs

[Matthew Brett]

Hi Ralf,

> Thanks for fixing that Warren. Guess in this case it wasn't enough that the
> patch looks fine and applied cleanly.
>
> By the way, does anyone have a reasonable way with git to get the sphinxext
> stuff from numpy that svn pulls in via externals? This is the reason that
> the docs don't build out of the box in a git repo. And can I add
> /doc/sphinxext to .gitignore?

Sorry - I missed this one - and I am no expert at this, but:

There are a few options for this kind of thing in git - but they are
not as straightforward as svn externals.

The reason for the difficulty is that svn thinks of every directory as
being a separate versioned thing, whereas git thinks in terms of whole
trees.    As a symptom of same, git has one .git subdirectory at the
root level of your project, containing the repository information, and
svn has .svn files in each subdirectory of the tree.

The first is to use a git submodule: http://book.git-scm.com/5_submodules.html

In this case the external thing you want to include is a whole
repository - one repository for the sphinext directory.   It might
look something like:

cd my-numpy-git-repo/doc
git submodule add git://github.com/my-user/numpy-sphinxexts.git sphinext
git commit -am 'Added sphinxext repository as submodule'

This all fine for you, the creator, but anyone cloning your repo has
to remember to do this:

git clone git://github/my-user/my-numpy-git-repo.git
cd my-numpy-git-repo
git submodule init
git submodule update

in order to get the actual files in their tree...  Having said that,
it does have the benefit of keeping track of the particular revision
(commit) of the tree that you are using.

The second option is to use a subtree merge:

http://help.github.com/subtree-merge/
http://www.kernel.org/pub/software/scm/git/docs/howto/using-merge-subtree.html

Again, this requires an entire repository for the thing you want to
include.  I think like this:

git remote add sphinext-remote git://github.com/my-user/numpy-sphinxexts.git
git fetch sphinext-remote
git merge -s ours --no-commit sphinxext-remote/master
git read-tree --prefix=sphinxext-dir -u sphinext-remote/master
git commit -am 'Subtree merge of sphinxext docs'

At this stage you have the entire contents of the sphinxext repository
in your repo, in the 'sphinext-dir' directory, and you have merged the
histories of your repo and the sphinxext repo.  (You can avoid merging
the histories if you want  using the --squash option) - see
http://progit.org/book/ch6-7.html)

Now, whenever someone clones, they get the whole tree, including the
sphinxext docs - and that's the advantage of this approach.

To update the sphinext directory (and your repository history):

git pull -s subtree sphinxext-remote master

See: http://www.kernel.org/pub/software/scm/git/docs/howto/using-merge-subtree.html
for a discussion of subtree merge vs submodules.

There's an example of subtree merge here:
http://github.com/matthew-brett/gitwash-includer

Lastly - the download-it-yourself git subtree command :
http://github.com/apenwarr/git-subtree - does allow you to link to
subdirectories of a repository :
http://psionides.jogger.pl/2010/02/04/sharing-code-between-projects-with-git-subtree/
 .  It looks like it works like this:

In some repository 'containing-project' that has 'sphinxext' as a subdirectory:

cd containing-project
git subtree split --prefix path/to/sphinxext --branch sphinext-only

Now you have a new branch in this repository containing only the files
from the path/to/sphinxext directory, and the history of those files -
only.  You can then use this subtree as the target for your submodule
or subtree merge... - i.e:

git submodule add --branch sphinxext-only
git://github.com/my-user/containing-project.git sphinext

or

git remote add sphinext-remote git://github.com/my-user/containing-project.git
git fetch sphinext-remote
git merge -s ours --no-commit sphinxext-remote/sphinxext-only
git read-tree --prefix=sphinxext-dir -u sphinext-remote/sphinxext-only

I think the combination of the subtree command and the subtree merge
with --squash is the closest to the svn externals routine...

See you,

Matthew