On 21 October 2010 11:35, Kristian Ølgaard <[email protected]> wrote: > On 21 October 2010 11:01, Anders Logg <[email protected]> wrote: >> Anders Logg skrev 2010-09-13 11.51: >>> >>> 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? >>> >>> 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? >>> >>> 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. >>> >>> 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. >>> >>> -- >>> Anders >> >> Hi Kristian, >> >> I found the notes I made. Most issues have already been fixed, but here are >> some more that need fixing: >> >> * Consistent capitalization of headings >> >> There seems to be a mix now for different pages. This needs to be looked at, >> fixed and also be noted in the style guide. > > OK.
Do we want: Getting Help, FEniCS Python Demos, FEniCS Programmer’s Reference etc. or Getting help, FEniCS Python demos, FEniCS programmer's reference? I'm indifferent, and since the distribution between styles is 50-50 the work is the same changing one to the other. Kristian >> * The Launchpad pages page is still missing > > The page is there, but the links are missing. > >> * Pictures on demo pages >> >> It would be nice to add a picture to each demo documentation page. The >> picture can just be whatever comes out of Viper when running the demo. >> (Store a picture by pressing 'i' in the plot window.) > > OK, perhaps we can include it in the common section? > >> Do you still have any hours left on your contract? I know the contract has >> run out but I think you said you had some hours left to work. > > I have approx. 30 hours. I think it should be enough time to implement > the above, fix the handling of arguments for the programmer's > reference (Python version) and update the style guide to match the new > approach to generating the programmer's reference. Then all bases > should be covered and we just need to fill in the blanks. > > 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
