dolfin team mailing list archive

[Johan Hake <johan.hake@xxxxxxxxx>]

On Friday May 27 2011 12:10:39 Anders Logg wrote:
> On Fri, May 27, 2011 at 09:05:10PM +0200, Kristian Ølgaard wrote:
> > On 27 May 2011 20:52, Anders Logg <logg@xxxxxxxxx> wrote:
> > > On Fri, May 27, 2011 at 08:40:44PM +0200, Marie E. Rognes wrote:
> > >> On 05/27/2011 08:27 PM, Johan Hake wrote:
> > >> >On Friday May 27 2011 11:21:33 Kristian Ølgaard wrote:
> > >> >>On 27 May 2011 20:09, Marie E. Rognes<meg@xxxxxxxxx>  wrote:
> > >> >>>On 05/27/2011 08:05 PM, Kristian Ølgaard wrote:
> > >> >>>>On 27 May 2011 18:55, Marie E. Rognes<meg@xxxxxxxxx>   wrote:
> > >> >>>>>On 05/27/2011 06:21 PM, Johan Hake wrote:
> > >> >>>>>>Nice!
> > >> >>>>>>
> > >> >>>>>>Will any of the below targets superseed the generatation of
> > >> >>>>>>docstrings in
> > >> >>>>>>the
> > >> >>>>>>
> > >> >>>>>>   dolfin/swig/generate.py
> > >> >>>>>>
> > >> >>>>>>script?
> > >> >>>>>
> > >> >>>>>Hahaha. I had no idea that dolfin/swig/generate.py generates
> > >> >>>>>docstrings, so
> > >> >>>>>probably yes! or no.
> > >> >>>>>
> > >> >>>>>Why don't you give me a quick run-down of what the idea with the
> > >> >>>>>generation
> > >> >>>>>of docstrings is, and then I'll fix.
> > >> >>>>
> > >> >>>>The generate.py script creates the docstrings which is included by
> > >> >>>>Swig when creating the cpp.py module.
> > >> >>>>These docstrings are then extracted, using autodoc, in the .rst
> > >> >>>>files that we're generating from the dolfin module (what you have
> > >> >>>>been working on lately).
> > >> >>>>
> > >> >>>:-)
> > >> >>>
> > >> >>>Bottomline, the autodoc operates on the "installed" module, and the
> > >> >>>generated docstrings are thus included.
> > >> >>
> > >> >>Yes, and we need to run generate.py first to get the docstrings in
> > >> >>cpp.py correct.
> > >> >>Because once created, we can't modify it (at runtime) unless we do a
> > >> >>search&  replace but then we might as well run generate.py.
> > >> >
> > >> >So it sounds like we should still run generate.py seperately from
> > >> >what you have been adding.
> > >> >
> > >> >Would it be an idea to add the running of generate.py as a build
> > >> >target? Then everything can be managed from the build directory.
> > >> 
> > >> Completely independently of the documentation: Yes, that would be
> > >> great.
> > > 
> > > Once the smoke clears, we really need to write down all the steps to
> > > generate the documentation. It's getting complicated... :-)
> > 
> > I think that moving the docs to the projects is a step in the right
> > direction.
> > 
> > > generate.py should probably be moved and located together with the
> > > other scripts.
> > 
> > Maybe, it's really a part of the Swig step, but as I recall it it's
> > expensive to run so we probably don't want to run it every time the
> > Python module is created since that is already expensive.
> 
> Isn't it so that the Python module is only generated when necessary
> (when the header files have changed). Then it would be natural to
> always generated the docstrings at the same time since they may be
> wrong. Furthermore, I think the extraction of docstrings is a
> relatively small cost compared to compiling the gigantic file
> generated by SWIG.

I did not envision that we should regenerate the docstrings each time we build 
the swig interface. For people rebuilding the swig interface just when someone 
(TM) else has changed it that might not be such a penalty. But I would not 
appreciate such an overhead to the allready time consumeing proces...

That said, putting the generate.py script into utils, rename it to  
generate_swig_interface.py and make a build target for it to run would make 
sense.

Johan