Bug #637346: Adding python-bindings to doxygen documentation

Patch by Christoph Holtermann.

git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@19956 57a11ea4-9604-0410-9ed3-97b8803252fd

src/base-typemaps.i

@@ -1,3 +1,8 @@
+/** @file 
+    @brief interface file for SWIG, used by python-bindings and scheme(?).
+    @addtogroup python-bindings
+*/
+
 /* Not sure why SWIG doesn't figure this out. */
 typedef int gint;
 typedef int time_t;

src/doc/doxygen.cfg.in

@@ -572,7 +572,9 @@ INPUT_ENCODING         = UTF-8
 
 FILE_PATTERNS          = *.c \
                          *.h \
-                         *.txt
+                         *.txt \
+			 *.py \
+			 *.i
 
 # The RECURSIVE tag can be used to turn specify whether or not subdirectories 
 # should be searched for input files as well. Possible values are YES and NO. 

src/doc/doxygen_main_page.c

@@ -56,6 +56,7 @@ in relation to existing code.
 - \ref taxnotes
 - \ref todo
 - \ref userprefs
+- \ref python-bindings-page
 
 Each overview in this section is generated directly from the
 source files using Doxygen but some topics need updating.

src/optional/python-bindings/__init__.py

@@ -4,3 +4,8 @@
 # instead of
 # >>> from gnucash.gnucash_core import thingy
 from gnucash_core import *
+##  @file
+#   @brief helper file for the importing of gnucash
+#   @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
+#   @author Jeff Green,   ParIT Worker Co-operative <jeff@parit.ca>
+#   @ingroup python-bindings

src/optional/python-bindings/example_scripts/account_analysis.py

@@ -21,6 +21,10 @@
 #
 # @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
 
+##  @file
+#   @brief Output all the credits and debits on an account
+#   @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
+#   @ingroup python-bindings-examples
 
 # python imports
 from sys import argv, stdout

src/optional/python-bindings/example_scripts/change_tax_code.py

@@ -1,5 +1,9 @@
 #!/usr/bin/env python
 
+##  @file
+#   @brief Output all the credits and debits on an account
+#   @ingroup python-bindings-examples
+
 from gnucash import Session, Account
 
 # choose the account code to select

src/optional/python-bindings/example_scripts/new_book_with_opening_balances.py

@@ -22,6 +22,12 @@
 #
 # @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
 
+##  @file
+#   @brief Replicate the account structure of a
+#   book and apply basis opening balances from the original
+#   @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
+#   @ingroup python-bindings-examples
+
 from gnucash import Session, Account, Transaction, Split, GncNumeric
 from gnucash.gnucash_core_c import \
     GNC_DENOM_AUTO, GNC_HOW_DENOM_EXACT, \

src/optional/python-bindings/example_scripts/priceDB_test.py

@@ -10,6 +10,10 @@
 # The account file is not saved but always use a disposable copy.
 # Change, FILE, CURRENCY and STOCK to those defined in your test account.
 
+##  @file
+#   @brief Test file for price database stuff
+#   @author Mike Evans 
+#   @ingroup python-bindings-examples
 
 from gnucash import Session
 FILE = "PATH_TO_YOUR_TEST_FILE"  ## Fail is no saved but use a copy anyway

src/optional/python-bindings/example_scripts/simple_book.py

@@ -1,4 +1,9 @@
 #!/usr/bin/env python
+
+##  @file
+#   @brief Simple example for a book 
+#   @ingroup python-bindings-examples
+
 import sys
 from gnucash import Session
 

src/optional/python-bindings/example_scripts/simple_business_create.py

@@ -33,6 +33,11 @@
 #
 # You may also want to look at simple_invoice_insert.py
 
+##  @file
+#   @brief Set up a set of books for business feature use
+#   @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
+#   @ingroup python-bindings-examples
+
 from os.path import abspath
 from sys import argv
 import datetime

src/optional/python-bindings/example_scripts/simple_invoice_insert.py

@@ -33,6 +33,11 @@
 #          sqlite3:///home/blah/blah.gnucash
 #          dda2ec8e3e63c7715097f852851d6b22 1001 'The Goods' 201.43 
 
+##  @file
+#   @brief Add an invoice to a set of books
+#   @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
+#   @ingroup python-bindings-examples
+
 from gnucash import Session, GUID, GncNumeric
 from gnucash.gnucash_business import Customer, Invoice, Entry
 from gnucash.gnucash_core_c import string_to_guid

src/optional/python-bindings/example_scripts/simple_session.py

@@ -1,4 +1,7 @@
 #!/usr/bin/env python
+##  @file
+#   @brief Example Script simple session
+#   @ingroup python-bindings-examples
 
 from gnucash import \
      Session, GnuCashBackendException, \

