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