fenics team mailing list archive

[Harish Narayanan <harish.mlists@xxxxxxxxx>]

On 9/3/10 8:23 PM, Johan Hake wrote:
> On Friday September 3 2010 01:20:16 Kristian Ølgaard wrote:
> 
>> On 3 September 2010 08:45, Garth N. Wells <gnw20@xxxxxxxxx> wrote:
> 
>> > On 03/09/10 00:48, Johan Hake wrote:
> 
>> >> Hello!
> 
>> >>
> 
>> >> I wonder how the docstring module is generated. More presisly the
> cpp.py
> 
>> >> file in that module. It looks very similare to what was generated
> by the
> 
>> >> generate_docstring.py which is still provided in DOLFIN.
> 
>>
> 
>> The idea with the current setup is to write all docstrings in the
> 
>> site-packages/dolfin/docstrings module by hand.
> 
> Ok.
> 
>> Ideally, we should generate it automatically since this will prevent
> 
>> the docs for the Python interface to become out of sync with the C++
> 
>> implementation. However, there are some problems with this approach.
> 
>>
> 
>> 1) The syntax in the C++ examples needs to be dealt with
> 
>> 2) Classes/functions are renamed/ignored (added?), we will need to
> 
>> look in the *.i files to figure out what to do
> 
>> 3) Overloaded functions are handled using '*args', we need to extract
> these
> 
>> 4) Other problems that I'm unaware of
> 
> Yes, these are all nasty one...
> 
>> The current content (in docstrings/dolfin/cpp.py) is just a copy of
> 
>> the old docstrings which was generated by 'generate_docstrings.py'
> 
>> since we didn't have time to write proper docstrings for the entire
> 
>> module. Only the Mesh class is currently documented and we need to add
> 
>> proper documentation for the rest.
> 
>>
> 
>> The generate_docstrings.py uses xml output from Doxygen to write the
> 
>> docstrings.i, this is relatively slow, but once the docstrings module
> 
>> is in place we can generate docstrings.i using this module which
> 
>> should be fast. (Actually, we can already do this now since the module
> 
>> is complete w.r.t. functions/classes).
> 
> Ok.
> 
> Johan
> 
>> Kristian
> 
>>
> 
>> > I couldn't figure it either. It would be good to have some more comments
> 
>> > in the code and some README files explaining what generates what.
> 
>> >
> 
>> > Garth
> 
>> >
> 
>> >> Is the goal to automate the generation of the the docstrings in this
> 
>> >> module, similare to what we have in C++?
> 
>> >>
> 
>> >> This is probably something you allready have discussed, but it has been
> 
>> >> difficult to keep track...

kmail's html e-mail with tiny fonts + poor eyesight = hard to read

Harish