fenics team mailing list archive

[Johan Hake <johan.hake@xxxxxxxxx>]

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 am also curious of how you think we are going to handle the C++ -> Python 
code in the example section.

>     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