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