r19956 - gnucash/trunk/src - Bug #637346: Adding python-bindings to doxygen documentation
Christian Stimming
cstim at code.gnucash.org
Fri Dec 17 15:36:40 EST 2010
Author: cstim
Date: 2010-12-17 15:36:40 -0500 (Fri, 17 Dec 2010)
New Revision: 19956
Trac: http://svn.gnucash.org/trac/changeset/19956
Modified:
gnucash/trunk/src/base-typemaps.i
gnucash/trunk/src/doc/doxygen.cfg.in
gnucash/trunk/src/doc/doxygen_main_page.c
gnucash/trunk/src/optional/python-bindings/__init__.py
gnucash/trunk/src/optional/python-bindings/example_scripts/account_analysis.py
gnucash/trunk/src/optional/python-bindings/example_scripts/change_tax_code.py
gnucash/trunk/src/optional/python-bindings/example_scripts/new_book_with_opening_balances.py
gnucash/trunk/src/optional/python-bindings/example_scripts/priceDB_test.py
gnucash/trunk/src/optional/python-bindings/example_scripts/simple_book.py
gnucash/trunk/src/optional/python-bindings/example_scripts/simple_business_create.py
gnucash/trunk/src/optional/python-bindings/example_scripts/simple_invoice_insert.py
gnucash/trunk/src/optional/python-bindings/example_scripts/simple_session.py
gnucash/trunk/src/optional/python-bindings/example_scripts/simple_sqlite_create.py
gnucash/trunk/src/optional/python-bindings/example_scripts/simple_test.py
gnucash/trunk/src/optional/python-bindings/example_scripts/test_imbalance_transaction.py
gnucash/trunk/src/optional/python-bindings/function_class.py
gnucash/trunk/src/optional/python-bindings/glib.i
gnucash/trunk/src/optional/python-bindings/gnucash_business.py
gnucash/trunk/src/optional/python-bindings/gnucash_core.i
gnucash/trunk/src/optional/python-bindings/gnucash_core.py
gnucash/trunk/src/optional/python-bindings/timespec.i
Log:
Bug #637346: Adding python-bindings to doxygen documentation
Patch by Christoph Holtermann.
Modified: gnucash/trunk/src/base-typemaps.i
===================================================================
--- gnucash/trunk/src/base-typemaps.i 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/base-typemaps.i 2010-12-17 20:36:40 UTC (rev 19956)
@@ -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;
Modified: gnucash/trunk/src/doc/doxygen.cfg.in
===================================================================
--- gnucash/trunk/src/doc/doxygen.cfg.in 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/doc/doxygen.cfg.in 2010-12-17 20:36:40 UTC (rev 19956)
@@ -572,7 +572,9 @@
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.
Modified: gnucash/trunk/src/doc/doxygen_main_page.c
===================================================================
--- gnucash/trunk/src/doc/doxygen_main_page.c 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/doc/doxygen_main_page.c 2010-12-17 20:36:40 UTC (rev 19956)
@@ -56,6 +56,7 @@
- \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.
Modified: gnucash/trunk/src/optional/python-bindings/__init__.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/__init__.py 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/__init__.py 2010-12-17 20:36:40 UTC (rev 19956)
@@ -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 at parit.ca>
+# @author Jeff Green, ParIT Worker Co-operative <jeff at parit.ca>
+# @ingroup python-bindings
Modified: gnucash/trunk/src/optional/python-bindings/example_scripts/account_analysis.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/example_scripts/account_analysis.py 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/account_analysis.py 2010-12-17 20:36:40 UTC (rev 19956)
@@ -21,6 +21,10 @@
#
# @author Mark Jenkins, ParIT Worker Co-operative <mark at parit.ca>
+## @file
+# @brief Output all the credits and debits on an account
+# @author Mark Jenkins, ParIT Worker Co-operative <mark at parit.ca>
+# @ingroup python-bindings-examples
# python imports
from sys import argv, stdout
Modified: gnucash/trunk/src/optional/python-bindings/example_scripts/change_tax_code.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/example_scripts/change_tax_code.py 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/change_tax_code.py 2010-12-17 20:36:40 UTC (rev 19956)
@@ -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
Modified: gnucash/trunk/src/optional/python-bindings/example_scripts/new_book_with_opening_balances.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/example_scripts/new_book_with_opening_balances.py 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/new_book_with_opening_balances.py 2010-12-17 20:36:40 UTC (rev 19956)
@@ -22,6 +22,12 @@
#
# @author Mark Jenkins, ParIT Worker Co-operative <mark at 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 at 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, \
Modified: gnucash/trunk/src/optional/python-bindings/example_scripts/priceDB_test.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/example_scripts/priceDB_test.py 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/priceDB_test.py 2010-12-17 20:36:40 UTC (rev 19956)
@@ -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
Modified: gnucash/trunk/src/optional/python-bindings/example_scripts/simple_book.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/example_scripts/simple_book.py 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/simple_book.py 2010-12-17 20:36:40 UTC (rev 19956)
@@ -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
Modified: gnucash/trunk/src/optional/python-bindings/example_scripts/simple_business_create.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/example_scripts/simple_business_create.py 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/simple_business_create.py 2010-12-17 20:36:40 UTC (rev 19956)
@@ -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 at parit.ca>
+# @ingroup python-bindings-examples
+
from os.path import abspath
from sys import argv
import datetime
Modified: gnucash/trunk/src/optional/python-bindings/example_scripts/simple_invoice_insert.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/example_scripts/simple_invoice_insert.py 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/simple_invoice_insert.py 2010-12-17 20:36:40 UTC (rev 19956)
@@ -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 at 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
Modified: gnucash/trunk/src/optional/python-bindings/example_scripts/simple_session.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/example_scripts/simple_session.py 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/simple_session.py 2010-12-17 20:36:40 UTC (rev 19956)
@@ -1,4 +1,7 @@
#!/usr/bin/env python
+## @file
+# @brief Example Script simple session
+# @ingroup python-bindings-examples
from gnucash import \
Session, GnuCashBackendException, \
Modified: gnucash/trunk/src/optional/python-bindings/example_scripts/simple_sqlite_create.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/example_scripts/simple_sqlite_create.py 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/simple_sqlite_create.py 2010-12-17 20:36:40 UTC (rev 19956)
@@ -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
Modified: gnucash/trunk/src/optional/python-bindings/example_scripts/simple_test.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/example_scripts/simple_test.py 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/simple_test.py 2010-12-17 20:36:40 UTC (rev 19956)
@@ -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
Modified: gnucash/trunk/src/optional/python-bindings/example_scripts/test_imbalance_transaction.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/example_scripts/test_imbalance_transaction.py 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/test_imbalance_transaction.py 2010-12-17 20:36:40 UTC (rev 19956)
@@ -22,6 +22,11 @@
#
# @author Mark Jenkins, ParIT Worker Co-operative <mark at parit.ca>
+## @file
+# @brief Test the transaction imbalace viewing mechanisms
+# @author Mark Jenkins, ParIT Worker Co-operative <mark at parit.ca>
+# @ingroup python-bindings-examples
+
from sys import argv
from gnucash import Session, Transaction, Split, Account, GncNumeric, \
Modified: gnucash/trunk/src/optional/python-bindings/function_class.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/function_class.py 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/function_class.py 2010-12-17 20:36:40 UTC (rev 19956)
@@ -20,6 +20,12 @@
#
# @author Mark Jenkins, ParIT Worker Co-operative <mark at parit.ca>
+## @file
+# @brief Library for making python classes from a set of functions.
+# @author Mark Jenkins, ParIT Worker Co-operative <mark at parit.ca>
+# @author Jeff Green, ParIT Worker Co-operative <jeff at parit.ca>
+# @ingroup python-bindings
+
INSTANCE_ARGUMENT = "instance"
class ClassFromFunctions(object):
@@ -111,7 +117,7 @@
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
Modified: gnucash/trunk/src/optional/python-bindings/glib.i
===================================================================
--- gnucash/trunk/src/optional/python-bindings/glib.i 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/glib.i 2010-12-17 20:36:40 UTC (rev 19956)
@@ -22,7 +22,14 @@
*
* @author Mark Jenkins, ParIT Worker Co-operative <mark at 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 at parit.ca>
+ @author Jeff Green, ParIT Worker Co-operative <jeff at parit.ca>
+ @ingroup python-bindings */
+
%typemap(in) gint8, gint16, gint32, gint64, gint, gshort, glong {
$1 = ($1_type)PyInt_AsLong($input);
}
Modified: gnucash/trunk/src/optional/python-bindings/gnucash_business.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/gnucash_business.py 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/gnucash_business.py 2010-12-17 20:36:40 UTC (rev 19956)
@@ -20,6 +20,11 @@
#
# @author Mark Jenkins, ParIT Worker Co-operative <mark at parit.ca>
# @author Jeff Green, ParIT Worker Co-operative <jeff at parit.ca>
+## @file
+# @brief High level python wrapper classes for the business parts of GnuCash
+# @author Mark Jenkins, ParIT Worker Co-operative <mark at parit.ca>
+# @author Jeff Green, ParIT Worker Co-operative <jeff at parit.ca>
+# @ingroup python-bindings
import gnucash_core_c
Modified: gnucash/trunk/src/optional/python-bindings/gnucash_core.i
===================================================================
--- gnucash/trunk/src/optional/python-bindings/gnucash_core.i 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/gnucash_core.i 2010-12-17 20:36:40 UTC (rev 19956)
@@ -24,6 +24,21 @@
* @author Jeff Green, ParIT Worker Co-operative <jeff at 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 at parit.ca>
+ @author Jeff Green, ParIT Worker Co-operative <jeff at 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>
Modified: gnucash/trunk/src/optional/python-bindings/gnucash_core.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/gnucash_core.py 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/gnucash_core.py 2010-12-17 20:36:40 UTC (rev 19956)
@@ -21,6 +21,84 @@
# @author Mark Jenkins, ParIT Worker Co-operative <mark at parit.ca>
# @author Jeff Green, ParIT Worker Co-operative <jeff at 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 at parit.ca>
+# @author Jeff Green, ParIT Worker Co-operative <jeff at 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 at 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 @@
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 @@
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 @@
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
Modified: gnucash/trunk/src/optional/python-bindings/timespec.i
===================================================================
--- gnucash/trunk/src/optional/python-bindings/timespec.i 2010-12-17 14:00:52 UTC (rev 19955)
+++ gnucash/trunk/src/optional/python-bindings/timespec.i 2010-12-17 20:36:40 UTC (rev 19956)
@@ -23,6 +23,12 @@
* @author Mark Jenkins, ParIT Worker Co-operative <mark at parit.ca>
*/
+/** @file
+ @brief SWIG interface file for type translation of Timespec types
+ @author Mark Jenkins, ParIT Worker Co-operative <mark at parit.ca>
+ @author Jeff Green, ParIT Worker Co-operative <jeff at parit.ca>
+ @ingroup python-bindings */
+
// A typemap for converting python dates to Timespec in functions that
// require Timespec as an argument
%typemap(in) Timespec {
More information about the gnucash-changes
mailing list