fenics team mailing list archive

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

On 13 September 2010 17:33, Johan Hake <johan.hake@xxxxxxxxx> wrote:
> On Monday September 13 2010 02:38:41 Kristian Ølgaard wrote:
>> The FEniCS documentation is almost complete. Below is a short list of
>> what remains to be done and a sketch of how we will handle the
>> programmer's reference part the design of which has been debated
>> intensely over the past weeks.
>>
>> * Tutorial
>>   - Hans Petter is working on translating his TEX source to reST for
>> the Python version.
>>   - Figure out if there are some common parts of the text which can be
>> shared with the C++ version.
>>   - Fill in blanks for C++ version.
>>   - This work can be completed independently of the other parts since
>> we can already use references like
>>
>>     :py:class:`Foo` :cpp:class:`Foo`.
>>
>> * Demos
>>   - Framework is in place.
>>   - Add documentation for all demos in the dolfin/demo/undocumented
>> directory. - Again, this work can be completed independently of the other
>> parts since we can already use references like
>>
>>     :py:class:`Foo` :cpp:class:`Foo`.
>>
>> * Style guides
>>   - Once the programmer's reference is complete we need to update this
>> section in the style guides accordingly.
>>
>> * Programmer's reference
>>   - Add module to extract docstrings from *.h files to DOLFIN.
>>     Anders' script is already working but we need to define the
>> intermediate representation (IR).
>>   - Make write_cpp_documentation() work with the intermediate
>> representation. The C++ version of programmer's reference is more or less
>> complete.
>>   - From the IR generate the docstrings.i file in DOLFIN.
>
> I guess we are going to include the type and number of arguments of each
> function/method in the IR. It would be usefull to generate a dictionary that
> map these to Python types. Most should be possible to automate, like removal
> of const, pointers and references. But for the types we include our own
> typemaps we probably need to go in and edit the Python type manually.

I think we just need a handwritten map, I don't think there will be that many.
Let's start writing the script and see how much we can automate.

> I am also curious of how you think we are going to handle the C++ -> Python
> code in the example section.

We might have to settle for a dictionary as a first implementation
although I have thought about writing a Python <---> C++ converter for
DOLFIN to make it easier to debug demo.py files and wrap main.cpp +
UFL files in a scripting environment.

Kristian

>>     We need to handle the example code (C++ --> Python syntax) and the
>> native arguments like double* --> numpy.array.
>>   - Add complete docstrings to the extended methods in *_post.i files
>> and the Python layer in dolfin/site-packages/dolfin,
>>     the idea being that documentation should be located where the code is.
>
> Sounds good!
>
>>   - In fenics-doc we will import the dolfin module and use it to
>> generate the reST files and autodoc from Sphinx to handle the
>> docstrings.
>>     To get a meaningful module structure we have to be more careful
>> when including classes/functions in the __init__.py file in dolfin.
>>     Classes from dolfin.cpp which are not imported in other modules
>> (like dolfin.mesh, dolfin.la etc.) will not be included in the
>>     documentation.
>
> Sounds good!
>
> Johan
>
>> The above should increase the chances of the source code in DOLFIN and
>> the documentation being in sync as well as reduce the work involved
>> writing documentation for both interfaces. We will also have the same
>> documentation available in >>> help(dolfin) as we have in the online
>> documentation.
>>
>> Finally, the appendices for FFC, UFC and UFL needs to be written. I
>> think we can handle FFC and UFL by improving the docstrings in the
>> modules (this will also help developers while writing the code) and
>> use autodoc from Sphinx, maybe with some autogenerated reST files.
>> The documentation for UFC might have to be written manually, but since
>> the idea is that the interface should not change too rapidly I think
>> this is an OK solution.
>>
>> There's your summary Anders, now let's hear your completely different
>> approach to documenting the FEniCS project :)
>>
>> Kristian
>>
>> _______________________________________________
>> Mailing list: https://launchpad.net/~fenics
>> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~fenics
>> More help   : https://help.launchpad.net/ListHelp
>