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