On Thu, Oct 21, 2010 at 03:06:49PM +0200, Kristian Ølgaard wrote: > On 21 October 2010 12:28, Anders Logg <[email protected]> wrote: > > Kristian Ølgaard skrev 2010-10-21 11.47: > >> > >> 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. > >>>>> > >>>> > >>>> 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. > > > > I don't have any strong opinion. I think we decided to go with lowercase for > > the FEniCS book chapters. Possibly it was Marie that suggested to do > > lowercase. > > I changed it to lowercase.
Great. > >>>> * The Launchpad pages page is still missing > >>> > >>> The page is there, but the links are missing. > > Fixed, I put all the links to projects listed on > https://launchpad.net/fenics-project and included FEniCS Apps. > Feel free to add more links in case I missed any. Looks good. There are some inconsistencies wrt use of ':' or not. Perhaps it should say (join team before posting) on each line after the mailing lists? > >>>> * 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? > > > > Sounds good. > > I added a picture to the Poisson demo, check it out and see how it > looks. If we're happy I can add the rest and include some appropriate > info in the style guide. Looks good. I wonder if one should move the picture up a bit so it comes at the end of the first paragraph, just before 1.1, so one sees the picture directly without scrolling. That gives a more pleasant first impression I think. > >>> 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. > > > > Sounds good. Make sure to save some time for writing up a summary of the > > status, any loose ends that need fixing etc. > > Of course, it'll just be a slightly modified version of the list > presented in this thread. ok! -- Anders _______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
