Doxygen and texi documentation cleanup

.gitignore

@@ -96,11 +96,6 @@ libgnucash/core-utils/test/test-gnc-uri-utils
 libgnucash/core-utils/test/test-resolve-file-path
 libgnucash/doc/doxygen.cfg
 libgnucash/doc/doxygen.log
-libgnucash/doc/design/gnucash-design.info
-libgnucash/doc/design/mdate-sh
-libgnucash/doc/design/stamp-vti
-libgnucash/doc/design/texinfo.tex
-libgnucash/doc/design/version.texi
 libgnucash/doc/html/
 libgnucash/engine/gncla-dir.h
 libgnucash/engine/gnucash

CMakeLists.txt

@@ -843,6 +843,13 @@ add_definitions (-DHAVE_CONFIG_H)
 set (CONFIG_H ${CMAKE_CURRENT_BINARY_DIR}/common/config.h)
 configure_file (${CMAKE_CURRENT_SOURCE_DIR}/common/config.h.cmake.in ${CONFIG_H})
 
+# The doxygen developer documentation
+find_program(DOXYGEN doxygen)
+if (NOT ${DOXYGEN} STREQUAL "DOXYGEN-NOTFOUND")
+  configure_file(doxygen.cfg.in doxygen.cfg)
+  add_custom_target(doc ${DOXYGEN} doxygen.cfg)
+endif()
+
 # The subdirectories
 add_subdirectory (borrowed)
 add_subdirectory (data)
@@ -884,7 +891,10 @@ endif()
 set(DIST_FILE "${PACKAGE_PREFIX}.tar")
 
 set(toplvl_DIST_local ${gnucash_DOCS}
-  CMakeLists.txt README)
+    doxygen.cfg.in
+    doxygen_main_page.c
+    CMakeLists.txt
+    README)
 
 
 set_local_dist(toplvl_DIST ${toplvl_DIST_local})

HACKING

@@ -10,11 +10,6 @@ In addition to this file, you should read the README file, which
 explains the details of getting the git source, building GnuCash,
 and creating patches for submission.
 
-The src/doc/design directory contains a preliminary design document
-which you should read as well. You should also feel free to hack on
-the design document.
-
-
 Coding Style Conventions
 ------------------------
 Please refer to https://wiki.gnucash.org/wiki/CodingStandard.
@@ -109,6 +104,50 @@ This file needs to be cleaned up in two ways:
 2/ There are a bunch of suppressions which need to not be suppressions, but
    instead just not be generated by valgrind.
 
+Using Callgrind with GnuCash
+----------------------------
+In order to debug with callgrind, you need to add a couple of code
+fragments around the section of code you are profiling.  This is
+easiest if you can find the function that invokes the routine(s) you
+want to profile, add the following code around the function call of
+interest.
+
+Add the following to the start of the file:
+
+#include <valgrind/callgrind.h>
+
+Add the following to the start of the calling function:
+
+static GTimeVal start, end;
+
+Add the following just before the function of interest:
+
+g_print("Start timing.\n");
+g_get_current_time(&start);
+CALLGRIND_START_INSTRUMENTATION();
+CALLGRIND_TOGGLE_COLLECT();
+
+Add the following just after the function of interest:
+
+CALLGRIND_TOGGLE_COLLECT();
+CALLGRIND_STOP_INSTRUMENTATION();
+g_get_current_time(&end);
+if (start.tv_usec > end.tv_usec) {
+  end.tv_usec += 1000000;
+  end.tv_sec  -= 1;
+}
+g_print("Callgrind enabled for %d.%6d seconds.\n",
+        (int)(end.tv_sec - start.tv_sec),
+        (int)(end.tv_usec - start.tv_usec));
+
+You will need to recompile, and then run the 'gnucash-valgrind'
+wrapper script instead of the normal 'gnucash' script.
+
+NOTE: Version 3.2 of valgrind has changed the above macros to no
+longer take an argument. In order to compile with this version of
+valgrind you will need to remove the trailing parentheses and
+semicolon.
+
 
 Look up exported and imported symbols
 -------------------------------------

README.dependencies

@@ -105,13 +105,6 @@ Libraries/Deps
                                                  to the main menu bar instead
                                                  of one on the window.
 
-  makeinfo                                       Not really needed, it
-                                                 just builds the
-                                                 mostly obsolete
-                                                 design documentation
-                                                 (superceded for the
-                                                 most part in Doxygen
-                                                 docs).
   doxygen                                        For building the Doxygen API
                                                  documentation.
 

bindings/guile/date-utilities.scm

@@ -690,9 +690,7 @@ Defaulting to today."))
   (current-time))
 
 
-;; There is no GNC:RELATIVE-DATES list like the one mentioned in
-;; gnucash-design.info, is there? Here are the currently defined
-;; items, loosely grouped.
+;; Here are the currently defined items, loosely grouped.
 ;;today
 ;;start-cal-year end-cal-year start-prev-year end-prev-year
 ;;start-this-month end-this-month start-prev-month end-prev-month

