dolfin team mailing list archive

[Kristian Ølgaard <k.b.oelgaard@xxxxxxxxx>]

On 27 May 2011 21:10, Anders Logg <logg@xxxxxxxxx> 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.

That makes sense, if the interface changes the docs could/should also change.
So it should be run as part of the Swig step?

Kristian

> --
> Anders
>