src/optional/python-bindings/example_scripts/simple_sqlite_create.py

@@ -1,4 +1,7 @@
 #!/usr/bin/env python
+##  @file
+#   @brief Example Script simple sqlite create 
+#   @ingroup python-bindings-examples
 
 from gnucash import Session, Account
 from os.path import abspath

src/optional/python-bindings/example_scripts/simple_test.py

@@ -1,5 +1,7 @@
 #!/usr/bin/env python
-# Creates a basic set of accounts and a couple of transactions
+## @file
+# @brief Creates a basic set of accounts and a couple of transactions
+# @ingroup python-bindings-example
 
 from gnucash import Session, Account, Transaction, Split, GncNumeric
 

src/optional/python-bindings/example_scripts/test_imbalance_transaction.py

@@ -22,6 +22,11 @@
 #
 # @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
 
+##  @file
+#   @brief Test the transaction imbalace viewing mechanisms
+#   @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
+#   @ingroup python-bindings-examples
+
 from sys import argv
 
 from gnucash import Session, Transaction, Split, Account, GncNumeric, \

src/optional/python-bindings/function_class.py

@@ -20,6 +20,12 @@
 #
 # @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
 
+##  @file
+#   @brief Library for making python classes from a set of functions.
+#   @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
+#   @author Jeff Green,   ParIT Worker Co-operative <jeff@parit.ca>
+#   @ingroup python-bindings
+
 INSTANCE_ARGUMENT = "instance"
 
 class ClassFromFunctions(object):
@@ -111,7 +117,7 @@ def decorate_functions(cls, decorator, *args):
                      decorator( getattr(cls, function_name) ) )
 
 def method_function_returns_instance(method_function, cls):
-    """A function decorator that is used to decorates method functions that
+    """A function decorator that is used to decorate method functions that
     return instance data, to return instances instead.
 
     You can't use this decorator with @, because this function has a second

src/optional/python-bindings/glib.i

@@ -22,6 +22,13 @@
  *
  * @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
  */
