On 9/3/10 8:23 PM, Johan Hake wrote: > On Friday September 3 2010 01:20:16 Kristian Ølgaard wrote: > >> On 3 September 2010 08:45, Garth N. Wells <[email protected]> wrote: > >> > On 03/09/10 00:48, Johan Hake wrote: > >> >> Hello! > >> >> > >> >> I wonder how the docstring module is generated. More presisly the > cpp.py > >> >> file in that module. It looks very similare to what was generated > by the > >> >> generate_docstring.py which is still provided in DOLFIN. > >> > >> The idea with the current setup is to write all docstrings in the > >> site-packages/dolfin/docstrings module by hand. > > Ok. > >> Ideally, we should generate it automatically since this will prevent > >> the docs for the Python interface to become out of sync with the C++ > >> implementation. However, there are some problems with this approach. > >> > >> 1) The syntax in the C++ examples needs to be dealt with > >> 2) Classes/functions are renamed/ignored (added?), we will need to > >> look in the *.i files to figure out what to do > >> 3) Overloaded functions are handled using '*args', we need to extract > these > >> 4) Other problems that I'm unaware of > > Yes, these are all nasty one... > >> The current content (in docstrings/dolfin/cpp.py) is just a copy of > >> the old docstrings which was generated by 'generate_docstrings.py' > >> since we didn't have time to write proper docstrings for the entire > >> module. Only the Mesh class is currently documented and we need to add > >> proper documentation for the rest. > >> > >> The generate_docstrings.py uses xml output from Doxygen to write the > >> docstrings.i, this is relatively slow, but once the docstrings module > >> is in place we can generate docstrings.i using this module which > >> should be fast. (Actually, we can already do this now since the module > >> is complete w.r.t. functions/classes). > > Ok. > > Johan > >> Kristian > >> > >> > I couldn't figure it either. It would be good to have some more comments > >> > in the code and some README files explaining what generates what. > >> > > >> > Garth > >> > > >> >> Is the goal to automate the generation of the the docstrings in this > >> >> module, similare to what we have in C++? > >> >> > >> >> This is probably something you allready have discussed, but it has been > >> >> difficult to keep track...
kmail's html e-mail with tiny fonts + poor eyesight = hard to read Harish _______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
