GNOME Bugzilla – Bug 651491
Importing docstrings from doxygen to swig
Last modified: 2018-06-29 22:58:22 UTC
Created attachment 188895 [details] [review] --just a proof of concept--please don't commit-- http://www.enricozini.org/2007/tips/swig-doxygen-docstring/ describes a way to include the docstrings in GnuCashs C-sourcefiles into the python-bindings generated by SWIG. I tried it once and it seems to work. What I have done is 1) in src/doc/doxygen.cfg.in line 1097: GENERATE_XML = YES 2) run "make doc" to get xml-files 3) get doxy2swig.py. I found it at http://wrapitk.googlecode.com/svn-history/r539/trunk/Languages/Doc/doxy2swig.py 4) took the include-files from gnucash_core.i and put their names into file doxydocfiles. Where filename.h becomes filename_8h.xml 5) create tempdir doxydocs 6) wrote the skript make_doxydoc.sh. This takes the names from doxydocfiles and calls doxy2swig.py ../../doc/xml/filename_8c.xml doxydocs/filename.i 7) The skript also outputs all files as %includes to doxydocs.i 8) Include doxydocs.i into gnucash_core.i 9) run SWIG Now there is a lot more online documentation. I don't know how to include this procedure into the regular make process. So this is just a proof of concept. --Please don't commit this patch yet--
Created attachment 189045 [details] [review] patch to import documentation from doxygen to python-bindings I found out how to change the automake files to include the process. 1) a new option --enable-doxy2swig is added to configure.ac. Variable WITH_DOXY2SWIG is exported. 2) src/optional/python-bindings/Makefile.am is changed to call doxy2swig.py to read xml files in /src/doc/xml 3) if they do not exist, make doc will be called in basedir 4) src/doc/Makefile.am enables XML-Output if WITH_DOXY2SWIG is set. 5) the output of doxy2swig.py is collected in doxydocs.i 6) if WITH_DOXY2SWIG is set doxydocs.i is included in gnucash_core.i
doxy2swig.py is not included and has to be separately installed. So I don't risk any copyright issues ;-)
it can be found at http://www.aero.iitb.ac.in/~prabhu/software/code/python/doxy2swig.py
Comment on attachment 189045 [details] [review] patch to import documentation from doxygen to python-bindings I finally found some time to review this patch. I have applied it to current trunk. It applies cleanly. The logic you added in configure.in seems sound as well. I tried various combination of options, and configure always worked as expected. Next I tried to build GnuCash with --enable-python and --enable-doxy2swig. This fails with errors of xml files not being found. I'll attach the relevant part of the log.
Created attachment 194138 [details] Part of the build log after configuring & building with --enable-doxy2swig Some notes that may be useful: * I always run configure from a subdirectory of the source tree. So my build happens in that subdirectory, not directly in the source tree. I'm not sure this has anything to do with this error, but I just mention it to be sure. * So in this pytest subdirectory, I ran "../configure --enable-python --enable-doxy2swig <and some other options I always have set>" * The build was started with a simple "make" * I'm surprised that after make has finished with optional/python-bindings it reports several times to run make doc in /kobaltnet/janssege/Development/EclipseGnuCash/GnuCash-git (that's the base directory for my checkout). I would have expected make doc to be run in several subdirectories. * After that, doxy2swig.py fails due to a lot of missing xml files. I suppose these should have been generated in the previous steps.
I guess the first point you mention is important. I'm running configure in the base directory. The error log says: make[5]: Entering directory `/kobaltnet/janssege/Development/EclipseGnuCash/GnuCash-git/pytest/src/optional/python-bindings' make[6]: Entering directory `/kobaltnet/janssege/Development/EclipseGnuCash/GnuCash-git' and that's where make doc is called. It seems to me that it should be called from /kobaltnet/janssege/Development/EclipseGnuCash/GnuCash-git/pytest/ XML_DOC_DIR points to the wrong directory /kobaltnet/janssege/Development/EclipseGnuCash/GnuCash-git/src/doc/xml/ it should be /kobaltnet/janssege/Development/EclipseGnuCash/GnuCash-git/pytest/src/doc/xml/ XML_DOC_DIR = ${top_srcdir}/src/doc/xml XML_DOC_FILES = ${XML_DOC_DIR}/qofsession_8h.xml\ top_srcdir is not possible to use in your case. How do i get the directory that's your actual source dir ? make doc should be called in the base directory - at least that's what i usually do. With the xml-file generation enabled it produces the files that are needed to be read from. They are XML_DOC_FILES and they should be in XML_DOC_DIR. I'm not so familiar with Make. I will try to work this out.
To Geert Janssens: Could you tell me how exactly you compile gnucash ? In the last months I unfortunately didn't have time to work this out, I hope to make it over christmas. regards, Christoph Holtermann
GnuCash bug tracking has moved to a new Bugzilla host. The new URL for this bug is https://bugs.gnucash.org/show_bug.cgi?id=651491. Please continue processing the bug there and please update any external references or bookmarks.