On 13 September 2010 14:54, Garth N. Wells <[email protected]> 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). > > >>> 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've added the list to: https://blueprints.launchpad.net/fenics-doc/+spec/demos Kristian > Garth > >>> 4. I made a bunch of notes when we worked with the docs a couple of >>> weeks back. I have them on a piece of paper at the office. Some of >>> these you have already fixed but I'll check what else I thought of. >> >> OK, sounds good. >> >> Kristian >> >>> -- >>> Anders >>> >> >> _______________________________________________ >> Mailing list: https://launchpad.net/~fenics >> Post to : [email protected] >> Unsubscribe : https://launchpad.net/~fenics >> More help : https://help.launchpad.net/ListHelp > > _______________________________________________ > Mailing list: https://launchpad.net/~fenics > Post to : [email protected] > Unsubscribe : https://launchpad.net/~fenics > More help : https://help.launchpad.net/ListHelp > _______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
