[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [IMP-dev] [IMP-commits] r1155 - in trunk: doc doc/doxygen kernel kernel/doc patches tools




On Jan 12, 2009, at 7:21 AM, Ben Webb wrote:

Daniel Russel wrote:
"scons doc" still tries to build all of the swig things (and doesn't
actually build the documentation), despite being the obvious thing for a
user to try if they want to build documentation. While the examples
happen to be in the doc hierarchy, running them is part of test, and so
they shouldn't be run when the user wants to build docs.

"scons doc" will ensure that all targets in the doc directory are up to date. Since examples is a subdirectory of the doc directory, there is no
way to avoid this. The only way is to move the examples to their own
top-level directory, but that is a little confusing since when they are
installed they go into a subdirectory of doc. That is perhaps the best
solution though.
Or to make an alias for doc which masks the directory. It worked just fine ("scons doc" built the doc only and "scons test" ran examples) in the patch I gave you.

Semantically, the doc dir is completely up to date without actually running the examples (since running the examples doesn't produce anything meaningful). It is just that your code to run the examples happens to be in doc/examples. But there is no reason to trouble users with this implementation detail (which can make building docs take a really long time).

We also really need to move the produced documentation to some place more obvious (like "doc/html" where I had it).

I'm not sure what you mean by "doesn't actually build the
documentation". It builds the documentation just fine for me. What
problem do you run into?
I can't reproduce it now. Perhaps it was something with the scons data files being messed up in the transition from my version to yours.