On Monday September 13 2010 09:54:47 Kristian Ølgaard wrote: > On 13 September 2010 17:33, Johan Hake <[email protected]> wrote: > > On Monday September 13 2010 02:38:41 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. > > > > I guess we are going to include the type and number of arguments of each > > function/method in the IR. It would be usefull to generate a dictionary > > that map these to Python types. Most should be possible to automate, > > like removal of const, pointers and references. But for the types we > > include our own typemaps we probably need to go in and edit the Python > > type manually. > > I think we just need a handwritten map, I don't think there will be that > many. Let's start writing the script and see how much we can automate.
Ok. > > I am also curious of how you think we are going to handle the C++ -> > > Python code in the example section. > > We might have to settle for a dictionary as a first implementation > although I have thought about writing a Python <---> C++ converter for > DOLFIN to make it easier to debug demo.py files and wrap main.cpp + > UFL files in a scripting environment. Sounds cool! But why do you need to wrap main.cpp + UFL files when you have PyDOLFIN ;) Johan > Kristian > > >> 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. > > > > Sounds good! > > > >> - 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. > > > > Sounds good! > > > > Johan > > > >> 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 :) > >> > >> Kristian > >> > >> _______________________________________________ > >> 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
