From 7c76425cbff55076053eb83df8dd1fb4bf5077f4 Mon Sep 17 00:00:00 2001 From: Christian Stimming Date: Fri, 17 Dec 2010 20:36:40 +0000 Subject: [PATCH] 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 | 5 ++ src/doc/doxygen.cfg.in | 4 +- src/doc/doxygen_main_page.c | 1 + src/optional/python-bindings/__init__.py | 5 ++ .../example_scripts/account_analysis.py | 4 + .../example_scripts/change_tax_code.py | 4 + .../new_book_with_opening_balances.py | 6 ++ .../example_scripts/priceDB_test.py | 4 + .../example_scripts/simple_book.py | 5 ++ .../example_scripts/simple_business_create.py | 5 ++ .../example_scripts/simple_invoice_insert.py | 5 ++ .../example_scripts/simple_session.py | 3 + .../example_scripts/simple_sqlite_create.py | 3 + .../example_scripts/simple_test.py | 4 +- .../test_imbalance_transaction.py | 5 ++ .../python-bindings/function_class.py | 8 +- src/optional/python-bindings/glib.i | 7 ++ .../python-bindings/gnucash_business.py | 5 ++ src/optional/python-bindings/gnucash_core.i | 17 +++- src/optional/python-bindings/gnucash_core.py | 84 ++++++++++++++++++- src/optional/python-bindings/timespec.i | 6 ++ 21 files changed, 183 insertions(+), 7 deletions(-) diff --git a/src/base-typemaps.i b/src/base-typemaps.i index 95934b9117..c6df30f872 100644 --- a/src/base-typemaps.i +++ b/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; diff --git a/src/doc/doxygen.cfg.in b/src/doc/doxygen.cfg.in index b6d09c9de7..636372e4e7 100644 --- a/src/doc/doxygen.cfg.in +++ b/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. diff --git a/src/doc/doxygen_main_page.c b/src/doc/doxygen_main_page.c index ecaa3774b2..2678cba127 100644 --- a/src/doc/doxygen_main_page.c +++ b/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. diff --git a/src/optional/python-bindings/__init__.py b/src/optional/python-bindings/__init__.py index 0e94f2ac33..815b5fbae4 100644 --- a/src/optional/python-bindings/__init__.py +++ b/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 +# @author Jeff Green, ParIT Worker Co-operative +# @ingroup python-bindings diff --git a/src/optional/python-bindings/example_scripts/account_analysis.py b/src/optional/python-bindings/example_scripts/account_analysis.py index 1787085a26..5e522e31ef 100644 --- a/src/optional/python-bindings/example_scripts/account_analysis.py +++ b/src/optional/python-bindings/example_scripts/account_analysis.py @@ -21,6 +21,10 @@ # # @author Mark Jenkins, ParIT Worker Co-operative +## @file +# @brief Output all the credits and debits on an account +# @author Mark Jenkins, ParIT Worker Co-operative +# @ingroup python-bindings-examples # python imports from sys import argv, stdout diff --git a/src/optional/python-bindings/example_scripts/change_tax_code.py b/src/optional/python-bindings/example_scripts/change_tax_code.py index 111ea6fc81..c6790c4d9e 100644 --- a/src/optional/python-bindings/example_scripts/change_tax_code.py +++ b/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 diff --git a/src/optional/python-bindings/example_scripts/new_book_with_opening_balances.py b/src/optional/python-bindings/example_scripts/new_book_with_opening_balances.py index a5d5555ae7..247352d369 100644 --- a/src/optional/python-bindings/example_scripts/new_book_with_opening_balances.py +++ b/src/optional/python-bindings/example_scripts/new_book_with_opening_balances.py @@ -22,6 +22,12 @@ # # @author Mark Jenkins, ParIT Worker Co-operative +## @file +# @brief Replicate the account structure of a +# book and apply basis opening balances from the original +# @author Mark Jenkins, ParIT Worker Co-operative +# @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, \ diff --git a/src/optional/python-bindings/example_scripts/priceDB_test.py b/src/optional/python-bindings/example_scripts/priceDB_test.py index 584b858adf..915158ecaf 100644 --- a/src/optional/python-bindings/example_scripts/priceDB_test.py +++ b/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 diff --git a/src/optional/python-bindings/example_scripts/simple_book.py b/src/optional/python-bindings/example_scripts/simple_book.py index 9d75515d5e..fb2a92584b 100644 --- a/src/optional/python-bindings/example_scripts/simple_book.py +++ b/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 diff --git a/src/optional/python-bindings/example_scripts/simple_business_create.py b/src/optional/python-bindings/example_scripts/simple_business_create.py index dd36226749..302b46cd9a 100644 --- a/src/optional/python-bindings/example_scripts/simple_business_create.py +++ b/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 +# @ingroup python-bindings-examples + from os.path import abspath from sys import argv import datetime diff --git a/src/optional/python-bindings/example_scripts/simple_invoice_insert.py b/src/optional/python-bindings/example_scripts/simple_invoice_insert.py index 2c9ce52d26..d620f6fdc3 100644 --- a/src/optional/python-bindings/example_scripts/simple_invoice_insert.py +++ b/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 +# @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 diff --git a/src/optional/python-bindings/example_scripts/simple_session.py b/src/optional/python-bindings/example_scripts/simple_session.py index 82ad457919..7b4ccf5ef0 100644 --- a/src/optional/python-bindings/example_scripts/simple_session.py +++ b/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, \ diff --git a/src/optional/python-bindings/example_scripts/simple_sqlite_create.py b/src/optional/python-bindings/example_scripts/simple_sqlite_create.py index 14759a4f2a..0811117810 100644 --- a/src/optional/python-bindings/example_scripts/simple_sqlite_create.py +++ b/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 diff --git a/src/optional/python-bindings/example_scripts/simple_test.py b/src/optional/python-bindings/example_scripts/simple_test.py index a1c3e5ef70..4775bc812c 100644 --- a/src/optional/python-bindings/example_scripts/simple_test.py +++ b/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 diff --git a/src/optional/python-bindings/example_scripts/test_imbalance_transaction.py b/src/optional/python-bindings/example_scripts/test_imbalance_transaction.py index 3092f7f8f1..4646848076 100644 --- a/src/optional/python-bindings/example_scripts/test_imbalance_transaction.py +++ b/src/optional/python-bindings/example_scripts/test_imbalance_transaction.py @@ -22,6 +22,11 @@ # # @author Mark Jenkins, ParIT Worker Co-operative +## @file +# @brief Test the transaction imbalace viewing mechanisms +# @author Mark Jenkins, ParIT Worker Co-operative +# @ingroup python-bindings-examples + from sys import argv from gnucash import Session, Transaction, Split, Account, GncNumeric, \ diff --git a/src/optional/python-bindings/function_class.py b/src/optional/python-bindings/function_class.py index df8623f8e6..1e80488d9c 100644 --- a/src/optional/python-bindings/function_class.py +++ b/src/optional/python-bindings/function_class.py @@ -20,6 +20,12 @@ # # @author Mark Jenkins, ParIT Worker Co-operative +## @file +# @brief Library for making python classes from a set of functions. +# @author Mark Jenkins, ParIT Worker Co-operative +# @author Jeff Green, ParIT Worker Co-operative +# @ingroup python-bindings + INSTANCE_ARGUMENT = "instance" class ClassFromFunctions(object): @@ -111,7 +117,7 @@ class ClassFromFunctions(object): 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 diff --git a/src/optional/python-bindings/glib.i b/src/optional/python-bindings/glib.i index db02f4c221..3760ae8e0f 100644 --- a/src/optional/python-bindings/glib.i +++ b/src/optional/python-bindings/glib.i @@ -22,6 +22,13 @@ * * @author Mark Jenkins, ParIT Worker Co-operative */ +/** @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 + @author Jeff Green, ParIT Worker Co-operative + @ingroup python-bindings */ + %typemap(in) gint8, gint16, gint32, gint64, gint, gshort, glong { $1 = ($1_type)PyInt_AsLong($input); diff --git a/src/optional/python-bindings/gnucash_business.py b/src/optional/python-bindings/gnucash_business.py index 5ccc2b709e..7695913271 100644 --- a/src/optional/python-bindings/gnucash_business.py +++ b/src/optional/python-bindings/gnucash_business.py @@ -20,6 +20,11 @@ # # @author Mark Jenkins, ParIT Worker Co-operative # @author Jeff Green, ParIT Worker Co-operative +## @file +# @brief High level python wrapper classes for the business parts of GnuCash +# @author Mark Jenkins, ParIT Worker Co-operative +# @author Jeff Green, ParIT Worker Co-operative +# @ingroup python-bindings import gnucash_core_c diff --git a/src/optional/python-bindings/gnucash_core.i b/src/optional/python-bindings/gnucash_core.i index 7d08f4b1b3..2dcc9b87d4 100644 --- a/src/optional/python-bindings/gnucash_core.i +++ b/src/optional/python-bindings/gnucash_core.i @@ -24,6 +24,21 @@ * @author Jeff Green, ParIT Worker Co-operative */ +/** @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 + @author Jeff Green, ParIT Worker Co-operative + @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 // 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 diff --git a/src/optional/python-bindings/gnucash_core.py b/src/optional/python-bindings/gnucash_core.py index aa7aeccde2..4b450b8976 100644 --- a/src/optional/python-bindings/gnucash_core.py +++ b/src/optional/python-bindings/gnucash_core.py @@ -21,6 +21,84 @@ # @author Mark Jenkins, ParIT Worker Co-operative # @author Jeff Green, ParIT Worker Co-operative +# 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 +# @author Jeff Green, ParIT Worker Co-operative +# @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 @@ class Session(GnuCashCoreClass): 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 @@ for error_name, error_value, error_name_after_prefix in \ 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 diff --git a/src/optional/python-bindings/timespec.i b/src/optional/python-bindings/timespec.i index d960d6a7a3..42bc6ee023 100644 --- a/src/optional/python-bindings/timespec.i +++ b/src/optional/python-bindings/timespec.i @@ -23,6 +23,12 @@ * @author Mark Jenkins, ParIT Worker Co-operative */ +/** @file + @brief SWIG interface file for type translation of Timespec types + @author Mark Jenkins, ParIT Worker Co-operative + @author Jeff Green, ParIT Worker Co-operative + @ingroup python-bindings */ + // A typemap for converting python dates to Timespec in functions that // require Timespec as an argument %typemap(in) Timespec {