On 3 September 2010 10:31, Garth N. Wells <[email protected]> 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
In the file generate.py at the bottom, you need to switch on the lines: from generate_docstrings import DocstringGenerator g = DocstringGenerator(header_files = docstring_headers, swig_directory = ".", docstring_file_base = "") g.generate_doxygen_documentation() g.generate_interface_file_from_index() g.clean() and then comment the remainder of the lines which creates docstrings.i from the docstrings module. Then run 'python generate.py' to generate docstrings.i from xml files. Kristian > 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_docstrings.i' > > > when I run it. > > 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
