fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Mon, Sep 13, 2010 at 01:54:52PM +0100, Garth N. Wells wrote:
>
>
> On 13/09/10 11:08, Kristian Ølgaard wrote:
> >On 13 September 2010 11:51, Anders Logg<logg@xxxxxxxxx>  wrote:
> >>On Mon, Sep 13, 2010 at 11:38:41AM +0200, 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.
> >>>     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.
> >>>   - 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.
> >>>
> >>>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 :)
> >>
> >>I actually think this looks good! :-) Just a couple of questions/comments:
> >>
> >>1. I don't understand how the docstrings in *_post.i files is supposed
> >>to work. How does one write them and how are they extracted?
> >
> >For example in the function_post.i we extend the
> >Function.function_space() function. The docstring for this function
> >could be more detailed, and if we want this we should improve it in
> >the function_post.i file so we don't have to worry about it later.
> >This is what I mean when I wrote that documentation for Python goes
> >where the code is.
> >
> >>2. For FFC, UFC and UFL, we have pretty good manuals already, so would
> >>it be possible to just use that as a starting point, convert to reST
> >>with some extra manual editing? Or should it all be part of the code?
> >
> >Sure, we can write all the introduction and basic design and ideas by
> >hand by translating what we have.
> >Note that stuff like the language chapters etc. in FFC can be omitted
> >since this is part of UFL now.
> >But we might also want to document the interface for FFC/UFL which we
> >can generate automatically.
> >
>
> I agree think that it's good to use we have has a start. FFC
> probably only needs a very minimal user doc (installation + command
> line flags).

+ Python interface

> >>3. Perhaps it would be a good idea to divide the documentation effort
> >>between all developers, like having a system where everyone signs up
> >>to document a specific demo.
> >
> >Yes, definitely. The style guide is relatively detailed and the demos
> >which are already there serve as good references.
> >I also created a template for demos (containing foo/common.txt,
> >foo/cpp/documentation.rst and foo/python/documentation.rst) which can
> >be downloaded from the demos style guide page.
> >
>
> Sounds good. We could have just one blueprint and claim demos on the
> blueprint whiteboard.

I'm sure people will just rush in to claim as many demos as they
can. :-)

Perhaps it would work to do what we did a couple of years back, to set
weekly or bi-weekly deadlines so we all feel a little peer-pressure to
get things done.

--
Anders