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. > 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. 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
