GNOME Bugzilla – Bug 637346
Adding python-bindings to doxygen
Last modified: 2018-06-29 22:49:29 UTC
This is an attempt to include the python-bindings in the doxygen-documentation.
Created attachment 176509 [details] [review] Adds simple doxygen-support to the python-bindings
This adds .py and .i files as inputs to doxygen. Python is not fully supported by doxygen. In the comments that are used inside python which use docstrings it is not possible to use doxygens special commands. These can only be used with comments that are marked with ## or #. It is possible to use special commands inside the docstrings only when a tool like doxypy.py is used (http://code.foosel.org/doxypy). This can be set as an input filter to doxygen. It "translates" docstrings to #-comments. So doxygen sees the file through this filters eyes and accepts special commands in docstrings. I don't know if it's worth the effort to try to implement that. For a beginning staying with this is sufficient. Please have a look at these deeds and maybe commit one day if you like.
Comment on attachment 176509 [details] [review] Adds simple doxygen-support to the python-bindings Just a Note: From README.dependencies: C++ style comments (`// comment to end of line') are discouraged but not actively eradicated. But I am not shure, it this should affect the .py files.
(In reply to comment #3) > (From update of attachment 176509 [details] [review]) > Just a Note: > From README.dependencies: > C++ style comments (`// comment to end of line') are discouraged but > not actively eradicated. > > But I am not shure, it this should affect the .py files. Are you talking about this ? Index: src/optional/python-bindings/timespec.i =================================================================== ... // A typemap for converting python dates to Timespec in functions that // require Timespec as an argument I just wonder, because these lines of code are not related to my suggested attaching the bindings to doxygen but something that has already been there. Is this a general coding guideline for GnuCash you are speaking about or is this guideline related to doxygen ? In the first case it would be just coincidence that this line was included in the patch, in the second case I would have to have a look at all files that are newly introduced to doxygen. In the .py files there are no comments like // (also not /* or so ). Python comments are only # like in shell-scripts or """ ... """ as docstrings. The .i-files I am not so sure about. As far as I understand they are only used as interface-files for SWIG. Timespec.i is such a thing. I could go ahead and change all //-comments to /* and */ even though I didn't write them. I guess it wouldn't do any harm. I could make a list of all files that are newly introduced by extending the inclusion criteria for doxygen if that is of any help.
Created attachment 176545 [details] [review] Adds simple doxygen-support to the python-bindings Update reflects changes in src/optional/python-bindings/example_scripts/price_database_example.py. I had to modify that part of the patch manually for it is not yet in svn, but surely will be earlier than this one. I hope it works. To be pedantic : The patch also includes corrections for some spelling mistakes I came across in the python-bindings ;-)
I put a version of doxygen including this patch online on http://www.gnucash.holtermann7.de/index.html New page Python-bindings: http://www.gnucash.holtermann7.de/python-bindings-page.html Added group python-bindings: http://www.gnucash.holtermann7.de/group__python-bindings.html Added group python-bindings-examples as a subgroup of python-bindings: http://www.gnucash.holtermann7.de/group__python-bindings-examples.html
Comment on attachment 176545 [details] [review] Adds simple doxygen-support to the python-bindings Sounds good, and it also doesn't interfere with the upcoming 2.4.0 release. I got one rejected patch for src/optional/python-bindings/example_scripts/price_database_example.py but the rest is committed.
... and I committed the patch as r19956. Thanks a lot!
(In reply to comment #8) > ... and I committed the patch as r19956. Thanks a lot! Thank you very much !
Created attachment 176731 [details] [review] A second step towards doxygen python-bindings docs * doxygen_mainpage.c : Put reference to python-bindings to it's alphabetical place * Rename all - to _ : python-bindings -> python_bindings - That's because doxygen at http://svn.gnucash.org/docs/HEAD/ does not like the minus signs and sometimes just takes the first part. With my local version which is 1.7 this doesn't happen. * Move the base of documentation from gnucash_core.py to a separate file : src/doc/python-bindings-doxygen.c * Add that file to src/doc/Makefile.am - EXTRA_DIST * Extend the doc - Add some mre details to explain SWIGs working process.
I also put this 2nd Version online, see Comment 6 https://bugzilla.gnome.org/show_bug.cgi?id=637346#c6
Comment on attachment 176731 [details] [review] A second step towards doxygen python-bindings docs Very good explanation! Also, feel free to reorder to gnucash docs mainpage in other ways as well. E.g., the python page link may appear completely separated from the "modules" enumeration because python bindings are a different thing... but in any case your patch is a big improvement and can be committed immediately.
Comment on attachment 176731 [details] [review] A second step towards doxygen python-bindings docs r19981, thanks!
Thank you very much for committing ! One file is missing, though : src/doc/python-bindings-doxygen.py. I created it new in the 2nd patch. It's in the patch as I just checked, I didn't forget it. It contains the main part of the documentation which is at the moment missing in doxygen.
r19991, thanks for noting this. (In git patches the addition of new files is noted as well; in plain patches this isn't always immediately visibile and you might need to point it out extra as well.)
Created attachment 178676 [details] [review] A small enhancement, basically mentioning the wiki-page
Comment on attachment 178676 [details] [review] A small enhancement, basically mentioning the wiki-page r20127, thanks!
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=637346. Please continue processing the bug there and please update any external references or bookmarks.