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 pavement.py

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. Cheers, Ralf

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