On 03/09/10 15:51, Johan Hake wrote:
On Friday September 3 2010 01:31:38 Garth N. Wells wrote: > On 03/09/10 09:20, 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. > > 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' > > Does this mean that I should be able to run 'generate_docstrings.py'? I > get the error > > Traceback (most recent call last): > File "generate_docstrings.py", line 458, in <module> > g.generate_interface_file_from_index() > File "generate_docstrings.py", line 432, in > generate_interface_file_from_index > dfile = open(self._docstring_file,"w") > IOError: [Errno 2] No such file or directory: > '/home/garth/code/fenics/dolfin.d/dolfin-all/dolfin/swig/swig/swig_docstrin > gs.i' > > > when I run it. The error come because running the script from the konsole assume a predefined directory structure. By importing DocstringGenerator you can set these direcories, which we do in generate.py, as Kristian writes.
This should all be in a README file somewhere, or commented in the code. Garth
Johan > Garth > > > 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
