fenics team mailing list archive

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

On 3 September 2010 10:31, Garth N. Wells <gnw20@xxxxxxxxx> wrote:
>
>
> On 03/09/10 09:20, 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.
>> 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'
>
> Does this mean that I should be able to run 'generate_docstrings.py'? I get
> the error

In the file generate.py at the bottom, you need to switch on the lines:

from generate_docstrings import DocstringGenerator

g = DocstringGenerator(header_files = docstring_headers,
swig_directory = ".", docstring_file_base = "")
g.generate_doxygen_documentation()
g.generate_interface_file_from_index()
g.clean()

and then comment the remainder of the lines which creates docstrings.i
from the docstrings module.

Then run 'python generate.py' to generate docstrings.i from xml files.

Kristian

> Traceback (most recent call last):
>  File "generate_docstrings.py", line 458, in <module>
>    g.generate_interface_file_from_index()
>  File "generate_docstrings.py", line 432, in
> generate_interface_file_from_index
>    dfile = open(self._docstring_file,"w")
> IOError: [Errno 2] No such file or directory:
> '/home/garth/code/fenics/dolfin.d/dolfin-all/dolfin/swig/swig/swig_docstrings.i'
>
>
> when I run it.
>
> Garth
>
>> 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
>>>
>