dolfin team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

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.

--
Anders