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