bindings/python/gnucash_core.py

@@ -22,6 +22,135 @@
 # @author Jeff Green,   ParIT Worker Co-operative <[email protected]>
 
 # The following is for doxygen
+
+## @defgroup python_bindings Python Bindings Module
+#  Also have a look at the page @ref python_bindings_page.
+
+## @defgroup python_bindings_examples Python Bindings Examples Module
+#  @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.
+#
+#   In the source tree they are located at bindings/python.
+#
+#   To enable them in the compilation process you have to add  -DWITH_PYTHON=ON
+#   to the call of cmake.
+#
+#   As a starting point have a look at the \link python_bindings_examples example-scripts\endlink.
+#
+#   @section possibilities What can Python Bindings be used for ?
+#
+#   The python bindings supply the ability to access a wide range of the core functions of GnuCash. You
+#   can read and write Transactions, Commodities, Lots, access the business stuff... You gain the ability
+#   to manipulate your financial data with a flexible scripting language.
+#
+#   Not everything GnuCash can is possible to access though. The bindings focus on basic accounting functions.
+#   Have a look at the examples to get an impression.
+#
+#   Some functions are broken because they have not been wrapped properly. They may crash the program or return unaccessible values.
+#   Please file a bug report if you find one to help support the development process.
+#
+#   @section python_bindings_section Principles
+#   The python-bindings are generated using SWIG from parts of the source-files of GnuCash.
+#
+#   @note Python-scripts should not be executed while GnuCash runs. GnuCash is designed as
+#   a single user application with only one program accessing the data at one time. You can force your
+#   access but that may corrupt data. Maybe one day that may change but for the moment there is no active development on that.
+#
+#   @subsection swigworks What SWIG does
+#
+#   SWIG extracts information from the c-sources and provides access to the structures
+#   to python. It's work is controlled by interface files :
+#
+#   @li gnucash_core.i
+#   @li timespec.i
+#   @li glib.i
+#   @li @link base-typemaps.i src/base-typemaps.i @endlink This file is shared with Guile.
+#
+#   it outputs:
+#
+#   @li gnucash_core.c
+#   @li gnucash_core_c.py
+#
+#   If you have generated your own local doxygen documentation (by "make doc") after having compiled the python-bindings, doxygen
+#   will include SWIGs output-files.
+#   It's actually quite interesting to have a look at them through doxygen, because they contain all that you can
+#   access from python.
+#
+#   This c-style-api is the bottom layer. It is a quite raw extract and close to the original source. Some more details are described further down.
+#
+#   For some parts there is a second layer of a nice pythonic interface. It is declared
+#   in
+#   @li gnucash_core.py and
+#   @li gnucash_business.py.
+#   @li function_class.py contains helper functions for that.
+#
+#   @section howto How to use the Python bindings
+#   @subsection 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
+#
+#   Here you will find easy to use things. But sometimes - and at the current level rather sooner than
+#   later - you may be forced to search for solutions at the :
+#
+#   @subsection 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.
+#
+#   You will find a lot of pointers here which you can just ignore if input and output of the function have the
+#   same type.
+#
+#   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 that it is fed with and translates it. Not everything
+#   is a working translation, because not everything has been worked through. At this point you are getting closer to the developers who you can
+#   contact at the mailing-list [email protected]. There may be a workaround. Maybe the problem can only be fixed by changing SWIGs input
+#   files to correctly translate the c-source. Feel free to post a question at the developers list. It may awaken the interest of someone who creates
+#   some more beautiful python-interfaces.
+#
+#   @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 (Further) documentation
+#
+#   @li The documentation you just read uses doxygen. It collects documentation in GnuCash's sources. Besides that there is
+#   @li the classic python-documentation using help() and docstrings. Have a look at both.
+#   @li There is a page in the GnuCash wiki at https://wiki.gnucash.org/wiki/Python
+#   @li You may also have a look into the archives of [email protected].
+#   @li On Bugzilla there is also some interesting talk regarding the development process.
+#   @li Then you can use the abilities of git to see the history of the code by @code git log @endcode done in the directory of the python-bindings.
+#
+#   @section pytodo To-Do
+#   @li Work out the relation of scheme/guile and python-bindings
+#   @li maybe join python_bindings_page and group
+#   @li work on the structure of the documentation to make it more clear
+#   @li try to make SWIG include the documentation of the c-source
+#   @li make function-links in SWIG-generated files work.
+#   @li some words to the tests
+#
+# @author Christoph Holtermann
+# @date December 2010
+
+
 ## @file
 #  @brief High level python wrapper classes for the core parts of GnuCash
 #  @author Mark Jenkins, ParIT Worker Co-operative <[email protected]>