fenics team mailing list archive

[Johan Hake <johan.hake@xxxxxxxxx>]

On Monday September 13 2010 09:54:47 Kristian Ølgaard wrote:
> 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.

Ok.

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

Sounds cool! 

But why do you need to wrap

  main.cpp + UFL files

when you have PyDOLFIN ;)

Johan

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