r19981 - gnucash/trunk/src - Bug #637346: A second step towards doxygen python-bindings docs
Christian Stimming
cstim at code.gnucash.org
Mon Dec 27 10:36:15 EST 2010
Author: cstim
Date: 2010-12-27 10:36:15 -0500 (Mon, 27 Dec 2010)
New Revision: 19981
Trac: http://svn.gnucash.org/trac/changeset/19981
Modified:
gnucash/trunk/src/base-typemaps.i
gnucash/trunk/src/doc/Makefile.am
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/price_database_example.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: A second step towards doxygen python-bindings docs
Patch by Christoph Holtermann
Modified: gnucash/trunk/src/base-typemaps.i
===================================================================
--- gnucash/trunk/src/base-typemaps.i 2010-12-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/base-typemaps.i 2010-12-27 15:36:15 UTC (rev 19981)
@@ -1,6 +1,6 @@
/** @file
- @brief interface file for SWIG, used by python-bindings and scheme(?).
- @addtogroup python-bindings
+ @brief interface file for SWIG, used by python-bindings and scheme/guile.
+ @addtogroup python_bindings
*/
/* Not sure why SWIG doesn't figure this out. */
Modified: gnucash/trunk/src/doc/Makefile.am
===================================================================
--- gnucash/trunk/src/doc/Makefile.am 2010-12-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/doc/Makefile.am 2010-12-27 15:36:15 UTC (rev 19981)
@@ -28,7 +28,8 @@
guid.txt \
qif.txt \
generic-druid-framework.txt \
- user-prefs-howto.txt
+ user-prefs-howto.txt \
+ python-bindings-doxygen.py
docdir = ${GNC_DOC_INSTALL_DIR}
Modified: gnucash/trunk/src/doc/doxygen_main_page.c
===================================================================
--- gnucash/trunk/src/doc/doxygen_main_page.c 2010-12-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/doc/doxygen_main_page.c 2010-12-27 15:36:15 UTC (rev 19981)
@@ -50,13 +50,13 @@
- \ref plugindesign
- \ref pricedocs
- \ref gnucashextension
+- \ref python_bindings_page
- \ref qif
- \ref backendapi
- \ref budgetplan
- \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-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/__init__.py 2010-12-27 15:36:15 UTC (rev 19981)
@@ -8,4 +8,4 @@
# @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
+# @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-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/account_analysis.py 2010-12-27 15:36:15 UTC (rev 19981)
@@ -24,7 +24,7 @@
## @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
+# @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-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/change_tax_code.py 2010-12-27 15:36:15 UTC (rev 19981)
@@ -2,7 +2,7 @@
## @file
# @brief Output all the credits and debits on an account
-# @ingroup python-bindings-examples
+# @ingroup python_bindings_examples
from gnucash import Session, Account
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-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/new_book_with_opening_balances.py 2010-12-27 15:36:15 UTC (rev 19981)
@@ -26,7 +26,7 @@
# @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
+# @ingroup python_bindings_examples
from gnucash import Session, Account, Transaction, Split, GncNumeric
from gnucash.gnucash_core_c import \
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-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/priceDB_test.py 2010-12-27 15:36:15 UTC (rev 19981)
@@ -13,7 +13,7 @@
## @file
# @brief Test file for price database stuff
# @author Mike Evans
-# @ingroup python-bindings-examples
+# @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/price_database_example.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/example_scripts/price_database_example.py 2010-12-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/price_database_example.py 2010-12-27 15:36:15 UTC (rev 19981)
@@ -8,8 +8,13 @@
# OR: export PYTHONPATH=$HOME/progs/lib/python2.6/site-packages
# Then: gnucash-env ipython
# The account file is not saved but always use a disposable copy.
-# Thanks for contributions by Christoph Holtermann
+# Thanks for contributions by Christoph Holtermann and Mark Jenkins
+## @file
+# @brief Test file for price database stuff
+# @author Mike Evans, Christoph Holtermann, Mark Jenkins
+# @ingroup python_bindings_examples
+
from gnucash import Session
# -------------------------------------------
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-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/simple_book.py 2010-12-27 15:36:15 UTC (rev 19981)
@@ -2,7 +2,7 @@
## @file
# @brief Simple example for a book
-# @ingroup python-bindings-examples
+# @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-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/simple_business_create.py 2010-12-27 15:36:15 UTC (rev 19981)
@@ -36,7 +36,7 @@
## @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
+# @ingroup python_bindings_examples
from os.path import abspath
from sys import argv
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-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/simple_invoice_insert.py 2010-12-27 15:36:15 UTC (rev 19981)
@@ -36,7 +36,7 @@
## @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
+# @ingroup python_bindings_examples
from gnucash import Session, GUID, GncNumeric
from gnucash.gnucash_business import Customer, Invoice, Entry
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-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/simple_session.py 2010-12-27 15:36:15 UTC (rev 19981)
@@ -1,7 +1,7 @@
#!/usr/bin/env python
## @file
# @brief Example Script simple session
-# @ingroup python-bindings-examples
+# @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-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/simple_sqlite_create.py 2010-12-27 15:36:15 UTC (rev 19981)
@@ -1,7 +1,7 @@
#!/usr/bin/env python
## @file
# @brief Example Script simple sqlite create
-# @ingroup python-bindings-examples
+# @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-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/simple_test.py 2010-12-27 15:36:15 UTC (rev 19981)
@@ -1,7 +1,7 @@
#!/usr/bin/env python
## @file
# @brief Creates a basic set of accounts and a couple of transactions
-# @ingroup python-bindings-example
+# @ingroup python_bindings_examples
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-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/example_scripts/test_imbalance_transaction.py 2010-12-27 15:36:15 UTC (rev 19981)
@@ -25,7 +25,7 @@
## @file
# @brief Test the transaction imbalace viewing mechanisms
# @author Mark Jenkins, ParIT Worker Co-operative <mark at parit.ca>
-# @ingroup python-bindings-examples
+# @ingroup python_bindings_examples
from sys import argv
Modified: gnucash/trunk/src/optional/python-bindings/function_class.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/function_class.py 2010-12-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/function_class.py 2010-12-27 15:36:15 UTC (rev 19981)
@@ -24,7 +24,7 @@
# @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
+# @ingroup python_bindings
INSTANCE_ARGUMENT = "instance"
Modified: gnucash/trunk/src/optional/python-bindings/glib.i
===================================================================
--- gnucash/trunk/src/optional/python-bindings/glib.i 2010-12-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/glib.i 2010-12-27 15:36:15 UTC (rev 19981)
@@ -27,7 +27,7 @@
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 */
+ @ingroup python_bindings */
%typemap(in) gint8, gint16, gint32, gint64, gint, gshort, glong {
Modified: gnucash/trunk/src/optional/python-bindings/gnucash_business.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/gnucash_business.py 2010-12-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/gnucash_business.py 2010-12-27 15:36:15 UTC (rev 19981)
@@ -24,7 +24,7 @@
# @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
+# @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-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/gnucash_core.i 2010-12-27 15:36:15 UTC (rev 19981)
@@ -26,17 +26,19 @@
/** @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
+
+ This file is processed by SWIG and the resulting files are gnucash_core.c and gnucash_core_c.py.
+ Have a look at the includes to see which parts of the GnuCash source SWIG takes as input.
@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
+ @ingroup python_bindings
@file gnucash_core.c
@brief SWIG output file.
- @ingroup python-bindings
+ @ingroup python_bindings
@file gnucash_core_c.py
@brief SWIG output file.
- @ingroup python-bindings
+ @ingroup python_bindings
*/
%feature("autodoc", "1");
Modified: gnucash/trunk/src/optional/python-bindings/gnucash_core.py
===================================================================
--- gnucash/trunk/src/optional/python-bindings/gnucash_core.py 2010-12-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/gnucash_core.py 2010-12-27 15:36:15 UTC (rev 19981)
@@ -26,79 +26,8 @@
# @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
+# @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 \
@@ -143,7 +72,7 @@
def __init__(self, book_uri=None, ignore_lock=False, is_new=False,
force_new= False):
- """A convenient contructor that allows you to specify a book URI,
+ """A convenient constructor that allows you to specify a book URI,
begin the session, and load the book.
This can give you the power of calling
@@ -157,7 +86,7 @@
is_new is passed to qof_session_begin as the argument create,
and force_new as the argument force. Is_new will create a new
database or file; force will force creation even if it will
- destroy and existing dataset.
+ destroy an existing dataset.
ignore_lock is passed to qof_session_begin's argument of the
same name and is used to break an existing lock on a dataset.
Modified: gnucash/trunk/src/optional/python-bindings/timespec.i
===================================================================
--- gnucash/trunk/src/optional/python-bindings/timespec.i 2010-12-26 20:05:29 UTC (rev 19980)
+++ gnucash/trunk/src/optional/python-bindings/timespec.i 2010-12-27 15:36:15 UTC (rev 19981)
@@ -27,7 +27,7 @@
@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 */
+ @ingroup python_bindings */
// A typemap for converting python dates to Timespec in functions that
// require Timespec as an argument
More information about the gnucash-changes
mailing list