+/** @file
+    @brief SWIG interface file for type translation of glib types
+        This file may be obsolete, because the same definitions are also in base-typemaps.i.
+    @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
+    @author Jeff Green,   ParIT Worker Co-operative <jeff@parit.ca>
+    @ingroup python-bindings */
+
 
 %typemap(in) gint8, gint16, gint32, gint64, gint, gshort, glong {
     $1 = ($1_type)PyInt_AsLong($input);

src/optional/python-bindings/gnucash_business.py

@@ -20,6 +20,11 @@
 #
 # @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
 # @author Jeff Green,   ParIT Worker Co-operative <jeff@parit.ca>
+##  @file
+#   @brief High level python wrapper classes for the business parts of GnuCash
+#   @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
+#   @author Jeff Green,   ParIT Worker Co-operative <jeff@parit.ca>
+#   @ingroup python-bindings
 
 import gnucash_core_c
 

src/optional/python-bindings/gnucash_core.i

@@ -24,6 +24,21 @@
  * @author Jeff Green, ParIT Worker Co-operative <jeff@parit.ca>
  */
 
+/** @file
+    @brief SWIG interface file for the core parts of GnuCash
+        This file is processed by SWIG and the resulting files are gnucash_core.c and gnucash_core_c.py
+    @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
+    @author Jeff Green,   ParIT Worker Co-operative <jeff@parit.ca>
+    @ingroup python-bindings 
+
+    @file gnucash_core.c
+    @brief SWIG output file.
+    @ingroup python-bindings
+    @file gnucash_core_c.py
+    @brief SWIG output file.
+    @ingroup python-bindings
+*/
+
 %feature("autodoc", "1");
 %module(package="gnucash") gnucash_core_c
 
@@ -68,7 +83,7 @@
 %include <qofbackend.h>
 
 // this function is defined in qofsession.h, but isnt found in the libraries,
-// ignoroed because SWIG attempts to link against (to create language bindings)
+// ignored because SWIG attempts to link against (to create language bindings)
 %ignore qof_session_not_saved;
 %include <qofsession.h>
 

src/optional/python-bindings/gnucash_core.py

@@ -21,6 +21,84 @@
 # @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
 # @author Jeff Green,   ParIT Worker Co-operative <jeff@parit.ca>
 
+# The following is for doxygen
+## @file
+#  @brief High level python wrapper classes for the core parts of GnuCash
+#  @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
+#  @author Jeff Green,   ParIT Worker Co-operative <jeff@parit.ca>
+#  @ingroup python-bindings
+
+## @defgroup python-bindings
+#  Also have a look at the page @ref python-bindings-page.
+
+## @defgroup python-bindings-examples
+#  @ingroup python-bindings
+#  The python-bindings come with quite a lot of example scripts.
+
+##  @page python-bindings-page Python bindings
+#   Also have a look at group @ref python-bindings.
+#
+#   For the moment the python-bindings are only available via svn. They may be included
+#   in GnuCash 2.4.
+#
+#   To enable them in the compilation process you have to add --enable-python-bindings
+#   to the call of ./configure.
+#
+#   As a starting point have a look at the \link #python-bindings-examples example-scripts\endlink.
+#
+#   @section python-bindings-section Principles
+#   The python-bindings are generated using SWIG from the c-source-files of gnucash.
+#   It is possible to access a wide range of the functions of GnuCash in this way.
+#   SWIG extracts informations from the c-sources and provides access to the structures
+#   from python.
+#  
+#   SWIG reads gnucash_core.i and outputs gnucash_core.c and gnucash_core_c.py.
+#
+#   This leads to the bottom layer of funtions which is a quite raw extract and close to the original source.
+#   This yields access using the c-style-api.
+#   You will find a lot of pointers here which you can just ignore if input and output of the function have the
+#   same type.
+#   As a second layer there are some structures where a nice pythonic interface has been added.
+#   @section highlevel High level python wrapper classes
+#   If you
+# 
+#   @code >> import gnucash @endcode
+#
+#   You can access the structures of the high level api. For Example you get a Session object by
+#
+#   @code >> session=gnucash.Session() @endcode
+#
+#   @section c_style_api C-style-api
+#
+#   If you
+#
+#   @code >> import gnucash @endcode
+#
+#   The c-style-api can be accessed via gnucash.gnucash_core_c. You can have a look at all the possibilities
+#   at gnucash_core_c.py.
+#
+#   For example you could start a session by gnucash.gnucash_core_c.qof_session_begin(). But if you just try
+#
+#   @code session=gnucash.gnucash_core_c.qof_session_begin() @endcode
+#
+#   you will get an error message and realize the lack of convenience for you have to add the correct function parameters.
+#
+#   Not all of the available structures will work. SWIG just takes everything from the sources and translates it. Not everything
+#   is a working translation. At this point you are getting close to the developers whom you can contact at the mailing-list gnucash-devel@gnucash.org.
+#   A step further would be to fix the problem by changing SWIGs input files to correctly reflect the c-structure.
+#
+#   @section Thisorthat When to use which api ?
+#
+#   The start would surely be the high-level api for you can be quite sure to have something working and you will maybe find
+#   explanations in the example-scripts. If you search for something that is not yet implemented in that way you will have to
+#   take your way to the c-style-api.
+#
+#   @section pydoc Documentation
+#
+#   The documentation you just read uses doxygen. It collects documentation in GnuCash's sources. Besides that there is
+#   the classic python-documentation using help() and docstrings. Have a look at both.
+
+
 import gnucash_core_c
 
 from function_class import \
@@ -65,7 +143,7 @@ class Session(GnuCashCoreClass):
 
     def __init__(self, book_uri=None, ignore_lock=False, is_new=False,
                  force_new= False):
-        """A convienent contructor that allows you to specify a book URI,
+        """A convenient contructor that allows you to specify a book URI,
         begin the session, and load the book.
 
         This can give you the power of calling
@@ -115,7 +193,7 @@ def raise_backend_errors(self, called_function="qof_session function"):
                 errors )
 
     def generate_errors(self):
-        """A generator that yeilds any outstanding QofBackend errors
+        """A generator that yields any outstanding QofBackend errors
         """
         while self.get_error() is not ERR_BACKEND_NO_ERR:
             error = self.pop_error()
@@ -417,7 +495,7 @@ def one_arg_default_none(function):
     extract_attributes_with_prefix(gnucash_core_c, 'ERR_'):
     backend_error_dict[ error_value ] = error_name
 
-# GncNumeric demoniminator computation schemes
+# GncNumeric denominator computation schemes
 # Used for the denom argument in arithmetic functions like GncNumeric.add
 from gnucash.gnucash_core_c import GNC_DENOM_AUTO
 

src/optional/python-bindings/timespec.i

@@ -23,6 +23,12 @@
  * @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
  */
 
+/** @file
+    @brief SWIG interface file for type translation of Timespec types
+    @author Mark Jenkins, ParIT Worker Co-operative <mark@parit.ca>
+    @author Jeff Green,   ParIT Worker Co-operative <jeff@parit.ca>
+    @ingroup python-bindings */
+
 // A typemap for converting python dates to Timespec in functions that
 // require Timespec as an argument
 %typemap(in) Timespec {