fenics team mailing list archive

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

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.
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

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).

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...
>>
>> Johan
>>
>>
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~fenics
>> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~fenics
>> More help   : https://help.launchpad.net/ListHelp
>
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp
>