[Numpy-discussion] clearing after build; Some directories missing in .gitignore?

Ralf Gommers ralf.gommers@googlemail....
Mon Oct 25 09:55:31 CDT 2010

On Mon, Oct 25, 2010 at 7:52 PM, Friedrich Romstedt
<friedrichromstedt@gmail.com> wrote:
> I was tearing my hear out yesterday evening with trying to find out
> and to understand how this directories occur in the build process and
> what role they play:
> build_doc/

This is just where the generated pdf's are copied to, see line 100 of

> doc/source/reference/generated/

The doc build process extracts the docstrings of all functions/objects
in numpy and generates one reST page for each, this is numpy-specific
(the machinery in doc/sphinxext). That's this dir. Those files are
then included in the pdf/html docs in the next step. That's the
standard Sphinx way of doing things.

> The build process of the docs is rather opaque to me, so I don't know
> what to do with them.
> The question is:  Do I really have to clean my working directory
> before doing a new build.  I have problems with this because it seems
> that the cleaning is neither complete nor is .gitignore (see above).
> In pavement.py I read:
> @needs('clean', 'clean_bootstrap')
> def nuke(options):
>    """Remove everything: build dir, installers, bootstrap dirs, etc..."""
>    for d in [options.superpack.builddir, options.installers.releasedir]:
>        if os.path.exists(d):
>            shutil.rmtree(d)
> So :func:`nuke`, as opposed to what I was told before, also removes
> the installers.

I'm pretty sure I said "$paver clean" doesn't do that. "nuke" is not
used anywhere in the release script. Neither is "clean_bootstrap".

>  :func:`clean` removes build/, dist/, numpy.egg-info/,
> and doc/build/.  :func:`clean_bootstrap` is a noop for us.  None of
> them treats the directories listed above.
> I don't know if the generated docs in doc/source/reference/generated
> are included automatically, so that garbage from previous builds could
> make it into later doc builds?

That shouldn't be possible. But good point, one of the improvements to
make to the paver and release scripts is making sure that the docs get
built only once instead of once per OS X dmg.
> Further, I don't know what may dangle around what I simply don't see
> because it's hidden by .gitignore.  E.g. what's about doc/cdoc/build?

Not 100% sure, but don't think that is used yet.

> doc/numpy.scipy.org/_build?  I don't have this dirs, though.

This is the new numpy website, not relevant for building user and
reference guides.

> I will, for now, just remove the directories listed above and hope
> that :func:`clean` does the rest to the extent needed, but I really
> have the impressions that the binary build system is rather "organic"
> and needs a general overhaul.

For sure there is room for improvement in documenting and cleaning a
bit (esp. the global vars in pavement.py), but overall I think it's
pretty clear. Except maybe for the doc build, but that's the nature of
the beast.


> A bit lost,
> Friedrich
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion@scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion

More information about the NumPy-Discussion mailing list