pygccxml-commit

[pygccxml-commit] SF.net SVN: pygccxml: [323] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 323
Author:   roman_yakovenko
Date:     2006-07-19 22:31:26 -0700 (Wed, 19 Jul 2006)
ViewCVS:  http://svn.sourceforge.net/pygccxml/?rev=323&view=rev

Log Message:
-----------
moving API docs to "documentation" directory

Added Paths:
-----------
    pyplusplus_dev/docs/documentation/apidocs/
    pyplusplus_dev/docs/documentation/apidocs/www_configuration.py
Added: pyplusplus_dev/docs/documentation/apidocs/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/apidocs/www_configuration.py	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/apidocs/www_configuration.py	2006-07-20 05:31:26 UTC (rev 323)
@@ -0,0 +1,2 @@
+name = 'API docs'
+main_html_file = 'index.html'
\ No newline at end of file


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

[pygccxml-commit] SF.net SVN: pygccxml: [326] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 326
Author:   roman_yakovenko
Date:     2006-07-19 23:50:38 -0700 (Wed, 19 Jul 2006)
ViewCVS:  http://svn.sourceforge.net/pygccxml/?rev=326&view=rev

Log Message:
-----------
adding "how to ... ?" to documentation

Modified Paths:
--------------
    pyplusplus_dev/docs/documentation/index.rest
    pyplusplus_dev/docs/documentation/www_configuration.py

Added Paths:
-----------
    pyplusplus_dev/docs/documentation/how_to.rest
Added: pyplusplus_dev/docs/documentation/how_to.rest
===================================================================
--- pyplusplus_dev/docs/documentation/how_to.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/how_to.rest	2006-07-20 06:50:38 UTC (rev 326)
@@ -0,0 +1,124 @@
+============
+How to ... ?
+============
+
+.. contents:: Table of contents
+
+----------------------------------------
+How to add custom exception translation?
+----------------------------------------
+::
+
+  struct my_exception{
+    ...
+    const std::string& error() const;
+    ...
+  }
+
+First of all lets define ``translate`` function:
+
+::
+
+  translate_code = \
+  """   
+    void translate(const my_exception &exception){
+        PyErr_SetString( PyExc_RuntimeError, exception.error().c_str() );
+    }
+  """
+
+::
+
+  mb.add_declaration_code( translate_code )
+
+
+Now we should register it:
+
+::
+
+  registration_code = "boost::python::register_exception_translator<my_exception>(&translate);"
+  mb.add_registration_code( registration_code )
+
+Small usage advice.
+-------------------
+
+`pyplusplus`_ allows you to define a query that will return you all exception classes:
+
+::
+
+  mb = module_builder_t( ... )
+  exception_classes = mb.decls( lambda decl: decl.name.endswith( 'exception' ) )
+
+Now you can iterate on ``exception_classes``, generate and register translate 
+code for every class.
+
+That's all.
+
+-------------------------------------------------------
+How to expose function, which has hand-written wrapper?
+-------------------------------------------------------
+::
+
+  struct window_t{
+      ...
+      void get_size( int& height, int& widht ) const;
+      ...
+  };
+
+You can not expose ``get_size`` function as is - ``int`` is immutable type in 
+Python. So, we need to create a wrapper to the function:
+::
+
+  boost::python::tuple get_size_wrapper( const window_t& win ){
+      int height(0), width( 0 );
+      win.get_size( height, widht );
+      return boost::python::make_tuple( height, width );
+  }
+
+::
+
+  class_<window_t>( ... )
+      .def( "get_size", &get_size_wrapper )
+      ...
+  ;
+
+Now, after you know how this problem is solved. I will show how this solution 
+could be integrated with `pyplusplus`_.
+
+
+::
+
+  wrapper_code = \
+  """
+     static boost::python::tuple get_size( const window_t& win ){
+        int height(0), width( 0 );
+        win.get_size( height, widht );
+        return boost::python::make_tuple( height, width );
+    }
+  """
+
+::
+
+  registration_code = 'def( "get_size", &%s::get_size )' % window.wrapper_alias
+
+::
+
+  mb = module_builder_t( ... )
+  window = mb.class_( "window_t" )
+  window.member_function( "get_size" ).exclude()
+  window.add_wrapper_code( wrapper_code )
+  window.add_code( registration_code )
+
+That's all. 
+
+.. _`pyplusplus` : ./../pyplusplus.html
+.. _`boost.python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

Modified: pyplusplus_dev/docs/documentation/index.rest
===================================================================
--- pyplusplus_dev/docs/documentation/index.rest	2006-07-20 06:23:22 UTC (rev 325)
+++ pyplusplus_dev/docs/documentation/index.rest	2006-07-20 06:50:38 UTC (rev 326)
@@ -4,8 +4,13 @@
 
 .. contents:: Table of contents
 
-* `STL Containers`_ 
+----
+XXXX
+----
 
+ ???
+
+
 .. _`STL Containers` : ./containers.html
       
 

Modified: pyplusplus_dev/docs/documentation/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/www_configuration.py	2006-07-20 06:23:22 UTC (rev 325)
+++ pyplusplus_dev/docs/documentation/www_configuration.py	2006-07-20 06:50:38 UTC (rev 326)
@@ -1,3 +1,5 @@
-name = 'C++ containers'
-main_html_file = 'containers.html'
-files_to_skip = ['indexing_suite_v2.html']
\ No newline at end of file
+name = 'documentation'
+main_html_file = 'index.html'
+files_to_skip = ['indexing_suite_v2.html']
+names = { 'containers' : 'STL containers'
+          , 'how_to' : 'how to ... ?' }
\ No newline at end of file


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

[pygccxml-commit] SF.net SVN: pygccxml: [333] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 333
Author:   roman_yakovenko
Date:     2006-07-20 12:12:15 -0700 (Thu, 20 Jul 2006)
ViewCVS:  http://svn.sourceforge.net/pygccxml/?rev=333&view=rev

Log Message:
-----------
adding documentation for documentation strings

Modified Paths:
--------------
    pyplusplus_dev/docs/documentation/www_configuration.py

Added Paths:
-----------
    pyplusplus_dev/docs/documentation/doc_string.rest
Added: pyplusplus_dev/docs/documentation/doc_string.rest
===================================================================
--- pyplusplus_dev/docs/documentation/doc_string.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/doc_string.rest	2006-07-20 19:12:15 UTC (rev 333)
@@ -0,0 +1,75 @@
+====================
+Documentation string
+====================
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+`pyplusplus`_ provides a convenient way to export documentation from C++ source
+files as `Python`_ `documentation string`_
+
+---------------
+API description
+---------------
+
+::
+
+  mb = module_builder_t( ... )
+  my_class = mb.class_( 'my_class' )
+  my_class.documentation = '"very helpful documentation string"'
+  my_class.member_function( "do_nothing" ).documentation = \
+      '"This function does nothing."'
+
+In `pyplusplus`_ every class, that describes C++ declarations has ``documentation``
+property. This property should contain valid C++ string or ``None``.
+
+`boost.python`_ not always provides functionality, that exports documentation string.
+In those cases, `pyplusplus`_ will not generate documentation string.
+
+Also the previous method is pretty clear, it is not practical. There should be a
+better way, to complete the task. Lets take a look on
+``module_builder_t.build_code_creator`` method. One of the arguments of this method
+is ``doc_extractor``.
+
+
+``doc_extractor`` is a callable object, that takes one argument - reference to declaration.
+
+::
+
+  def doc_extractor( decl ):
+    ...
+
+How it could help? Every declaration has location information:
+
+   * ``decl.location.file_name`` - absolute file name, where this declaration
+     has been declared.
+
+   * ``decl.location.line`` - line number.
+
+So, you can go to the source file and to extract declaration from it.
+`pyplusplus`_ will call ``doc_extractor`` on every exported declaration.
+
+Now, when I think you understand what functionality `pyplusplus`_ provides.
+It is a time to say what functionality is missing. `pyplusplus`_ does not
+provide any documentation extractor. It is not completely true. You can find
+document extractor for `doxygen`_ format in ``contrib/doc_extractors`` directory.
+It has been contributed by Georgiy Dernovoy.
+
+
+.. _`doxygen` : http://www.stack.nl/~dimitri/doxygen/
+.. _`documentation string` : http://docs.python.org/tut/node6.html#SECTION006760000000000000000
+.. _`pyplusplus` : ./../pyplusplus.html
+.. _`boost.python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

Modified: pyplusplus_dev/docs/documentation/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/www_configuration.py	2006-07-20 17:50:37 UTC (rev 332)
+++ pyplusplus_dev/docs/documentation/www_configuration.py	2006-07-20 19:12:15 UTC (rev 333)
@@ -1,5 +1,7 @@
 name = 'documentation'
 main_html_file = 'index.html'
-files_to_skip = ['indexing_suite_v2.html']
-names = { 'containers' : 'STL containers'
-          , 'how_to' : 'how to ... ?' }
\ No newline at end of file
+files_to_skip = ['indexing_suite_v2.html']
+names = { 'containers' : 'STL containers'
+          , 'how_to' : 'how to ... ?'
+          , 'doc_string' : 'documentation string'
+}
\ No newline at end of file


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

[pygccxml-commit] SF.net SVN: pygccxml: [351] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 351
Author:   roman_yakovenko
Date:     2006-07-26 07:24:17 -0700 (Wed, 26 Jul 2006)
ViewCVS:  http://svn.sourceforge.net/pygccxml/?rev=351&view=rev

Log Message:
-----------
adding documentation, that will describe how to add custom code to generated one

Modified Paths:
--------------
    pyplusplus_dev/docs/documentation/www_configuration.py

Added Paths:
-----------
    pyplusplus_dev/docs/documentation/inserting_code.rest
Added: pyplusplus_dev/docs/documentation/inserting_code.rest
===================================================================
--- pyplusplus_dev/docs/documentation/inserting_code.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/inserting_code.rest	2006-07-26 14:24:17 UTC (rev 351)
@@ -0,0 +1,109 @@
+=============
+Inerting code
+=============
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+`pyplusplus`_ is not a magician! Sometimes there is a need to modify or add code
+to generated file(s). This document will describe how you can insert your code
+to almost any place.
+
+-----------
+Source code
+-----------
+
+I am going to introduce C++ class ``world_t``. I will use it for all explanations.
+
+::
+
+  struct world_t {
+    void set(std::string msg) { this->msg = msg; }
+    std::string greet() { return msg; }
+    
+    std::string msg;
+  };
+
+If run `pyplusplus`_ on this code it will generate next `boost.python`_ code:
+
+::
+
+  bp::class_< world_t, boost::noncopyable >( "world_t" )    
+      .def( 
+          "greet"
+          , &::world_t::greet
+          , bp::default_call_policies() )    
+      .def( 
+          "set"
+          , &::world_t::set
+          , ( bp::arg("msg") )
+          , bp::default_call_policies() )    
+      .def_readwrite( "msg", &world_t::msg );
+
+It is possible, that `pyplusplus`_ will generate code, that expose class 
+``world_t``, that will look different. The second form is more verbose, but it 
+provides solution for few problems. 
+
+::
+
+  { //::world_t
+      typedef bp::class_< world_t, boost::noncopyable > world_t_exposer_t;
+      world_t_exposer_t world_t_exposer = world_t_exposer_t( "world_t" );
+      bp::scope world_t_scope( world_t_exposer );
+      { //::world_t::greet
+      
+          typedef ::std::string ( ::world_t::*function_ptr_t )(  ) ;
+          
+          world_t_exposer.def( 
+              "greet"
+              , function_ptr_t( &::world_t::greet )
+              , bp::default_call_policies() );
+      
+      }
+      { //::world_t::set
+      
+          typedef void ( ::world_t::*function_ptr_t )( ::std::string ) ;
+          
+          world_t_exposer.def( 
+              "set"
+              , function_ptr_t( &::world_t::set )
+              , ( bp::arg("msg") )
+              , bp::default_call_policies() );
+      
+      }
+      world_t_exposer.def_readwrite( "msg", &world_t::msg );
+  }
+
+
+--------------------
+Insert code to class
+--------------------
+
+``class_t`` declaration defines ``add_code( self, code, works_on_instance=True )``
+method.
+
+::
+
+  mb = module_builder_t( ... )
+  my_class = mb.class_( 'my_class' )
+  my_class.add_code( C++ code )
+
+
+
+
+.. _`pyplusplus` : ./../pyplusplus.html
+.. _`pygccxml` : ./../../pygccxml/pygccxml.html
+.. _`boost.python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

Modified: pyplusplus_dev/docs/documentation/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/www_configuration.py	2006-07-26 13:08:20 UTC (rev 350)
+++ pyplusplus_dev/docs/documentation/www_configuration.py	2006-07-26 14:24:17 UTC (rev 351)
@@ -3,5 +3,6 @@
 files_to_skip = ['indexing_suite_v2.html']
 names = { 'containers' : 'STL containers'
           , 'how_to' : 'how to ... ?'
-          , 'doc_string' : 'documentation string'
+          , 'doc_string' : 'documentation string'
+          , 'inserting_code' : 'inserting code'
 }
\ No newline at end of file


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

[pygccxml-commit] SF.net SVN: pygccxml: [354] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 354
Author:   roman_yakovenko
Date:     2006-07-27 11:47:29 -0700 (Thu, 27 Jul 2006)
ViewCVS:  http://svn.sourceforge.net/pygccxml/?rev=354&view=rev

Log Message:
-----------
fixing small bugs

Modified Paths:
--------------
    pyplusplus_dev/docs/documentation/feedback.rest
    pyplusplus_dev/pyplusplus/_logging_/__init__.py
Modified: pyplusplus_dev/docs/documentation/feedback.rest
===================================================================
--- pyplusplus_dev/docs/documentation/feedback.rest	2006-07-27 09:56:53 UTC (rev 353)
+++ pyplusplus_dev/docs/documentation/feedback.rest	2006-07-27 18:47:29 UTC (rev 354)
@@ -61,7 +61,8 @@
 
 In previous paragraph, I described pretty usefull functionality. What should be
 done in order to enable it? - *Nothing!* By default, `pyplusplus`_ prints only 
-important messages to ``stdout``. 
+important messages to ``stdout``. More over it prints them onle for declarations
+that are going to be exported.
 
 `pyplusplus`_ uses standard `logging`_ package to write all user messages. By 
 default, messages with ``DEBUG`` level will be skipped, all other messages will

Modified: pyplusplus_dev/pyplusplus/_logging_/__init__.py
===================================================================
--- pyplusplus_dev/pyplusplus/_logging_/__init__.py	2006-07-27 09:56:53 UTC (rev 353)
+++ pyplusplus_dev/pyplusplus/_logging_/__init__.py	2006-07-27 18:47:29 UTC (rev 354)
@@ -28,4 +28,4 @@
     module_builder = _create_logger_( 'pyplusplus.module_builder' )
     #root logger exists for configuration purpose only
     root = logging.getLogger( 'pyplusplus' )
-    all = [ root, file_writer, module_builder ]
+    all = [ root, file_writer, module_builder, declarations ]


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

[pygccxml-commit] SF.net SVN: pygccxml: [364] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 364
Author:   roman_yakovenko
Date:     2006-07-29 13:02:42 -0700 (Sat, 29 Jul 2006)
ViewCVS:  http://svn.sourceforge.net/pygccxml/?rev=364&view=rev

Log Message:
-----------
adding "insert code" documentation 

Modified Paths:
--------------
    pyplusplus_dev/docs/documentation/feedback.rest
    pyplusplus_dev/docs/documentation/inserting_code.rest
Modified: pyplusplus_dev/docs/documentation/feedback.rest
===================================================================
--- pyplusplus_dev/docs/documentation/feedback.rest	2006-07-29 13:02:39 UTC (rev 363)
+++ pyplusplus_dev/docs/documentation/feedback.rest	2006-07-29 20:02:42 UTC (rev 364)
@@ -120,7 +120,7 @@
            declarations = _create_logger_( 'pyplusplus.declarations' )
            module_builder = _create_logger_( 'pyplusplus.module_builder' )  
            root = logging.getLogger( 'pyplusplus' )
-           all = [ root, file_writer, module_builder ]
+           all = [ root, file_writer, module_builder, declarations ]
 
    You can use these references in the ``logging`` package to complete
    your task of adjusting individual loggers.

Modified: pyplusplus_dev/docs/documentation/inserting_code.rest
===================================================================
--- pyplusplus_dev/docs/documentation/inserting_code.rest	2006-07-29 13:02:39 UTC (rev 363)
+++ pyplusplus_dev/docs/documentation/inserting_code.rest	2006-07-29 20:02:42 UTC (rev 364)
@@ -8,92 +8,154 @@
 Introduction
 ------------
 
-`pyplusplus`_ is not a magician! Sometimes there is a need to modify or add code
-to generated file(s). This document will describe how you can insert your code
-to almost any place.
+`pyplusplus`_ is not a magician! Sometimes there is a need to add code to 
+generated file(s). This document will describe how you can insert your code to 
+almost any place. 
 
------------
-Source code
------------
+---------------------
+Insert code to module
+---------------------
 
-I am going to introduce C++ class ``world_t``. I will use it for all explanations.
+Almost every ``boost.python`` module has next structure:
 
 ::
 
-  struct world_t {
-    void set(std::string msg) { this->msg = msg; }
-    std::string greet() { return msg; }
-    
-    std::string msg;
-  };
+  //declarations code
+  ...
+  BOOST_PYTHON_MODULE(X)
+  {
+    //registration code
+    ...
+  }
+  
+Using ``module_builder_t`` you can add code to declaration and registration 
+sections. More over you can add the code to head or tail of the section. 
+``module_builder_t`` class provides API, that will help you to complete the task:
 
-If run `pyplusplus`_ on this code it will generate next `boost.python`_ code:
+* ``add_declaration_code( self, code, tail=True )``
 
-::
+  This function will add a code to the declaration section. If you want to add
+  the code to the head of the section, pass ``tail=False`` to the method.
+  
+* ``add_registration_code( self, code, tail=True )``
 
-  bp::class_< world_t, boost::noncopyable >( "world_t" )    
-      .def( 
-          "greet"
-          , &::world_t::greet
-          , bp::default_call_policies() )    
-      .def( 
-          "set"
-          , &::world_t::set
-          , ( bp::arg("msg") )
-          , bp::default_call_policies() )    
-      .def_readwrite( "msg", &world_t::msg );
+  This function will ass a code to the registration section. If you want to add
+  the code to the head of the section, pass ``tail=False`` to the method.
+  
+Both these methods have same precondition: they should be called after 
+``build_code_creator`` method has been called. Both these methods work directly
+with code creators tree, hence the precondition.
 
-It is possible, that `pyplusplus`_ will generate code, that expose class 
-``world_t``, that will look different. The second form is more verbose, but it 
-provides solution for few problems. 
+Example
+-------
 
 ::
 
-  { //::world_t
-      typedef bp::class_< world_t, boost::noncopyable > world_t_exposer_t;
-      world_t_exposer_t world_t_exposer = world_t_exposer_t( "world_t" );
-      bp::scope world_t_scope( world_t_exposer );
-      { //::world_t::greet
-      
-          typedef ::std::string ( ::world_t::*function_ptr_t )(  ) ;
-          
-          world_t_exposer.def( 
-              "greet"
-              , function_ptr_t( &::world_t::greet )
-              , bp::default_call_policies() );
-      
-      }
-      { //::world_t::set
-      
-          typedef void ( ::world_t::*function_ptr_t )( ::std::string ) ;
-          
-          world_t_exposer.def( 
-              "set"
-              , function_ptr_t( &::world_t::set )
-              , ( bp::arg("msg") )
-              , bp::default_call_policies() );
-      
-      }
-      world_t_exposer.def_readwrite( "msg", &world_t::msg );
-  }
+  mb = module_builder_t( ... )
+  mb.build_code_creator( ... )
+  mb.add_declaration_code( '//just a comment' )
+  mb.add_registration_code( '//another comment', False ) #adding code to the head
+  
 
-
 --------------------
 Insert code to class
 --------------------
 
-``class_t`` declaration defines ``add_code( self, code, works_on_instance=True )``
-method.
+``class_t`` declaration defines few methods adds user code to the generated one.
+Lets take a look on next use case:
 
 ::
 
+  struct window_t{
+      ...
+      void get_size( int& height, int& width ) const;
+      ...
+  };
+
+
+  ``int`` is immutable type in Python. So you can not expose ``get_size`` member 
+  function as is. You need to create a wrapper and expose it.
+
+  In the near future ``pyplusplus`` will eliminate the need of creating hand 
+  written wrapper for this use case.
+  
+::
+
+  boost::python::tuple get_window_size( const window_t& win ){
+      int h(0), w(0);
+      win.get_size( h, w );
+      return boost::python::make_tuple( h, w );
+  }
+
+Now you have to register it:
+
+::
+
+  using boost::python;
+  class_< window_t >( ... )
+      .def( "get_size", &::get_window_size )
+      ...
+  ;
+
+How it could be achieved with `pyplusplus`_? Class declaration, has also two 
+functions:
+
+* ``add_declaration_code( self, code )``
+
+  **Not implemented.**
+  **Feedback is wanted.**
+  **Please consider the relationship between this code and class wrapper code.**
+
+  This method will add the code to the declaration section within the module.
+  If you split your module to few files, `pyplusplus`_ will generate code, in a 
+  way, that declarations you added, will be visible to registration code.
+  
+* ``add_registration_code( self, code, works_on_instance=True )``
+
+  This method will add the code to the registration section of the class. 
+  
+  What is ``works_on_instance`` argument for? In our case, we added new method 
+  to the class. The first argument of the call will be ``self``. 
+  ::
+
+    #From Python user can call this method like this:
+    win = window_t( )
+    height, width = win.get_size()
+    
+  If you will pass ``works_on_instance=False`` next code will be generated:
+  ::
+
+    {
+        class_< window_t > window_exporter( "window_t" );
+        scope window_scope( window_exporter );
+        ...
+        def( "get_size", &::get_window_size );
+    }
+    
+  And in this case, user will be forced to pass reference to ``window_t`` object:
+  
+  ::
+
+    win = window_t()
+    height, width = window_t.get_size( win )
+
+Example
+-------
+::
+
   mb = module_builder_t( ... )
-  my_class = mb.class_( 'my_class' )
-  my_class.add_code( C++ code )
+  window = mb.class_( 'window_t' )
+  window.add_declaration_code( get_window_size definition )
+  window.add_registration_code( 'def( "get_size", &::get_window_size )' )
+  #pyplusplus will add ';' if needed
 
+----------------------------
+Insert code to class wrapper
+----------------------------
 
+I don't know what about you, but I don't like to create free functions in global
+namespace.I prefer to add ``get_window_size`` function to 
 
-
 .. _`pyplusplus` : ./../pyplusplus.html
 .. _`pygccxml` : ./../../pygccxml/pygccxml.html
 .. _`boost.python`: http://www.boost.org/libs/python/doc/index.html


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

[pygccxml-commit] SF.net SVN: pygccxml: [380] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 380
Author:   roman_yakovenko
Date:     2006-08-03 06:33:06 -0700 (Thu, 03 Aug 2006)
ViewCVS:  http://svn.sourceforge.net/pygccxml/?rev=380&view=rev

Log Message:
-----------
adding/updating documentation

Modified Paths:
--------------
    pyplusplus_dev/docs/documentation/how_to.rest

Added Paths:
-----------
    pyplusplus_dev/docs/documentation/hints.rest
Added: pyplusplus_dev/docs/documentation/hints.rest
===================================================================
--- pyplusplus_dev/docs/documentation/hints.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/hints.rest	2006-08-03 13:33:06 UTC (rev 380)
@@ -0,0 +1,52 @@
+=====
+Hints 
+=====
+
+.. contents:: Table of contents
+
+----------------------------------
+Class template instantiation alias
+----------------------------------
+
+`pyplusplus`_ has nice feature. If you define ``typedef`` for instantiated class 
+template, than `pyplusplus`_ will use it as a `Python`_ class name.
+
+For example:
+::
+
+  #include <vector>
+
+::
+
+  typedef std::vector< int > numbers;
+
+::
+
+  numbers generate_n(){
+      ...
+  }
+
+`pyplusplus`_ will use "numbers" as Python class name:
+
+::
+
+  using boost::python;
+  class_< std::vector< int > >( "numbers" )
+      ...
+  ;
+  
+This feature will work only in case there is only one such ``typedef``. Using class
+property ``aliases`` you can get access to all ``typedef``'s of the class.
+
+.. _`pyplusplus` : ./../pyplusplus.html
+.. _`boost.python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

Modified: pyplusplus_dev/docs/documentation/how_to.rest
===================================================================
--- pyplusplus_dev/docs/documentation/how_to.rest	2006-08-03 12:56:43 UTC (rev 379)
+++ pyplusplus_dev/docs/documentation/how_to.rest	2006-08-03 13:33:06 UTC (rev 380)
@@ -106,10 +106,28 @@
   window = mb.class_( "window_t" )
   window.member_function( "get_size" ).exclude()
   window.add_wrapper_code( wrapper_code )
-  window.add_code( registration_code )
+  window.registration_code( registration_code )
 
 That's all. 
 
+------------------------------------------------------------
+Fatal error C1204:Compiler limit:internal structure overflow
+------------------------------------------------------------
+
+If you get this error, that the generated file is too big. You will have to split
+it to few files. Well, not you but `pyplusplus`_ you will only have to tell that 
+to it.
+
+If you are using ``module_builder_t.write_module`` method, consider to switch
+to ``module_builder_t.split_module``. 
+
+If you are using ``split_method``, but still generated code for some specific 
+class could not be compiled because of error, you can ask `pyplusplus`_ to split
+class registration code to few cpp files.
+
+For more information, please read the documentation.
+
+
 .. _`pyplusplus` : ./../pyplusplus.html
 .. _`boost.python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

[pygccxml-commit] SF.net SVN: pygccxml: [381] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 381
Author:   roman_yakovenko
Date:     2006-08-05 11:33:36 -0700 (Sat, 05 Aug 2006)
ViewCVS:  http://svn.sourceforge.net/pygccxml/?rev=381&view=rev

Log Message:
-----------
updating documentation

Modified Paths:
--------------
    pyplusplus_dev/docs/documentation/index.rest

Added Paths:
-----------
    pyplusplus_dev/docs/documentation/architecture.rest
Added: pyplusplus_dev/docs/documentation/architecture.rest
===================================================================
--- pyplusplus_dev/docs/documentation/architecture.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/architecture.rest	2006-08-05 18:33:36 UTC (rev 381)
@@ -0,0 +1,68 @@
+============
+Architecture
+============
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+This document will describe an architecture behind `pyplusplus`_. If you just 
+started with `pyplusplus`_ you don't have to read this document.
+
+--------
+pygccxml
+--------
+
+What is exactly `pygccxml`_ for `pyplusplus`_. `pygccxml`_ provides next services:
+
+* definition of classes, that describe C++ declaration and types
+* C++ source files parsing and caching functionality
+* C++ class and type analizers( type traits )
+
+`pyplusplus`_ uses those services to:
+
+* extract declarations from source files
+
+* find out declaration default configuration:
+
+  * call policies for functions
+
+  * indexing suite parameters
+
+  * generate warnings/hints
+  
+  * ...
+
+* provide powerful query interface
+
+In general, `pygccxml`_ does all dirty work.
+
+---------------------
+decl_wrappers package
+---------------------
+
+This is the most important package in `pyplusplus`_. Why? Because this package
+contains interface, that configure code generator engine. For example
+
+
+pygccxml & decl_wrappers integration
+------------------------------------
+
+Almost every class in the ``decl_wrappers`` package derives from relevant class
+defined in ``pygccxml.declarations` package.
+  
+
+.. _`pyplusplus` : ./../pyplusplus.html
+.. _`boost.python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

Modified: pyplusplus_dev/docs/documentation/index.rest
===================================================================
--- pyplusplus_dev/docs/documentation/index.rest	2006-08-03 13:33:06 UTC (rev 380)
+++ pyplusplus_dev/docs/documentation/index.rest	2006-08-05 18:33:36 UTC (rev 381)
@@ -13,10 +13,10 @@
 
 How can you help?
 
-* Lets face it: today it is not possible to use `pyplusplus`_ without looking
-  into source code sometimes. `pyplusplus`_ uses `Epydoc`_ to generate 
-  documentation from source files. So, if you found some undocumented piece of 
-  code and you understand what it does, please write documentation string.
+* Lets face it: today it is not possible to use `pyplusplus`_ without eventually
+  looking into source code. `pyplusplus`_ uses `Epydoc`_ to generate documentation 
+  from source files. So, if you found some undocumented piece of code and you 
+  understand what it does, please write documentation string.
   
 * You are reading documentation and my English cause you to scream? Please, fix
   those errors and send me new version of the document. I will integrate the 


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

[pygccxml-commit] SF.net SVN: pygccxml: [660] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 660
          http://svn.sourceforge.net/pygccxml/?rev=660&view=rev
Author:   roman_yakovenko
Date:     2006-10-12 07:59:28 -0700 (Thu, 12 Oct 2006)

Log Message:
-----------
adding documentation

Added Paths:
-----------
    pyplusplus_dev/docs/documentation/functions/
    pyplusplus_dev/docs/documentation/functions/call_policies.rest
    pyplusplus_dev/docs/documentation/functions/functions.rest
    pyplusplus_dev/docs/documentation/functions/www_configuration.py

Added: pyplusplus_dev/docs/documentation/functions/call_policies.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/call_policies.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/call_policies.rest	2006-10-12 14:59:28 UTC (rev 660)
@@ -0,0 +1,157 @@
+=============
+Call policies
+=============
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+`Boost.Python`_ has a `nice introduction`__ in the tutorials about call policies.
+Also you can find more formal definition - `CallPolicies Concept`_ . 
+
+.. __ : http://boost.org/libs/python/doc/tutorial/doc/html/python/functions.html#python.call_policies
+.. _`CallPolicies Concept` : http://boost.org/libs/python/doc/v2/CallPolicies.html#CallPolicies-concept
+
+------
+Syntax
+------
+
+The call policies in `Py++`_ are named exactly as in `Boost.Python`_, only the 
+syntax is slightly different. For instance, this call policy:
+
+.. code-block:: C++
+
+  return_internal_reference< 1, with_custodian_and_ward<1, 2> >()
+
+becomes in `Py++`_
+
+.. code-block:: Python
+
+  return_internal_reference( 1, with_custodian_and_ward(1, 2) )
+
+`Py++`_ supports all call policies presented in `Boost.Python`_.
+
+-------------
+Usage example
+-------------
+
+Every "callable" object in `Py++`_ has ``call_policies`` property. 
+
+C++ code:
+
+  .. code-block:: C++
+
+    struct data{...};
+    const data& do_smth( const data& d, int x );
+    
+    void return_second_arg( int x, int y );
+    
+    typedef struct opaque_ *opaque_pointer;
+    opaque_pointer get_opaque();
+
+Python code:
+
+  .. code-block:: Python
+
+    from pyplusplus import module_builder
+    from pyplusplus.module_builder import call_policies
+    
+    mb = module_builder.module_builder_t( ... )
+    mb.free_function( 'return_second_arg' ).call_policies = call_policies.return_arg( 2 )
+    
+    mb.member_function( 'do_smth' ).call_policies = call_policies.return_self()
+    
+    mb.calldef( 'get_opaque' ).call_policies \
+        = call_policies.return_value_policy( call_policies.return_opaque_pointer )
+
+--------
+Defaults
+--------
+
+`Py++`_ is able to "guess" few call policies, base on analysis of return type:
+
+* ``default_call_policies``:
+
+  * `Python`_ immutable type by value: C++ fundamental types, ``std::string``, enumerations
+  
+  *  user defined type ( class ) by value
+  
+  * ``const char*``
+
+* ``return_value_policy``
+  
+  * ``return_opaque_pointer``
+  
+    * ``void*`` 
+  
+    * ``const void*``
+  
+  * ``copy_const_reference``
+
+    * ``const T&``
+    
+    * for member ``operator[]`` that returns const reference to immutable type
+  
+  * ``return_by_value``
+
+    * ``const wchar_t*``
+    
+  * ``copy_non_const_reference``
+  
+    * ``T&``, for member ``operator[]`` that returns reference to immutable type
+  
+  * ``return_internal_reference``
+  
+    * ``T&``, for member ``operator[]``
+
+---------------------
+Missing call policies
+---------------------
+
+If you don't specify call policy for a function and it needs one, few things will
+happen:
+
+* `Py++`_ prints a warning message
+
+* `Py++`_ generates code with 
+  
+  .. code-block:: C++
+  
+    /* undefined call policies */
+  
+  comment, in place of call policy. If `Py++`_ was wrong and function doesn't 
+  need call policy the generate code will compile fine, otherwise you will get a
+  compilation error.
+
+
+------------
+Special case
+------------
+
+``return_value_policy( return_opaque_pointer )`` is a special policy for `Boost.Python`_.
+In this case, it requieres from an user to define specializations for the 
+``boost::python::type_id`` function on the type pointed to by returned pointer. 
+`Py++`_ will generate the requiered code.
+
+For more information about the call policy please refer to `Boost.Python`_
+`documentation`_.
+
+.. _`documentation` : http://boost.org/libs/python/doc/v2/return_opaque_pointer.html 
+
+
+
+
+.. _`Py++` : ./../pyplusplus.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

Added: pyplusplus_dev/docs/documentation/functions/functions.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/functions.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/functions.rest	2006-10-12 14:59:28 UTC (rev 660)
@@ -0,0 +1,27 @@
+=====================
+Functions & operators
+=====================
+
+.. contents:: Table of contents
+
+--------
+Preamble
+--------
+
+`Boost.Python`_ provides very rich interface to expose functions and operators.
+This section of documentation will explain how to configure `Py++`_ in order
+to export your code using desired `Boost.Python`_ functionality.
+
+
+.. _`Py++` : ./../pyplusplus.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

Added: pyplusplus_dev/docs/documentation/functions/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/functions/www_configuration.py	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/www_configuration.py	2006-10-12 14:59:28 UTC (rev 660)
@@ -0,0 +1,5 @@
+name = 'functions & operators'
+#main_html_file = 'index.html'
+
+names = { 'call_policies' : 'call policies'
+}


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

[pygccxml-commit] SF.net SVN: pygccxml: [661] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 661
          http://svn.sourceforge.net/pygccxml/?rev=661&view=rev
Author:   roman_yakovenko
Date:     2006-10-15 12:21:55 -0700 (Sun, 15 Oct 2006)

Log Message:
-----------
adding functions documentation

Modified Paths:
--------------
    pyplusplus_dev/docs/documentation/containers.rest
    pyplusplus_dev/docs/documentation/functions/www_configuration.py

Added Paths:
-----------
    pyplusplus_dev/docs/documentation/functions/default_args.rest
    pyplusplus_dev/docs/documentation/functions/overloading.rest

Modified: pyplusplus_dev/docs/documentation/containers.rest
===================================================================
--- pyplusplus_dev/docs/documentation/containers.rest	2006-10-12 14:59:28 UTC (rev 660)
+++ pyplusplus_dev/docs/documentation/containers.rest	2006-10-15 19:21:55 UTC (rev 661)
@@ -51,10 +51,12 @@
 
 .. _`documentation` : ./indexing_suite_v2.html
 .. _`post` : http://mail.python.org/pipermail/c++-sig/2003-October/005802.html
-
-------------------------
-Py++ and indexing suites
-------------------------
+
+
+------------------------
+Py++ and indexing suites
+------------------------
+
 `Py++`_ implements support for both indexing suites. More over, you can 
 freely mix indexing suites. For example you can expose ``std::vector<int>`` using
 `Boost.Python`_ built-in indexing suite and ``std::map< int, std::string>`` using

Added: pyplusplus_dev/docs/documentation/functions/default_args.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/default_args.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/default_args.rest	2006-10-15 19:21:55 UTC (rev 661)
@@ -0,0 +1,128 @@
+=================
+Default arguments
+=================
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+There is more than one way to export function with default arguments. Before we 
+proceed, please take a look on next class:
+
+.. code-block:: C++
+
+  struct X
+  {
+      bool f(int a=12)
+      {
+          return true;
+      }  
+  };
+
+-------------------
+Do nothing approach
+-------------------
+
+By default `Py++`_ exposes function with its default arguments.
+
+.. code-block:: C++
+
+  namespace bp = boost::python;
+  
+  BOOST_PYTHON_MODULE(pyplusplus){
+    bp::class_< X >( "X" )    
+        .def( 
+            "f"
+            , &::X::f
+            , ( bp::arg("a")=(int)(12) ) );  
+  }
+
+This approach brings another additional value: keyword arguments. Your users
+will be able to call function ``f`` like this:
+
+.. code-block:: Python
+
+  x = X()
+  x.f( a=13 )
+
+----------------------------
+Default values, using macros
+----------------------------
+
+``BOOST_PYTHON_FUNCTION_OVERLOADS`` and ``BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS``
+macros help to deal with default values. You can turn ``use_overload_macro``
+to ``True`` as shown in `overloading`_ document.
+
+.. _`overloading` : ./overloading.html 
+
+--------------------------
+Registration order problem
+--------------------------
+
+There are different trades-off between these approaches. In general you should
+use the first one, untill you have "registration order" problem:
+
+.. code-block:: C++
+
+  struct S1;
+  struct S2;
+  
+  struct S1{
+      void do_smth( S2* s2=0 );
+  };
+  
+  struct S2{
+      void do_smth( S1 s1=S1() );
+  };
+  
+  BOOST_PYTHON_MODULE( ... ){
+      using namespace boost::python;
+      
+      class_< S2 >( "S2" )
+          .def( "do_smth", &S2::do_smth, ( arg("s1")=S1() ) );
+      
+      class_< S1 >( "S1" )
+          .def( "do_smth", &S1::do_smth, ( arg("s2")=object() ) );
+          
+  }
+
+These module could not be loaded, because the expression ``arg("s1")=S1()``
+requieres ``S1`` struct to be registered. `GCC-XML`_ reports default arguments 
+as strings. `Py++`_ doesn't have enough information to generate code with the 
+right class registration order.
+
+
+Unfortunatelly these macros have some limitations:
+
+1. The overloaded functions must have a common sequence of initial arguments.
+
+2. You will not be able to override virtual functions in `Python`_.
+
+3. You will not be able to use "named" arguments.
+
+4. You will not be able to set the functions documentation.
+
+Nevertheless these limitations the macros becomes very useful when you have 
+"registration order" problem with default arguments.
+
+
+
+
+`Py++`_ needs your help to generate right code:
+
+
+
+.. _`Py++` : ./../pyplusplus.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

Added: pyplusplus_dev/docs/documentation/functions/overloading.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/overloading.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/functions/overloading.rest	2006-10-15 19:21:55 UTC (rev 661)
@@ -0,0 +1,179 @@
+===========
+Overloading
+===========
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+Things get a little bit complex, when you should export overloaded functions.
+In general the solution is to explicitly say to compiler what function you
+want to export, by specifying its type. Before we proceed, please take a look
+on next class:
+
+.. code-block:: C++
+
+  struct X
+  {
+      bool f(int a)
+      {
+          return true;
+      }
+  
+      bool f(int a, double b)
+      {
+          return true;
+      }
+  
+      bool f(int a, double b, char c)
+      {
+          return true;
+      }
+  };
+
+This class has been taken from `Boost.Python`_ `tutorials`__.
+
+.. __ : http://boost.org/libs/python/doc/tutorial/doc/html/python/functions.html#python.overloading
+
+There are few approaches, which you can use in order to exort the functions.
+
+-------------------
+Do nothing approach
+-------------------
+
+I am sure you will like "do nothing" approach. `Py++`_ recognize that you want to
+export an overloaded function and will generate the right code:
+
+.. code-block:: C++
+
+  namespace bp = boost::python;
+  
+  BOOST_PYTHON_MODULE(pyplusplus){
+    bp::class_< X >( "X" )    
+        .def( 
+            "f"
+            , (bool ( ::X::* )( int ) )( &::X::f )
+            , ( bp::arg("a") ) )    
+        .def( 
+            "f"
+            , (bool ( ::X::* )( int,double ) )( &::X::f )
+            , ( bp::arg("a"), bp::arg("b") ) )    
+        .def( 
+            "f"
+            , (bool ( ::X::* )( int,double,char ) )( &::X::f )
+            , ( bp::arg("a"), bp::arg("b"), bp::arg("c") ) );
+  }
+
+From my experience, this approach works pretty well and in most cases the only
+customization you should do on exported function is to setup right call policies.
+
+--------------------------------
+"create_with_signature" approach
+--------------------------------
+
+Well, while previous approach is very attractive it does not work in all cases
+and have a weakness.
+
+Overloaded template function
+----------------------------
+
+I am sure you already know next facts, but still I want to remind them:
+
+1. `GCC-XML`_ doesn't report about uninstantiated templates
+
+2. `Boost.Python`_ is able to export only template instantiation
+
+It is very important to understand the first fact. Lets take a look on next source
+code:
+
+.. code-block:: C++
+
+  struct Y{
+  
+      void do_smth( int );
+      
+      template< class T>
+      void do_smth( T t );
+  
+  };
+
+If you didn't instantiate( use ) ``do_smth`` member function, than `GCC-XML`_
+will not report it. As a result, `Py++`_ will not be aware of the fact that 
+``do_smth`` is an overloaded function. To make the long story short the generated
+code will not compile. You have to instruct `Py++`_ to generate code, which 
+contains function type:
+
+.. code-block:: Python
+
+  from pyplusplus import module_builder
+  
+  mb = module_builder.module_builder_t( ... )
+  y = mb.class_( 'Y' )
+  y.member_function( 'do_smth' ).create_with_signature = True
+  #------------------------------^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Every `Py++`_ class, which describes C++ function\\operator has ``create_with_signature``
+property. You have to set it to ``True``. Default value of the property is 
+computed. If the exported function is overloaded, then its value is ``True``
+otherwise it will be ``False``.
+
+Do nothing approach weakness
+----------------------------
+
+Code modification - the weakness of the "do nothing" approach. We live in the 
+dynamic world. You can create bindings for a project, but a month letter, the 
+project developers will add a new function to the exported class. Lets assume 
+that the function will introduce overloading. If ``create_with_signature`` has 
+``False`` as a value, than the previously generated code will not compile. My 
+advise to you: explicitly set ``create_with_signature`` to ``True``. It will 
+save your time in future.
+
+------------------------
+Overloading using macros
+------------------------
+
+`Boost.Python`_ provides two macros, which help you to deal with overloaded 
+functions:
+
+* ``BOOST_PYTHON_FUNCTION_OVERLOADS``
+
+* ``BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS``
+
+`Boost.Python`_ tutorials contains an `explanation`_ about this macros.
+
+.. _`explanation` : http://boost.org/libs/python/doc/tutorial/doc/html/python/functions.html#python.auto_overloading
+
+You can instruct `Py++`_ to generate code, which will use the macros:
+
+.. code-block:: Python
+
+  import module_builder
+  
+  mb = module_builder.module_builder_t( ... )
+  x = mb.class_( "X" )
+  x.member_functions( "f" ).use_overload_macro = True
+  #-------------------------^^^^^^^^^^^^^^^^^^^^^^^^^
+  
+Member and free functions declaration classes have ``use_overload_macro`` property.
+The default value of the property is ``False``.
+
+You don't really have to use the macros, unless you have "registration order"
+problem. The problem and work around described in `default arguments`_ document.
+
+.. _`default arguments` : ./default_args.html
+
+
+.. _`Py++` : ./../pyplusplus.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

Modified: pyplusplus_dev/docs/documentation/functions/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/functions/www_configuration.py	2006-10-12 14:59:28 UTC (rev 660)
+++ pyplusplus_dev/docs/documentation/functions/www_configuration.py	2006-10-15 19:21:55 UTC (rev 661)
@@ -2,4 +2,5 @@
 #main_html_file = 'index.html'
 
 names = { 'call_policies' : 'call policies'
+          , 'default_args' : 'default arguments'
 }


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

[pygccxml-commit] SF.net SVN: pygccxml: [992] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 992
          http://svn.sourceforge.net/pygccxml/?rev=992&view=rev
Author:   roman_yakovenko
Date:     2007-04-15 12:34:49 -0700 (Sun, 15 Apr 2007)

Log Message:
-----------
improving docs

Modified Paths:
--------------
    pyplusplus_dev/docs/documentation/www_configuration.py

Added Paths:
-----------
    pyplusplus_dev/docs/documentation/feedback.html
    pyplusplus_dev/docs/documentation/warnings.rest

Removed Paths:
-------------
    pyplusplus_dev/docs/documentation/feedback.rest

Added: pyplusplus_dev/docs/documentation/feedback.html
===================================================================
--- pyplusplus_dev/docs/documentation/feedback.html	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/feedback.html	2007-04-15 19:34:49 UTC (rev 992)
@@ -0,0 +1,9 @@
+<html>
+<head>
+<meta http-equiv="refresh" content="0; URL=./warnings.html">
+</head>
+<body>
+Automatic redirection failed, please go to
+<a href="./warnings.html">./warnings.html</a>
+</body>
+</html>

Deleted: pyplusplus_dev/docs/documentation/feedback.rest
===================================================================
--- pyplusplus_dev/docs/documentation/feedback.rest	2007-04-15 19:26:09 UTC (rev 991)
+++ pyplusplus_dev/docs/documentation/feedback.rest	2007-04-15 19:34:49 UTC (rev 992)
@@ -1,222 +0,0 @@
-=============
-Py++ feedback
-=============
-
-.. contents:: Table of contents
-
-------------
-Introduction
-------------
-
-`Py++`_ has been created with few goals in mind:
-
-* to allow users create `Python`_ bindings for large projects using the `Boost.Python`_
-  library
-
-* to minimize maintenance time
-
-* to serve as a user's guide for `Boost.Python`_ library
-
-
-Those goals all have something in common. In order to achieve them, `Py++`_ must
-give useful feedback to the user.  Because `Py++`_ understands the
-declarations it exports, it can scan declarations for potential problems, report
-them and in some cases provide hints about how to resolve the problem. Few examples:
-
-*
-  .. code-block:: C++
-
-     struct Y{ ... };
-
-  .. code-block:: C++
-
-     struct X{
-         ...
-         virtual Y& do_smth();
-     };
-
-  Member function ``do_smth`` can not be overridden in Python because... [FILL IN HERE].
-
-*
-  .. code-block:: C++
-
-     struct window{
-         ...
-         void get_size( int& height, int& width ) const;
-     };
-
-  Member function ``get_size`` can be exposed to Python, but it will not be callable because [FILL IN HERE].
-
-* In order to expose free/member function that takes more than 10 arguments user
-  should define ``BOOST_PYTHON_MAX_ARITY`` macro.
-
-*
-  .. code-block:: C++
-
-     struct X{
-         ...
-     };
-
-     void do_smth( X x );
-
-  If you expose ``do_smth`` function and don't expose struct ``X``, `Py++`_
-  will tell you that struct ``X`` is used in exported declaration, but was not
-  exposed.
-
-For these problems and many other `Py++`_ gives a nice explanation
-and sometimes a link to the relevant information on the Internet.
-
-I don't know what about you, but I found these messages pretty useful. They allow
-me to deliver Python bindings with higher quality.
-
--------------
-How it works?
--------------
-
-In previous paragraph, I described some pretty useful functionality but what should you
-do to enable it? - *Nothing!* By default, `Py++`_ only prints the
-important messages to ``stdout``. More over it prints them only for declarations
-that are going to be exported.
-
-`Py++`_ uses the python  `logging`_ package to write all user messages. By
-default, messages with ``DEBUG`` level will be skipped, all other messages will
-be reported.
-
---------
-Warnings
---------
-
-Example of the warning:
-::
-
-  WARNING: containers::item_t [struct]
-  > warning W1020: Py++ will generate class wrapper - hand written code
-  > should be added to the wrapper class
-
-Almost every warning reported by `Py++`_ consists from 3 parts:
-
-* description of the declaration it refers to: "containers::item_t [struct]"
-
-* warning unique identifier: "W1020"
-
-* short explanation of the problem: "Py++ will generate class wrapper - hand
-  written code should be added to the wrapper class"
-
----------------
-API Description
----------------
-
-How to disable warning(s)?
---------------------------
-
-Every warning has unique identifier. In the example I gave it was ``W1020``.
-
-.. code-block:: Python
-
-   from pyplusplus import messages
-   from pyplusplus import module_builder
-
-   mb = module_builder.module_builder_t( ... )
-   xyz = mb.class_( XYZ )
-   xyz.disable_warnings( messages.W1020 )
-
-It is also possible to disable warnings for all declarations. ``pyplusplus.messages``
-package defines ``DISABLE_MESSAGES`` variable. This variable( ``list`` ) keeps
-all warnings, which should not be reported. Use ``messages.disable`` function to
-edit it:
-
-.. code-block:: Python
-
-   messages.disable( messages.W1020 )
-
-
-Logging API
------------
-
-If you are here, it probably means that you are not pleased with default configuration
-and want to change it, right?
-
-1. If you simply want to change the logging message level:
-
-   .. code-block:: Python
-
-     import logging
-     from pyplusplus import module_builder
-
-   .. code-block:: Python
-
-     module_builder.set_logger_level( logging.DEBUG )
-
-
-2. But what if you want to disable some messages and leave others? This is also possible.
-   `Py++`_ and `pygccxml`_ do not use a single logger. Almost every internal
-   package has its own logger. So you can enable one logger and disable another one.
-
-   The `pygccxml`_ package defines all loggers in the ``pygccxml.utils`` package.
-
-   The `Py++`_ package defines all loggers in the ``pyplusplus._logging_`` package.
-
-   Both packages define a ``loggers`` class. Those classes keep references to
-   different loggers. The ``loggers`` classes look very similar to the next class:
-
-   .. code-block:: Python
-
-      import logging #standard Python package
-
-      def _create_logger_( name ):
-          logger = logging.getLogger(name)
-          ...
-          return logger
-
-      class loggers:
-           file_writer = _create_logger_( 'pyplusplus.file_writer' )
-           declarations = _create_logger_( 'pyplusplus.declarations' )
-           module_builder = _create_logger_( 'pyplusplus.module_builder' )
-           root = logging.getLogger( 'pyplusplus' )
-           all = [ root, file_writer, module_builder, declarations ]
-
-   You can use these references in the ``logging`` package to complete
-   your task of adjusting individual loggers.
-
-   One more thing, `Py++`_ automatically splits long message, where line
-   length defaults to 70 characters. Thus it is very convenient to read them on your screen.
-   If you want to use different tools to monitor those messages, consider to use
-   standard `Formatter`_ class, instead of ``multi_line_formatter_t`` one.
-
-
-Declarations API
-----------------
-
-Every declaration class has the following methods:
-
-* ``why_not_exportable( self )``
-
-  This method explains why a declaration could not be exported. The return value
-  is a string or ``None``. ``None`` is returned if the declaration is exportable.
-
-  Property ``exportable`` will be set to ``True`` if declaration is exportable,
-  and to ``False`` otherwise.
-
-* ``readme( self )``
-
-  This method gives you access to all tips/hints/warnings `Py++`_ has about
-  the declaration. This methods returns a list of strings. If the declaration is
-  not exportable, than first message within the list is an explanation, why it
-  is not exportable.
-
-
-.. _`Formatter` : http://docs.python.org/lib/node357.html
-.. _`logging` : http://docs.python.org/lib/module-logging.html
-.. _`Py++` : ./../pyplusplus.html
-.. _`pygccxml` : ./../../pygccxml/pygccxml.html
-.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
-.. _`Python`: http://www.python.org
-.. _`GCC-XML`: http://www.gccxml.org
-
-..
-   Local Variables:
-   mode: indented-text
-   indent-tabs-mode: nil
-   sentence-end-double-space: t
-   fill-column: 70
-   End:

Copied: pyplusplus_dev/docs/documentation/warnings.rest (from rev 987, pyplusplus_dev/docs/documentation/feedback.rest)
===================================================================
--- pyplusplus_dev/docs/documentation/warnings.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/warnings.rest	2007-04-15 19:34:49 UTC (rev 992)
@@ -0,0 +1,222 @@
+=============
+Py++ warnings
+=============
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+`Py++`_ has been created with few goals in mind:
+
+* to allow users create `Python`_ bindings for large projects using the `Boost.Python`_
+  library
+
+* to minimize maintenance time
+
+* to serve as a user's guide for `Boost.Python`_ library
+
+
+Those goals all have something in common. In order to achieve them, `Py++`_ must
+give useful feedback to the user. Because `Py++`_ understands the declarations
+it exports, it can scan declarations for potential problems, report them and in
+some cases provide hints about how to resolve the problem. Few examples:
+
+*
+  .. code-block:: C++
+
+     struct Y{ ... };
+
+  .. code-block:: C++
+
+     struct X{
+         ...
+         virtual Y& do_smth();
+     };
+
+  Member function ``do_smth`` can not be overridden in Python because... [FILL IN HERE].
+
+*
+  .. code-block:: C++
+
+     struct window{
+         ...
+         void get_size( int& height, int& width ) const;
+     };
+
+  Member function ``get_size`` can be exposed to Python, but it will not be callable because [FILL IN HERE].
+
+* In order to expose free/member function that takes more than 10 arguments user
+  should define ``BOOST_PYTHON_MAX_ARITY`` macro.
+
+*
+  .. code-block:: C++
+
+     struct X{
+         ...
+     };
+
+     void do_smth( X x );
+
+  If you expose ``do_smth`` function and don't expose struct ``X``, `Py++`_
+  will tell you that struct ``X`` is used in exported declaration, but was not
+  exposed.
+
+For these problems and many other `Py++`_ gives a nice explanation
+and sometimes a link to the relevant information on the Internet.
+
+I don't know what about you, but I found these messages pretty useful. They allow
+me to deliver Python bindings with higher quality.
+
+-------------
+How it works?
+-------------
+
+In previous paragraph, I described some pretty useful functionality but what should you
+do to enable it? - *Nothing!* By default, `Py++`_ only prints the
+important messages to ``stdout``. More over it prints them only for declarations
+that are going to be exported.
+
+`Py++`_ uses the python  `logging`_ package to write all user messages. By
+default, messages with ``DEBUG`` level will be skipped, all other messages will
+be reported.
+
+--------
+Warnings
+--------
+
+Example of the warning:
+::
+
+  WARNING: containers::item_t [struct]
+  > warning W1020: Py++ will generate class wrapper - hand written code
+  > should be added to the wrapper class
+
+Almost every warning reported by `Py++`_ consists from 3 parts:
+
+* description of the declaration it refers to: "containers::item_t [struct]"
+
+* warning unique identifier: "W1020"
+
+* short explanation of the problem: "Py++ will generate class wrapper - hand
+  written code should be added to the wrapper class"
+
+---------------
+API Description
+---------------
+
+How to disable warning(s)?
+--------------------------
+
+Every warning has unique identifier. In the example I gave it was ``W1020``.
+
+.. code-block:: Python
+
+   from pyplusplus import messages
+   from pyplusplus import module_builder
+
+   mb = module_builder.module_builder_t( ... )
+   xyz = mb.class_( XYZ )
+   xyz.disable_warnings( messages.W1020 )
+
+It is also possible to disable warnings for all declarations. ``pyplusplus.messages``
+package defines ``DISABLE_MESSAGES`` variable. This variable( ``list`` ) keeps
+all warnings, which should not be reported. Use ``messages.disable`` function to
+edit it:
+
+.. code-block:: Python
+
+   messages.disable( messages.W1020 )
+
+
+Logging API
+-----------
+
+If you are here, it probably means that you are not pleased with default configuration
+and want to change it, right?
+
+1. If you simply want to change the logging message level:
+
+   .. code-block:: Python
+
+     import logging
+     from pyplusplus import module_builder
+
+   .. code-block:: Python
+
+     module_builder.set_logger_level( logging.DEBUG )
+
+
+2. But what if you want to disable some messages and leave others? This is also possible.
+   `Py++`_ and `pygccxml`_ do not use a single logger. Almost every internal
+   package has its own logger. So you can enable one logger and disable another one.
+
+   The `pygccxml`_ package defines all loggers in the ``pygccxml.utils`` package.
+
+   The `Py++`_ package defines all loggers in the ``pyplusplus._logging_`` package.
+
+   Both packages define a ``loggers`` class. Those classes keep references to
+   different loggers. The ``loggers`` classes look very similar to the next class:
+
+   .. code-block:: Python
+
+      import logging #standard Python package
+
+      def _create_logger_( name ):
+          logger = logging.getLogger(name)
+          ...
+          return logger
+
+      class loggers:
+           file_writer = _create_logger_( 'pyplusplus.file_writer' )
+           declarations = _create_logger_( 'pyplusplus.declarations' )
+           module_builder = _create_logger_( 'pyplusplus.module_builder' )
+           root = logging.getLogger( 'pyplusplus' )
+           all = [ root, file_writer, module_builder, declarations ]
+
+   You can use these references in the ``logging`` package to complete
+   your task of adjusting individual loggers.
+
+   One more thing, `Py++`_ automatically splits long message, where line
+   length defaults to 70 characters. Thus it is very convenient to read them on your screen.
+   If you want to use different tools to monitor those messages, consider to use
+   standard `Formatter`_ class, instead of ``multi_line_formatter_t`` one.
+
+
+Declarations API
+----------------
+
+Every declaration class has the following methods:
+
+* ``why_not_exportable( self )``
+
+  This method explains why a declaration could not be exported. The return value
+  is a string or ``None``. ``None`` is returned if the declaration is exportable.
+
+  Property ``exportable`` will be set to ``True`` if declaration is exportable,
+  and to ``False`` otherwise.
+
+* ``readme( self )``
+
+  This method gives you access to all tips/hints/warnings `Py++`_ has about
+  the declaration. This methods returns a list of strings. If the declaration is
+  not exportable, than first message within the list is an explanation, why it
+  is not exportable.
+
+
+.. _`Formatter` : http://docs.python.org/lib/node357.html
+.. _`logging` : http://docs.python.org/lib/module-logging.html
+.. _`Py++` : ./../pyplusplus.html
+.. _`pygccxml` : ./../../pygccxml/pygccxml.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   End:

Modified: pyplusplus_dev/docs/documentation/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/www_configuration.py	2007-04-15 19:26:09 UTC (rev 991)
+++ pyplusplus_dev/docs/documentation/www_configuration.py	2007-04-15 19:34:49 UTC (rev 992)
@@ -1,6 +1,6 @@
 name = 'documentation'
 main_html_file = 'index.html'
-files_to_skip = ['indexing_suite_v2.html']
+files_to_skip = ['indexing_suite_v2.html', 'feedback.html']
 names = { 'containers' : 'STL containers'
           , 'how_to' : 'how to ... ?'
           , 'doc_string' : 'documentation string'


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

[pygccxml-commit] SF.net SVN: pygccxml: [999] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 999
          http://svn.sourceforge.net/pygccxml/?rev=999&view=rev
Author:   roman_yakovenko
Date:     2007-04-18 11:51:07 -0700 (Wed, 18 Apr 2007)

Log Message:
-----------
adding documentation about "include" functionality

Modified Paths:
--------------
    pyplusplus_dev/docs/documentation/index.rest
    pyplusplus_dev/docs/documentation/inserting_code.rest

Modified: pyplusplus_dev/docs/documentation/index.rest
===================================================================
--- pyplusplus_dev/docs/documentation/index.rest	2007-04-18 06:22:31 UTC (rev 998)
+++ pyplusplus_dev/docs/documentation/index.rest	2007-04-18 18:51:07 UTC (rev 999)
@@ -30,7 +30,7 @@
 Overview
 --------
 
-* `API docs`_ - contains API documentation, including source code, generated by `epydoc`_ 
+* `API docs`_ - contains API documentation, including source code, generated by `epydoc`_
 
 .. _`API docs` : ./apidocs/index.html
 .. _`epydoc` : http://epydoc.sourceforge.net/
@@ -43,26 +43,26 @@
 
 .. _`architecture` : ./architecture.html
 
-* `best practices`_ - `Py++`_ is huge, this document will explain you how to 
+* `best practices`_ - `Py++`_ is huge, this document will explain you how to
   effectively use it
 
 .. _`best practices`: ./best_practices.html
 
-* `documentation string`_ - explains how to automaticly extract a documentation 
+* `documentation string`_ - explains how to automaticly extract a documentation
   from the source files and put it as Python documentation string
 
 .. _`documentation string` : ./doc_string.html
 
-* `feedback`_ - `Py++`_ could be used as some kind of validator. It checks the 
-  exposed declarations and reports the potential errors. Thus you are able to 
-  create high quality Python bindings from the beginning. This document also 
+* `warnings`_ - `Py++`_ could be used as some kind of validator. It checks the
+  exposed declarations and reports the potential errors. Thus you are able to
+  create high quality Python bindings from the beginning. This document also
   describes how to supress the errors\\warnings.
 
-.. _`feedback` : ./feedback.html
+.. _`warnings` : ./warnings.html
 
 * `functions & operators`_ - contains a complete guide to exposing functions and
   operators, including "call policies" and description of different caveats
-  
+
 .. _`functions & operators` : ../functions/functions.html
 
 * `hints`_ - describes few techinques, which will help you with exposing template
@@ -70,28 +70,28 @@
 
 .. _`hints`: ./hints.html
 
-* `how to ... ?`_ - contains answers for different frequently asked questions 
+* `how to ... ?`_ - contains answers for different frequently asked questions
 
 .. _`how to ... ?` : ./how_to.html
 
 * `inserting code`_ - a complete guide for insert your code into the generated one
 
-.. _`inserting code` : ./inserting_code.html 
+.. _`inserting code` : ./inserting_code.html
 
-* `multi-module development`_ - describes how expose hierarchy of classes, which 
+* `multi-module development`_ - describes how expose hierarchy of classes, which
   is spread few different libraries
 
 .. _`multi-module development`: ./multi_module_development.html
 
-* `properties`_ - describes how to create class properties using `Py++`_ and 
+* `properties`_ - describes how to create class properties using `Py++`_ and
   built-in algorithm for automatic properties recognition
 
 .. _`properties`: ./properties.html
 
 * `tutorials`_ - don't know where to start? Start here. Small and simple example
-  will help you to start with `Py++`_. If you want to evaluate `Py++`_ you will 
+  will help you to start with `Py++`_. If you want to evaluate `Py++`_ you will
   find here small and handy GUI program.
-  
+
 .. _`tutorials` : ./tutorials/tutorials.html
 
 .. _`Epydoc` : http://epydoc.sourceforge.net/

Modified: pyplusplus_dev/docs/documentation/inserting_code.rest
===================================================================
--- pyplusplus_dev/docs/documentation/inserting_code.rest	2007-04-18 06:22:31 UTC (rev 998)
+++ pyplusplus_dev/docs/documentation/inserting_code.rest	2007-04-18 18:51:07 UTC (rev 999)
@@ -194,8 +194,48 @@
   for cls in mb.classes( relevant classes only ):
     inject_code( cls )
 
+------------
+Header files
+------------
 
+Now, when you know how to add your code to a generated one, I think you also should
+now how to add your own set of include directives to the generated files. There
+are few ways to do this.
 
+1. The easiest and the most effective one - tell to `Py++`_ that generated code
+   for the declaration should include additional files:
+
+   .. code-block:: Python
+
+     mb = module_builder_t( ... )
+     my_class = mb.class_( ... )
+     my_class.include_files.append( "vector" )
+
+   Every declaration has ``include_files`` property. This is a list of header files,
+   you want to include from the generated file(s).
+
+2. Other approach is a little bit low level, but it allows you to add your header
+   files to every generated file:
+
+   .. code-block:: Python
+
+     mb = module_builder_t( ... )
+     ...
+     mb.build_code_creator( ... )
+     mb.code_creator.add_include( "iostream" )
+
+   You can also replace all (to be) generated header files with your own set:
+
+   .. code-block:: Python
+
+     mb.code_creator.replace_included_headers( ["stdafx.h"] )
+
+Of course you can, and may be should, use both approaches.
+
+I suggest you to spend some time and to tweak `Py++`_ to generate source code
+with as little as possible include directives. This will save you huge amount of
+time later.
+
 .. _`Py++` : ./../pyplusplus.html
 .. _`pygccxml` : ./../../pygccxml/pygccxml.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

[pygccxml-commit] SF.net SVN: pygccxml: [1020] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 1020
          http://svn.sourceforge.net/pygccxml/?rev=1020&view=rev
Author:   roman_yakovenko
Date:     2007-04-24 22:41:44 -0700 (Tue, 24 Apr 2007)

Log Message:
-----------
fixing broken links

Modified Paths:
--------------
    developer_scripts/check_links.bat
    pyplusplus_dev/docs/comparisons/pyste.rest
    pyplusplus_dev/docs/documentation/functions/call_policies.rest
    pyplusplus_dev/docs/documentation/functions/default_args.rest
    pyplusplus_dev/docs/documentation/functions/functions.rest
    pyplusplus_dev/docs/documentation/functions/overloading.rest
    pyplusplus_dev/docs/documentation/functions/registration_order.rest
    pyplusplus_dev/docs/documentation/functions/transformation/built_in/built_in.rest
    pyplusplus_dev/docs/documentation/functions/transformation/built_in/inout.rest
    pyplusplus_dev/docs/documentation/functions/transformation/built_in/input.rest
    pyplusplus_dev/docs/documentation/functions/transformation/built_in/input_c_buffer.rest
    pyplusplus_dev/docs/documentation/functions/transformation/built_in/input_static_array.rest
    pyplusplus_dev/docs/documentation/functions/transformation/built_in/modify_type.rest
    pyplusplus_dev/docs/documentation/functions/transformation/built_in/output.rest
    pyplusplus_dev/docs/documentation/functions/transformation/built_in/output_static_array.rest
    pyplusplus_dev/docs/documentation/functions/transformation/built_in/transfer_ownership.rest
    pyplusplus_dev/docs/documentation/functions/transformation/custom/custom.rest
    pyplusplus_dev/docs/documentation/functions/transformation/name_mangling.rest
    pyplusplus_dev/docs/documentation/functions/transformation/terminology.rest
    pyplusplus_dev/docs/documentation/functions/transformation/transformation.rest
    pyplusplus_dev/docs/documentation/index.rest

Modified: developer_scripts/check_links.bat
===================================================================
--- developer_scripts/check_links.bat	2007-04-25 05:15:33 UTC (rev 1019)
+++ developer_scripts/check_links.bat	2007-04-25 05:41:44 UTC (rev 1020)
@@ -1 +1,3 @@
-E:\Python24\Scripts\linkchecker.bat ..\..\language-binding\production\www\index.html
+cd D:\dev\language-binding\production\www\
+E:\Python25\Scripts\linkchecker.bat index.html
+                                    

Modified: pyplusplus_dev/docs/comparisons/pyste.rest
===================================================================
--- pyplusplus_dev/docs/comparisons/pyste.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/comparisons/pyste.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -424,7 +424,7 @@
 thought about them, long before I created `Py++`_. But unfortunately, lack
 of time and motivation prevents him to work on `Pyste`_.
 
-.. _`screenshot` : ./../documentation/tutorials/pyplusplus_demo.png
+.. _`screenshot` : ./../documentation/tutorials/pyplusplus_gui.html
 .. _`Py++` : ./../pyplusplus.html
 .. _`pygccxml` : ./../../pygccxml/pygccxml.html
 .. _`Pyste`: http://www.boost.org/libs/python/doc/index.html

Modified: pyplusplus_dev/docs/documentation/functions/call_policies.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/call_policies.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/call_policies.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -548,7 +548,7 @@
 .. _`ResultConverterGenerator` : http://boost.org/libs/python/doc/v2/ResultConverter.html#ResultConverterGenerator-concept
 .. _`CallPolicies` : http://www.boost.org/libs/python/doc/v2/CallPolicies.html#CallPolicies-concept
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/default_args.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/default_args.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/default_args.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -142,7 +142,7 @@
 I am sure we will be able to help you.
 
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/functions.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/functions.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/functions.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -13,7 +13,7 @@
 to export your functions, using desired `Boost.Python`_ functionality.
 
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/overloading.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/overloading.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/overloading.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -167,7 +167,7 @@
 .. _`default arguments` : ./default_args.html
 
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/registration_order.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/registration_order.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/registration_order.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -144,7 +144,7 @@
 
 
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/transformation/built_in/built_in.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/built_in.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/built_in.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -45,7 +45,7 @@
 value. `Py++`_ handles pretty well such use cases.
 
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/transformation/built_in/inout.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/inout.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/inout.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -61,7 +61,7 @@
          bp::def( "hello_world", &hello_world_a3478182294a057b61508c30b1361318 );
      }
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/transformation/built_in/input.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/input.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/input.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -54,7 +54,7 @@
          bp::def( "hello_world", &hello_world_a3478182294a057b61508c30b1361318 );
      }
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/transformation/built_in/input_c_buffer.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/input_c_buffer.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/input_c_buffer.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -68,7 +68,7 @@
                 , ( bp::arg("inst"), bp::arg("buffer") ) );
      }
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/transformation/built_in/input_static_array.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/input_static_array.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/input_static_array.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -71,7 +71,7 @@
         .def_readwrite( "z", &ft::vector3::z );
      }
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/transformation/built_in/modify_type.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/modify_type.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/modify_type.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -65,7 +65,7 @@
          bp::def( "hello_world", &hello_world_a3478182294a057b61508c30b1361318 );
      }
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/transformation/built_in/output.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/output.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/output.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -59,7 +59,7 @@
       }
 
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/transformation/built_in/output_static_array.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/output_static_array.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/output_static_array.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -71,7 +71,7 @@
             .def_readwrite( "z", &ft::vector3::z );
      }
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/transformation/built_in/transfer_ownership.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/built_in/transfer_ownership.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/transformation/built_in/transfer_ownership.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -64,7 +64,7 @@
          bp::def( "do_smth", &do_smth_4cf7cde5fca92efcdb8519f8c1a4bccd, ( bp::arg("r") ) );
      }
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/transformation/custom/custom.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/custom/custom.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/transformation/custom/custom.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -26,7 +26,7 @@
 .. _`built-in transformers` : ../built_in/built_in.html
 
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/transformation/name_mangling.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/name_mangling.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/transformation/name_mangling.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -79,7 +79,7 @@
 2. If you forgot to give an alias to a function, your users will still be able
    to call the function. So no need to rush and create new release.
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/transformation/terminology.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/terminology.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/transformation/terminology.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -31,7 +31,7 @@
   Name under which `Python`_ users see the exposed function
 
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/functions/transformation/transformation.rest
===================================================================
--- pyplusplus_dev/docs/documentation/functions/transformation/transformation.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/functions/transformation/transformation.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -78,7 +78,7 @@
 A thanks goes to Matthias Baas for his efforts and hard work. He did a research,
 implemented the initial working version and wrote a lot of documentation. 
 
-.. _`Py++` : ./../pyplusplus.html
+.. _`Py++` : ./../../../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org
 .. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/index.rest
===================================================================
--- pyplusplus_dev/docs/documentation/index.rest	2007-04-25 05:15:33 UTC (rev 1019)
+++ pyplusplus_dev/docs/documentation/index.rest	2007-04-25 05:41:44 UTC (rev 1020)
@@ -63,7 +63,7 @@
 * `functions & operators`_ - contains a complete guide to exposing functions and
   operators, including "call policies" and description of different caveats
 
-.. _`functions & operators` : ../functions/functions.html
+.. _`functions & operators` : ./functions/functions.html
 
 * `hints`_ - describes few techniques, which will help you with exposing template
   instantiations


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

[pygccxml-commit] SF.net SVN: pygccxml: [1215] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 1215
          http://pygccxml.svn.sourceforge.net/pygccxml/?rev=1215&view=rev
Author:   roman_yakovenko
Date:     2007-12-31 01:27:13 -0800 (Mon, 31 Dec 2007)

Log Message:
-----------
adding docs for file writers

Modified Paths:
--------------
    pyplusplus_dev/docs/documentation/www_configuration.py

Added Paths:
-----------
    pyplusplus_dev/docs/documentation/split_module.rest

Added: pyplusplus_dev/docs/documentation/split_module.rest
===================================================================
--- pyplusplus_dev/docs/documentation/split_module.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/split_module.rest	2007-12-31 09:27:13 UTC (rev 1215)
@@ -0,0 +1,71 @@
+=================================
+Splitting generated code to files
+=================================
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+`Py++`_ provides 4 different strategies for splitting the generated code into files:
+
+* single file
+
+* multiple files
+
+* fixed set of multiple files
+
+* multiple files, where single class code is split to few files
+
+-----------
+Single file
+-----------
+
+If you just start with `Py++`_ or you are developing small module, than you should 
+start with this strategy. It is simple - all source code generated to single file.
+
+Of course this solution has it's price - every time you change the code you will
+have to recompile it. If you expose 2 or more declarations this is annoying and 
+time-consuming operation. 
+
+Usage example
+-------------
+
+.. code-block:: Python
+
+   from pyplusplus import module_builder
+   
+   mb = module_builder.module_builder_t(...)
+   mb.build_code_creator( ... )
+   mb.write_module( file name )
+
+--------------
+Multiple files
+--------------
+
+I believe this is the most widely used strategy. `Py++`_ splits generated code 
+as follows:
+
+* every class has it's own source & header file
+* all free enumerations are written to a single source file
+* all free functions are written to a single source file
+* all global variables are written to a single source file
+* source file, which contains complete code for module registration
+
+The main advantage of this mode is that you don't have to recompile the whole 
+project if only single declaration was changed. Thus this mode suites well huge
+projects.
+
+There are few problems with this mode:
+
+1. There are use cases, when the generated file names are too long. 
+
+
+
+
+.. _`Py++` : ./../pyplusplus.html
+.. _`pygccxml` : ./../../pygccxml/pygccxml.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org

Modified: pyplusplus_dev/docs/documentation/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/www_configuration.py	2007-12-30 10:39:06 UTC (rev 1214)
+++ pyplusplus_dev/docs/documentation/www_configuration.py	2007-12-31 09:27:13 UTC (rev 1215)
@@ -7,4 +7,5 @@
           , 'inserting_code' : 'inserting code'
           , 'best_practices' : 'best practices' 
           , 'multi_module_development' :  'multi-module development'
+          , 'split_module' : 'splitting generated code to files'
 }


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

[pygccxml-commit] SF.net SVN: pygccxml: [1217] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 1217
          http://pygccxml.svn.sourceforge.net/pygccxml/?rev=1217&view=rev
Author:   roman_yakovenko
Date:     2008-01-03 04:25:07 -0800 (Thu, 03 Jan 2008)

Log Message:
-----------
updating docs

Modified Paths:
--------------
    pyplusplus_dev/docs/documentation/how_to.rest
    pyplusplus_dev/docs/documentation/split_module.rest

Modified: pyplusplus_dev/docs/documentation/how_to.rest
===================================================================
--- pyplusplus_dev/docs/documentation/how_to.rest	2008-01-03 10:23:45 UTC (rev 1216)
+++ pyplusplus_dev/docs/documentation/how_to.rest	2008-01-03 12:25:07 UTC (rev 1217)
@@ -376,6 +376,35 @@
 The nice thing about this approach is that now `Python`_ users have "normal"
 class name and you have short file name.
 
+-------------------
+Full\relative paths
+-------------------
+
+Consider next file layout:
+::
+
+  boost/
+    date_time/
+      ptime.hpp
+      time_duration.hpp
+      date_time.hpp //main header, which include all other header files
+
+Py++ currently does not handle relative paths as input very well, so it is 
+recommended that you use ``os.path.abspath()`` to transform the header file to 
+be processed into an absolute path:
+  
+.. code-block:: Python
+    
+   #Next code will expose nothing
+   mb = module_builder( [ 'date_time/date_time.hpp' ], ... ) 
+   mb.split_module( ... )
+
+   #while this one will work as expected
+   import os
+   mb = module_builder( [ os.path.abspath('date_time/date_time.hpp') ], ... ) 
+   mb.split_module( ... )
+
+
 .. _`Py++` : ./../pyplusplus.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
 .. _`Python`: http://www.python.org

Modified: pyplusplus_dev/docs/documentation/split_module.rest
===================================================================
--- pyplusplus_dev/docs/documentation/split_module.rest	2008-01-03 10:23:45 UTC (rev 1216)
+++ pyplusplus_dev/docs/documentation/split_module.rest	2008-01-03 12:25:07 UTC (rev 1217)
@@ -209,11 +209,23 @@
   * ``huge_classes`` - list of names of huge classes
   * ``on_unused_file_found`` - callable object, which is called every time
     `Py++`_ found that previously generated file is not in use anymore.
-  * ``use_files_sum_repository`` - Py++ can generate file, which will contain md5 
-    sum of every generated file. Next time you generate code, md5sum will be loaded 
-    from the file and compared. This could speed-up code generation process by 10-15%
-    on big projects.
+  * ``use_files_sum_repository``
+    `Py++`_ is able to store md5 sum of the generated files in a file. Next 
+    time you will generate code, Py++ will compare generated file content 
+    against the sum, instead of loading the content of the previously generated
+    file from the disk and comparing against it. 
 
+    "<your module name>.md5.sum" is the file, that will be generated in the
+    ``dir_name`` directory.
+
+    Enabling this functionality should give you 10-15% of performance boost.
+
+    Warning: If you changed manually some of the files - don't forget to delete
+    the relevant line from "md5.sum" file. You can also delete the whole file. 
+    If the file is missing, Py++ will use old plain method of comparing content 
+    of the files. It will not re-write "unchanged" files and you will not be 
+    forced to recompile the whole project.
+
 *  
   .. code-block:: Python
 
@@ -227,9 +239,6 @@
   * ``number_of_files`` - the desired number of generated source files
   
 
-
-
-
 .. _`Py++` : ./../pyplusplus.html
 .. _`pygccxml` : ./../../pygccxml/pygccxml.html
 .. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

[pygccxml-commit] SF.net SVN: pygccxml: [1218] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 1218
          http://pygccxml.svn.sourceforge.net/pygccxml/?rev=1218&view=rev
Author:   roman_yakovenko
Date:     2008-01-05 12:47:42 -0800 (Sat, 05 Jan 2008)

Log Message:
-----------
improving docs

Added Paths:
-----------
    pyplusplus_dev/docs/documentation/how_to/
    pyplusplus_dev/docs/documentation/how_to/best_practices.rest
    pyplusplus_dev/docs/documentation/how_to/exception_translation.rest
    pyplusplus_dev/docs/documentation/how_to/hints.rest
    pyplusplus_dev/docs/documentation/how_to/how_to.rest
    pyplusplus_dev/docs/documentation/how_to/templates.rest
    pyplusplus_dev/docs/documentation/how_to/www_configuration.py

Added: pyplusplus_dev/docs/documentation/how_to/best_practices.rest
===================================================================
--- pyplusplus_dev/docs/documentation/how_to/best_practices.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/how_to/best_practices.rest	2008-01-05 20:47:42 UTC (rev 1218)
@@ -0,0 +1,176 @@
+==============
+Best practices
+==============
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+`Py++`_ has reach interface and a lot of functionality. Sometimes reach
+interface helps, but sometimes it can confuse. This document will describe how
+effectively to use `Py++`_.
+
+------------
+Big projects
+------------
+
+Definition
+----------
+
+First of all, let me to define "big project". "Big project" is a project with
+few hundred of header files. `Py++`_ was born to create `Python`_ bindings
+for such projects. If you take a look `here`__ you will find few such projects.
+
+.. __ : ./../../pyplusplus/quotes.html
+
+Tips
+----
+
+* Create one header file, which will include all project header files.
+
+  Doing it this way makes it so `GCC-XML`_ is only called once and it reduces the
+  overhead that would occur if you pass `GCC-XML`_ all the files individually.
+  Namely `GCC-XML`_ would have to run hundreds of times and each call would
+  actually end up including quite a bit of common code anyway. This way takes a
+  `GCC-XML`_ processing time from multiple hours with gigabytes of caches to a
+  couple minutes with a reasonable cache size.
+
+  You can read more about different caches supported by `pygccxml`_ `here`__.
+  ``module_builder_t.__init__`` method takes reference to an instance of cache
+  class or ``None``:
+
+  .. code-block:: Python
+
+    from module_builder import *
+    mb = module_builder_t( ..., cache=file_cache_t( path to project cache file ), ... )
+
+* Single header file, will also improve performance compiling the generated bindings.
+
+  When `Py++`_ generated the bindings, you have a lot of .cpp files to
+  compile. The project you are working on is big. I am sure it takes a lot of
+  time to compile projects that depend on it. Generated code also depend on it,
+  more over this code contains a lot of template instantiations. So it could
+  take a great deal of time to compile it. Allen Bierbaum investigated this
+  problem. He found out that most of the time is really spent processing all the
+  headers, templates, macros from the project and from the boost library. So he
+  come to conclusion, that in order to improve compilation speed, user should
+  be able to control( to be able to generate ) precompiled header file. He
+  implemented an initial version of the functionality. After small discussion,
+  we agreed on next interface:
+
+  .. code-block:: Python
+
+    class module_builder_t( ... ):
+        ...
+        def split_module( self, directory_path, huge_classes=None, precompiled_header=None ):
+            ...
+
+  ``precompiled_header`` argument could be ``None`` or string, that contains
+  name of precompiled header file, which will be created in the directory.
+  `Py++`_ will add to it header files from `Boost.Python`_ library and
+  your header files.
+
+  What is ``huge_classes`` argument for? ``huge_classes`` could be ``None`` or
+  list of references to class declarations. It is there to provide a solution to
+  `this error`_. `Py++`_ will automatically split generated code for the
+  huge classes to few files:
+
+  .. code-block:: Python
+
+    mb = module_builder_t( ... )
+    ...
+    my_big_class = mb.class_( my_big_class )
+    mb.split_module( ..., huge_classes=[my_big_class], ... )
+
+  * **Caveats**
+   
+    Consider next file layout:
+    ::
+
+      boost/
+        date_time/
+          ptime.hpp
+          time_duration.hpp
+          date_time.hpp //main header, which include all other header files
+
+    Py++ currently does not handle relative paths as input very well, so it is 
+    recommended that you use "os.path.abspath()" to transform the header file to 
+    be processed into an absolute path:
+    
+    .. code-block:: Python
+    
+      #Next code will expose nothing
+      mb = module_builder( [ 'date_time/date_time.hpp' ], ... ) 
+
+      #while this one will work as expected
+      import os
+      mb = module_builder( [ os.path.abspath('date_time/date_time.hpp') ], ... ) 
+
+.. _`this error` : http://boost.org/libs/python/doc/v2/faq.html#c1204
+.. __ : ./../../pygccxml/design.html
+
+* Keep the declaration tree small.
+
+  When parsing the header files to build the declaration tree, there will also
+  be the occasional "junk" declaration inside the tree that is not relevant to
+  the bindings you want to generate. These extra declarations come from header
+  files that were included somewhere in the header files that you were actually
+  parsing (e.g. if that library uses the STL or OpenGL or other system headers
+  then the final declaration tree will contain those declarations, too).
+  It can happen that the majority of declarations in your declaration tree are
+  such "junk" declarations that are not required for generating your bindings
+  and that just slow down the generation process (reading the declaration cache
+  and doing queries will take longer).
+
+  To speed up your generation process you might want to consider making the
+  declaration tree as small as possible and only store those declarations that
+  somehow have an influence on the bindings. Ideally, this is done as early
+  as possible and luckily gccxml provides an option that allows you to reduce
+  the number of declarations that it will store in the output XML file. You can
+  specify one or more declarations using the ``-fxml-start`` option and only
+  those sub-tree starting at the specified declarations will be written. For
+  example, if you specify the name of a particular class, only this class
+  and all its members will get written. Or if your project already uses
+  a dedicated namespace you can simply use this namespace as a starting point
+  and all declarations stemming from system headers will be ignored (except
+  for those declarations that are actually used within your library).
+
+  In the ``pygccxml`` package you can set the value for the ``-fxml-start``
+  option using the ``start_with_declarations`` attribute of the
+  ``pygccxml.parser.config_t`` object that you are passing to the parser.
+
+* Use `Py++`_ repository of generated files md5 sum.
+
+  `Py++`_ is able to store md5 sum of generated files in a file. Next time you 
+  will generate code, `Py++`_ will compare generated file content against the sum,
+  instead of loading the content of the previously generated file from the disk 
+  and comparing against it. 
+    
+  .. code-block:: Python
+
+    mb = module_builder_t( ... )
+    ...
+    my_big_class = mb.class_( my_big_class )
+    mb.split_module( ..., use_files_sum_repository=True )
+
+  `Py++`_ will generate file named "<your module name>.md5.sum" in the directory
+  it will generate all the files.
+  
+  Enabling this functionality should give you 10-15% of performance boost.
+  
+  * **Caveats**
+  
+    If you changed manually some of the files - don't forget to delete the relevant
+    line from "md5.sum" file. You can also delete the whole file. If the file is
+    missing, `Py++`_ will use old plain method of comparing content of the files.
+    It will not re-write "unchanged" files and you will not be forced to recompile 
+    the whole project.
+
+
+.. _`Py++` : ./../pyplusplus.html
+.. _`pygccxml` : ./../../pygccxml/pygccxml.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org

Added: pyplusplus_dev/docs/documentation/how_to/exception_translation.rest
===================================================================
--- pyplusplus_dev/docs/documentation/how_to/exception_translation.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/how_to/exception_translation.rest	2008-01-05 20:47:42 UTC (rev 1218)
@@ -0,0 +1,65 @@
+=========================================
+How to register an exception translation?
+=========================================
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+Boost.Python provides functionality to translate any C++ exception to a Python one.
+`Py++`_ provides a convenient API to do this.
+
+By the way, be sure to take a look on "`troubleshooting guide - exceptions`_".
+The guide will introduces a complete solution for handling exceptions within
+Python scripts.
+
+.. _`troubleshooting guide - exceptions` :  ./../../troubleshooting_guide/exceptions/exceptions.html
+
+--------
+Solution
+--------
+
+`Boost.Python exception translator documentation`_ contains a complete explanation
+what should be done. I will use that example, to show how it could be done with
+`Py++`_:
+
+.. code-block:: Python
+
+   from pyplusplus import module_builder_t
+
+   mb = module_builder_t( ... )
+   my_exception = mb.class_( 'my_exception' )
+
+   translate_code = 'PyErr_SetString(PyExc_RuntimeError, exc.what();'
+   my_exception.exception_translation_code = translate_code
+
+That's all, really. `Py++`_ will generate for you the ``translate`` function
+definition and than will register it.
+
+I think this is a most popular use case - translate a C++ exception to a string
+and than to create an instance of Python built-in exception. That is exactly why
+`Py++`_ provides additional API:
+
+.. code-block:: Python
+
+   mb = module_builder_t( ... )
+   my_exception = mb.class_( 'my_exception' )
+
+   my_exception.translate_exception_to_string( 'PyExc_RuntimeError', 'exc.what()')
+
+The first argument of ``translate_exception_to_string`` method is exception type,
+The second one is a string - code that converts your exception to ``const char*``.
+
+As you see, it is really simple to add exception translation to your project.
+
+One more point, in both pieces of code I used "``exc``" as the name of ``my_exception``
+class instance. This is a predefined name. I am not going to change it without
+any good reason, any time soon :-).
+
+.. _`Boost.Python exception translator documentation` : http://boost.org/libs/python/doc/v2/exception_translator.html
+.. _`Py++` : ./../../pyplusplus.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org

Added: pyplusplus_dev/docs/documentation/how_to/hints.rest
===================================================================
--- pyplusplus_dev/docs/documentation/how_to/hints.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/how_to/hints.rest	2008-01-05 20:47:42 UTC (rev 1218)
@@ -0,0 +1,64 @@
+=====
+Hints 
+=====
+
+.. contents:: Table of contents
+
+----------------------------------
+Class template instantiation alias
+----------------------------------
+
+`Py++`_ has nice feature. If you define ``typedef`` for instantiated class 
+template, than `Py++`_ will use it as a `Python`_ class name.
+
+For example:
+
+.. code-block:: C++
+
+  #include <vector>
+  typedef std::vector< int > numbers;
+  numbers generate_n(){
+      ...
+  }
+
+`Py++`_ will use "numbers" as Python class name:
+
+.. code-block:: C++
+
+  using boost::python;
+  class_< std::vector< int > >( "numbers" )
+      ...
+  ;
+
+`Py++`_ will pick up the alias, only in case the class has single "typedef". 
+
+``pyplusplus::aliases`` namespace
+---------------------------------
+
+The previous approach is "implicit" - `Py++`_ does something behind the scene. 
+Recently (version 0.8.6 ), another approach was introduced:
+
+.. code-block:: C++
+
+  #include <vector>
+  
+  namespace pyplusplus{ namespace aliases{
+  //^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+      typedef std::vector< int > numbers;
+    
+  } } //pyplusplus::aliases
+
+The idea is that you create namespace with a special name - ``pyplusplus::aliases``
+and `Py++`_ automatically picks the class aliases from it. In case you accidentally 
+introduced two or more different aliases to the same class, it will pick the 
+longest one and print a warning. Other advantages of the approach:
+
+* you are not forced to learn new API
+
+* you continue to use your favorite editor and familiar language
+
+.. _`Py++` : ./../pyplusplus.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org
+

Added: pyplusplus_dev/docs/documentation/how_to/how_to.rest
===================================================================
--- pyplusplus_dev/docs/documentation/how_to/how_to.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/how_to/how_to.rest	2008-01-05 20:47:42 UTC (rev 1218)
@@ -0,0 +1,175 @@
+============
+How to ... ?
+============
+
+.. contents:: Table of contents
+
+`How to deal with templates?`_
+
+.. _`How to deal with templates?` : ./templates.html
+
+`How to add custom exception translation?`_
+
+.. _ `How to add custom exception translation?` : custom_exception_translation.html
+
+-------------------------------------------------------
+How to expose function, which has hand-written wrapper?
+-------------------------------------------------------
+.. code-block:: C++
+
+  struct window_t{
+      ...
+      void get_size( int& height, int& widht ) const;
+  };
+
+You can not expose ``get_size`` function as is - ``int`` is immutable type in
+Python. So, we need to create a wrapper to the function:
+
+.. code-block:: C++
+
+  boost::python::tuple get_size_wrapper( const window_t& win ){
+      int height(0), width( 0 );
+      win.get_size( height, widht );
+      return boost::python::make_tuple( height, width );
+  }
+
+.. code-block:: C++
+
+  class_<window_t>( ... )
+      .def( "get_size", &get_size_wrapper )
+      ...
+  ;
+
+Now, after you know how this problem is solved. I will show how this solution
+could be integrated with `Py++`_.
+
+.. code-block:: Python
+
+  wrapper_code = \
+  """
+     static boost::python::tuple get_size( const window_t& win ){
+        int height(0), width( 0 );
+        win.get_size( height, width );
+        return boost::python::make_tuple( height, width );
+    }
+  """
+
+.. code-block:: Python
+
+  registration_code = 'def( "get_size", &%s::get_size )' % window.wrapper_alias
+
+.. code-block:: Python
+
+  mb = module_builder_t( ... )
+  window = mb.class_( "window_t" )
+  window.member_function( "get_size" ).exclude()
+  window.add_wrapper_code( wrapper_code )
+  window.registration_code( registration_code )
+
+That's all.
+
+-------------------------------------------------------------
+Fatal error C1204:Compiler limit: internal structure overflow
+-------------------------------------------------------------
+
+If you get this error, than the generated file is too big. You will have to split
+it to few files. Well, not you but `Py++`_, you will only have to tell it to do
+that.
+
+If you are using ``module_builder_t.write_module`` method, consider to switch
+to ``module_builder_t.split_module``.
+
+If you are using ``split_module``, but still the generated code for some class
+could not be compiled, because of the error, you can ask `Py++`_ to split the
+code generated for class to be split to few cpp files.
+
+For more information, please read the documentation.
+
+
+-------------------------------------
+Py++ generated file name is too long!
+-------------------------------------
+There are use cases, when `Py++`_ generated file name is too long. In some cases
+the code generation process even fails because of this. What can you do in order
+to eliminate the problem?
+
+First of all the problem arises when you expose template instantiated classes
+and you did not set the class alias.
+
+Let me explain:
+
+.. code-block:: C++
+
+  template < class T>
+  struct holder{ ... };
+
+
+Lets say that you want to export ``holder< int >`` class. Class name in `Python`_
+has few `constraints`_. `Py++`_ is aware of the `constraints`_ and if you didn't
+set an alias to the class, `Py++`_ will do it for you. In this case,
+"holder_less_int_grate\_" is the generated alias. Obviously it is much longer
+and not readable.
+
+.. _`constraints` : http://www.python.org/doc/current/ref/identifiers.html
+
+There are few pretty good reasons for this behavior:
+
+* when you just start to work on `Python`_ bindings concentrate your attention
+  on really important things
+
+* if you forgot to set the class alias your users still can use the class
+  functionality, however the class name will be a little bit ugly.
+
+
+In this case the generate alias for ``holder`` instantiation is relatively short.
+Imagine how long it could be for ``std::map`` instantiation.
+
+`Py++`_ uses class alias for the file name. So if you want to force `Py++`_ to
+generate files with short name, you have to set class alias:
+
+.. code-block:: Python
+
+  from pyplusplus import module_builder
+
+  mb = module_builder_t( ... )
+  holder = mb.class_( 'holder< int >' )
+  holder.alias = 'IntHolder'
+  #next line has same effect as the previous one:
+  holder.rename( 'IntHolder' )
+
+The nice thing about this approach is that now `Python`_ users have "normal"
+class name and you have short file name.
+
+-------------------
+Full\relative paths
+-------------------
+
+Consider next file layout:
+::
+
+  boost/
+    date_time/
+      ptime.hpp
+      time_duration.hpp
+      date_time.hpp //main header, which include all other header files
+
+Py++ currently does not handle relative paths as input very well, so it is
+recommended that you use ``os.path.abspath()`` to transform the header file to
+be processed into an absolute path:
+
+.. code-block:: Python
+
+   #Next code will expose nothing
+   mb = module_builder( [ 'date_time/date_time.hpp' ], ... )
+   mb.split_module( ... )
+
+   #while this one will work as expected
+   import os
+   mb = module_builder( [ os.path.abspath('date_time/date_time.hpp') ], ... )
+   mb.split_module( ... )
+
+
+.. _`Py++` : ./../pyplusplus.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org

Added: pyplusplus_dev/docs/documentation/how_to/templates.rest
===================================================================
--- pyplusplus_dev/docs/documentation/how_to/templates.rest	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/how_to/templates.rest	2008-01-05 20:47:42 UTC (rev 1218)
@@ -0,0 +1,196 @@
+===========================
+How to deal with templates?
+===========================
+
+.. contents:: Table of contents
+
+------------
+Introduction
+------------
+
+I would like to introduce next piece of code I will use for most exlanations.
+
+.. code-block:: C++
+
+   // file point.h
+   template< class T>
+   struct point_t{
+       T x, y;
+   };
+
+   template <class T>
+   double distance( const point_t<T>& point ){
+       return sqrt( point.x * point.x + point.y*point.y );
+   }
+
+   struct environment_t{
+      ...
+      template< class T>
+      T get_value(const std::string& name);
+      ...
+   };
+
+----------------------
+Template instantiation
+----------------------
+
+First of all you should understand, that you can not export template itself, but
+only its instantiations.
+
+You can instantiate template class using operator ``sizeof``:
+
+.. code-block:: C++
+
+   sizeof( point_t<int> );
+
+
+In order to instantiate a function you have to call it:
+
+.. code-block:: C++
+
+   void instantiate(){
+       double x = distance( point_t<t>() );
+
+       environment_t env;
+       std::string path = env.get_value< std::string >( "PATH" );
+       int version = env.get_value< int >( "VERSION" );
+   }
+
+You should put that code in some header file, parsed by GCC-XML.
+
+"Dynamic" instantiation
+-----------------------
+If you have a template class, which should be instantiated with many types, you
+can create a small code generator, which will "instantiate the class". It is
+pretty easy to blend together the generated code and the existing one:
+
+.. code-block:: Python
+
+   from module_builder import module_builder_t, create_text_fc
+
+   def generate_instantiations_string( ... ):
+      ...
+
+   code = generate_instantiations_string( ... )
+
+   mb = module_builder_t( [ create_text_fc( code ), other header files ], ... )
+   ...
+
+Function ``create_text_fc`` allows you to extract declarations from the string,
+which contains valid C++ code. It creates temporal header file and compiles it.
+
+.. __ : ./../../../pygccxml/design.html#parser-configuration-classes
+
+----------------------------------
+Functions templated on return type
+----------------------------------
+
+.. code-block:: C++
+
+   environment_t env;
+   std::string path = env.get_value< std::string >( "PATH" );
+   int version = env.get_value< int >( "VERSION" );
+
+
+`GCC-XML`_ provides information for both instantiations:
+
+    * ``get_value<int>``
+
+    * ``get_value< std::string >``
+
+But, in this case there is a catch: the name of both functions is "**get_value**".
+The only difference is "return type".
+
+In this situation, `Py++`_ will generate code that contains errors. If your are
+lucky, it depends on the compiler you use, the generated code will not compile.
+Otherwise, you will discover the errors while testing the bindings.
+
+Generated code:
+
+.. code-block:: C++
+
+  bp::class_< environment_t >( "environment_t" )
+      ...
+      .def( "get_value"
+            , (int ( ::environment_t::* )( ::std::string const & ) )( &::environment_t::get_value ) )
+      .def( "get_value"
+            , (::std::string ( ::environment_t::* )( ::std::string const & ) )( &::environment_t::get_value ) );
+
+The correct code:
+
+.. code-block:: C++
+
+  bp::class_< environment_t >( "environment_t" )
+      .def( "get_value"
+            , (int ( ::environment_t::* )( ::std::string const & ) )( &::environment_t::get_value< int > ) )
+            //--------------------------------------------------------------------------^^^^^^^^^^^^^^^^
+      .def( "get_value"
+            , (::std::string ( ::environment_t::* )( ::std::string const & ) )( &::environment_t::get_value< std::string > ) );
+            //------------------------------------------------------------------------------------^^^^^^^^^^^^^^^^^^^^^^^^
+
+The perfect one:
+
+.. code-block:: C++
+
+  bp::class_< environment_t >( "environment_t" )
+      ...
+      .def( "get_value", &::environment_t::get_value< int > )
+      .def( "get_value", &::environment_t::get_value< std::string > );
+
+
+Work-around
+-----------
+
+`Py++`_ contains a work-around to the problem:
+
+.. code-block:: Python
+
+   mb = module_builder_t( ..., optimize_queries=False, ... )
+   environment = mb.class_( "environment_t" )
+   for f in environment.member_functions( "get_value" ):
+       #set the function alias
+       f.alias = f.name + "_" + f.return_type.decl_string
+       #correct function name
+       f.name = f.demangled_name
+   #you still want the queries to run fast
+   mb.run_query_optimizer()
+
+Before you read the rest of the solution, you should understand what is
+"name mangling" means. If you don't, consider reading about it on `Wikipedia`__ .
+
+.. __ : http://en.wikipedia.org/wiki/Name_mangling
+
+The solution is pretty simple. `GCC-XML`_ reports mangled and demangled function
+names. The demangled function name contains "real" function name:
+``get_value< used type >``. You only have to instruct `Py++`_ to use it.
+
+`Py++`_ does not use by default demangled function name for mainly one reason.
+Demangled function name is a string that contains a lot of information. `Py++`_
+implements a parser, which extracts the only relevant one. The parser
+implementation is a little bit complex and was not heavily tested. By "heavily" I
+mean that I tested it on a lot of crazy use cases and on a real project, but
+there is always some new use case out there. I am almost sure it will work for
+you. The problem, we deal with, is rare, so by default "demangled_name"
+feature is turned off.
+
+By the way, almost the same problem exists for template classes. But, in the
+classes use case `Py++`_ uses demangled name by default.
+
+-----------
+Help wanted
+-----------
+I understand that the provided solutions are not perfect and that something
+better and simpler should be done. Unfortunatelly the priority of this task is
+low.
+
+Allen Bierbaum has few suggestion that could improve `Py++`_. He created a
+`wiki page`_, that discuss possible solutions. Your contribution is welcome too!
+
+.. _`wiki page` : https://realityforge.vrsource.org/view/PyppApi/TemplateSupport
+
+
+
+.. _`Py++` : ./../pyplusplus.html
+.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
+.. _`Python`: http://www.python.org
+.. _`GCC-XML`: http://www.gccxml.org

Added: pyplusplus_dev/docs/documentation/how_to/www_configuration.py
===================================================================
--- pyplusplus_dev/docs/documentation/how_to/www_configuration.py	                        (rev 0)
+++ pyplusplus_dev/docs/documentation/how_to/www_configuration.py	2008-01-05 20:47:42 UTC (rev 1218)
@@ -0,0 +1,10 @@
+name = 'how to ... ?'
+#main_html_file = 'index.html'
+
+names = { 'hints' : 'hints'
+          , 'how_to' : 'how to'
+          , 'templates' : 'deal with templates'
+          , 'best_practices' : 'best practices'
+          , 'exception_translation' : 'exception translation'
+}
+


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

[pygccxml-commit] SF.net SVN: pygccxml: [1220] pyplusplus_dev/docs/documentation

[<rom...@us...>]

Revision: 1220
          http://pygccxml.svn.sourceforge.net/pygccxml/?rev=1220&view=rev
Author:   roman_yakovenko
Date:     2008-01-05 13:19:44 -0800 (Sat, 05 Jan 2008)

Log Message:
-----------
moving docs

Removed Paths:
-------------
    pyplusplus_dev/docs/documentation/best_practices.rest
    pyplusplus_dev/docs/documentation/hints.rest
    pyplusplus_dev/docs/documentation/how_to.rest

Deleted: pyplusplus_dev/docs/documentation/best_practices.rest
===================================================================
--- pyplusplus_dev/docs/documentation/best_practices.rest	2008-01-05 21:18:15 UTC (rev 1219)
+++ pyplusplus_dev/docs/documentation/best_practices.rest	2008-01-05 21:19:44 UTC (rev 1220)
@@ -1,176 +0,0 @@
-==============
-Best practices
-==============
-
-.. contents:: Table of contents
-
-------------
-Introduction
-------------
-
-`Py++`_ has reach interface and a lot of functionality. Sometimes reach
-interface helps, but sometimes it can confuse. This document will describe how
-effectively to use `Py++`_.
-
-------------
-Big projects
-------------
-
-Definition
-----------
-
-First of all, let me to define "big project". "Big project" is a project with
-few hundred of header files. `Py++`_ was born to create `Python`_ bindings
-for such projects. If you take a look `here`__ you will find few such projects.
-
-.. __ : ./../../pyplusplus/quotes.html
-
-Tips
-----
-
-* Create one header file, which will include all project header files.
-
-  Doing it this way makes it so `GCC-XML`_ is only called once and it reduces the
-  overhead that would occur if you pass `GCC-XML`_ all the files individually.
-  Namely `GCC-XML`_ would have to run hundreds of times and each call would
-  actually end up including quite a bit of common code anyway. This way takes a
-  `GCC-XML`_ processing time from multiple hours with gigabytes of caches to a
-  couple minutes with a reasonable cache size.
-
-  You can read more about different caches supported by `pygccxml`_ `here`__.
-  ``module_builder_t.__init__`` method takes reference to an instance of cache
-  class or ``None``:
-
-  .. code-block:: Python
-
-    from module_builder import *
-    mb = module_builder_t( ..., cache=file_cache_t( path to project cache file ), ... )
-
-* Single header file, will also improve performance compiling the generated bindings.
-
-  When `Py++`_ generated the bindings, you have a lot of .cpp files to
-  compile. The project you are working on is big. I am sure it takes a lot of
-  time to compile projects that depend on it. Generated code also depend on it,
-  more over this code contains a lot of template instantiations. So it could
-  take a great deal of time to compile it. Allen Bierbaum investigated this
-  problem. He found out that most of the time is really spent processing all the
-  headers, templates, macros from the project and from the boost library. So he
-  come to conclusion, that in order to improve compilation speed, user should
-  be able to control( to be able to generate ) precompiled header file. He
-  implemented an initial version of the functionality. After small discussion,
-  we agreed on next interface:
-
-  .. code-block:: Python
-
-    class module_builder_t( ... ):
-        ...
-        def split_module( self, directory_path, huge_classes=None, precompiled_header=None ):
-            ...
-
-  ``precompiled_header`` argument could be ``None`` or string, that contains
-  name of precompiled header file, which will be created in the directory.
-  `Py++`_ will add to it header files from `Boost.Python`_ library and
-  your header files.
-
-  What is ``huge_classes`` argument for? ``huge_classes`` could be ``None`` or
-  list of references to class declarations. It is there to provide a solution to
-  `this error`_. `Py++`_ will automatically split generated code for the
-  huge classes to few files:
-
-  .. code-block:: Python
-
-    mb = module_builder_t( ... )
-    ...
-    my_big_class = mb.class_( my_big_class )
-    mb.split_module( ..., huge_classes=[my_big_class], ... )
-
-  * **Caveats**
-   
-    Consider next file layout:
-    ::
-
-      boost/
-        date_time/
-          ptime.hpp
-          time_duration.hpp
-          date_time.hpp //main header, which include all other header files
-
-    Py++ currently does not handle relative paths as input very well, so it is 
-    recommended that you use "os.path.abspath()" to transform the header file to 
-    be processed into an absolute path:
-    
-    .. code-block:: Python
-    
-      #Next code will expose nothing
-      mb = module_builder( [ 'date_time/date_time.hpp' ], ... ) 
-
-      #while this one will work as expected
-      import os
-      mb = module_builder( [ os.path.abspath('date_time/date_time.hpp') ], ... ) 
-
-.. _`this error` : http://boost.org/libs/python/doc/v2/faq.html#c1204
-.. __ : ./../../pygccxml/design.html
-
-* Keep the declaration tree small.
-
-  When parsing the header files to build the declaration tree, there will also
-  be the occasional "junk" declaration inside the tree that is not relevant to
-  the bindings you want to generate. These extra declarations come from header
-  files that were included somewhere in the header files that you were actually
-  parsing (e.g. if that library uses the STL or OpenGL or other system headers
-  then the final declaration tree will contain those declarations, too).
-  It can happen that the majority of declarations in your declaration tree are
-  such "junk" declarations that are not required for generating your bindings
-  and that just slow down the generation process (reading the declaration cache
-  and doing queries will take longer).
-
-  To speed up your generation process you might want to consider making the
-  declaration tree as small as possible and only store those declarations that
-  somehow have an influence on the bindings. Ideally, this is done as early
-  as possible and luckily gccxml provides an option that allows you to reduce
-  the number of declarations that it will store in the output XML file. You can
-  specify one or more declarations using the ``-fxml-start`` option and only
-  those sub-tree starting at the specified declarations will be written. For
-  example, if you specify the name of a particular class, only this class
-  and all its members will get written. Or if your project already uses
-  a dedicated namespace you can simply use this namespace as a starting point
-  and all declarations stemming from system headers will be ignored (except
-  for those declarations that are actually used within your library).
-
-  In the ``pygccxml`` package you can set the value for the ``-fxml-start``
-  option using the ``start_with_declarations`` attribute of the
-  ``pygccxml.parser.config_t`` object that you are passing to the parser.
-
-* Use `Py++`_ repository of generated files md5 sum.
-
-  `Py++`_ is able to store md5 sum of generated files in a file. Next time you 
-  will generate code, `Py++`_ will compare generated file content against the sum,
-  instead of loading the content of the previously generated file from the disk 
-  and comparing against it. 
-    
-  .. code-block:: Python
-
-    mb = module_builder_t( ... )
-    ...
-    my_big_class = mb.class_( my_big_class )
-    mb.split_module( ..., use_files_sum_repository=True )
-
-  `Py++`_ will generate file named "<your module name>.md5.sum" in the directory
-  it will generate all the files.
-  
-  Enabling this functionality should give you 10-15% of performance boost.
-  
-  * **Caveats**
-  
-    If you changed manually some of the files - don't forget to delete the relevant
-    line from "md5.sum" file. You can also delete the whole file. If the file is
-    missing, `Py++`_ will use old plain method of comparing content of the files.
-    It will not re-write "unchanged" files and you will not be forced to recompile 
-    the whole project.
-
-
-.. _`Py++` : ./../pyplusplus.html
-.. _`pygccxml` : ./../../pygccxml/pygccxml.html
-.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
-.. _`Python`: http://www.python.org
-.. _`GCC-XML`: http://www.gccxml.org

Deleted: pyplusplus_dev/docs/documentation/hints.rest
===================================================================
--- pyplusplus_dev/docs/documentation/hints.rest	2008-01-05 21:18:15 UTC (rev 1219)
+++ pyplusplus_dev/docs/documentation/hints.rest	2008-01-05 21:19:44 UTC (rev 1220)
@@ -1,64 +0,0 @@
-=====
-Hints 
-=====
-
-.. contents:: Table of contents
-
-----------------------------------
-Class template instantiation alias
-----------------------------------
-
-`Py++`_ has nice feature. If you define ``typedef`` for instantiated class 
-template, than `Py++`_ will use it as a `Python`_ class name.
-
-For example:
-
-.. code-block:: C++
-
-  #include <vector>
-  typedef std::vector< int > numbers;
-  numbers generate_n(){
-      ...
-  }
-
-`Py++`_ will use "numbers" as Python class name:
-
-.. code-block:: C++
-
-  using boost::python;
-  class_< std::vector< int > >( "numbers" )
-      ...
-  ;
-
-`Py++`_ will pick up the alias, only in case the class has single "typedef". 
-
-``pyplusplus::aliases`` namespace
----------------------------------
-
-The previous approach is "implicit" - `Py++`_ does something behind the scene. 
-Recently (version 0.8.6 ), another approach was introduced:
-
-.. code-block:: C++
-
-  #include <vector>
-  
-  namespace pyplusplus{ namespace aliases{
-  //^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-      typedef std::vector< int > numbers;
-    
-  } } //pyplusplus::aliases
-
-The idea is that you create namespace with a special name - ``pyplusplus::aliases``
-and `Py++`_ automatically picks the class aliases from it. In case you accidentally 
-introduced two or more different aliases to the same class, it will pick the 
-longest one and print a warning. Other advantages of the approach:
-
-* you are not forced to learn new API
-
-* you continue to use your favorite editor and familiar language
-
-.. _`Py++` : ./../pyplusplus.html
-.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
-.. _`Python`: http://www.python.org
-.. _`GCC-XML`: http://www.gccxml.org
-

Deleted: pyplusplus_dev/docs/documentation/how_to.rest
===================================================================
--- pyplusplus_dev/docs/documentation/how_to.rest	2008-01-05 21:18:15 UTC (rev 1219)
+++ pyplusplus_dev/docs/documentation/how_to.rest	2008-01-05 21:19:44 UTC (rev 1220)
@@ -1,411 +0,0 @@
-============
-How to ... ?
-============
-
-.. contents:: Table of contents
-
-----------------------------------------
-How to add custom exception translation?
-----------------------------------------
-
-.. code-block:: C++
-
-  struct my_exception{
-    ...
-    const std::string& error() const;
-  }
-
-First of all lets define ``translate`` function:
-
-.. code-block:: Python
-
-  translate_code = \
-  """
-    void translate(const my_exception &exception){
-        PyErr_SetString( PyExc_RuntimeError, exception.error().c_str() );
-    }
-  """
-
-.. code-block:: Python
-
-  mb = module_builder_t( ... )
-  mb.add_declaration_code( translate_code )
-
-
-Now we should register it:
-
-.. code-block:: Python
-
-  registration_code = "boost::python::register_exception_translator<my_exception>(&translate);"
-  mb.add_registration_code( registration_code )
-
-Small usage advice.
--------------------
-
-`Py++`_ allows you to define a query that will return you all exception classes:
-
-.. code-block:: Python
-
-  mb = module_builder_t( ... )
-  exception_classes = mb.decls( lambda decl: decl.name.endswith( 'exception' ) )
-
-Now you can iterate on ``exception_classes``, generate and register translate
-code for every class.
-
-That's all.
-
--------------------------------------------------------
-How to expose function, which has hand-written wrapper?
--------------------------------------------------------
-.. code-block:: C++
-
-  struct window_t{
-      ...
-      void get_size( int& height, int& widht ) const;
-  };
-
-You can not expose ``get_size`` function as is - ``int`` is immutable type in
-Python. So, we need to create a wrapper to the function:
-
-.. code-block:: C++
-
-  boost::python::tuple get_size_wrapper( const window_t& win ){
-      int height(0), width( 0 );
-      win.get_size( height, widht );
-      return boost::python::make_tuple( height, width );
-  }
-
-.. code-block:: C++
-
-  class_<window_t>( ... )
-      .def( "get_size", &get_size_wrapper )
-      ...
-  ;
-
-Now, after you know how this problem is solved. I will show how this solution
-could be integrated with `Py++`_.
-
-.. code-block:: Python
-
-  wrapper_code = \
-  """
-     static boost::python::tuple get_size( const window_t& win ){
-        int height(0), width( 0 );
-        win.get_size( height, width );
-        return boost::python::make_tuple( height, width );
-    }
-  """
-
-.. code-block:: Python
-
-  registration_code = 'def( "get_size", &%s::get_size )' % window.wrapper_alias
-
-.. code-block:: Python
-
-  mb = module_builder_t( ... )
-  window = mb.class_( "window_t" )
-  window.member_function( "get_size" ).exclude()
-  window.add_wrapper_code( wrapper_code )
-  window.registration_code( registration_code )
-
-That's all.
-
--------------------------------------------------------------
-Fatal error C1204:Compiler limit: internal structure overflow
--------------------------------------------------------------
-
-If you get this error, than the generated file is too big. You will have to split
-it to few files. Well, not you but `Py++`_, you will only have to tell it to do
-that.
-
-If you are using ``module_builder_t.write_module`` method, consider to switch
-to ``module_builder_t.split_module``.
-
-If you are using ``split_module``, but still the generated code for some class
-could not be compiled, because of the error, you can ask `Py++`_ to split the
-code generated for class to be split to few cpp files.
-
-For more information, please read the documentation.
-
-------------------------------------------------------
-How to automatically export template functions\\class?
-------------------------------------------------------
-
-Lets say you have next C++ function:
-
-.. code-block:: C++
-
-  // file point.h
-  namespace geometry{
-      template< class T>
-      struct point_t{
-          T x, y;
-      };
-      template <class T>
-      double distance( const point_t<T>& point ){
-          return sqrt( point.x * point.x + point.y*point.y );
-      }
-  } //namespace geometry
-
-You should understand, that you can not export template itself, but only its
-instantiations. The solution is built using next facts:
-
-* ``sizeof( class name )`` causes a compiler to instantiate the class
-
-* free function invocation causes a compiler to instantiate the function
-
-Lets say that we need to export the class and the function template
-instantiations for ``int`` and ``custom_type`` types. There are few ways to do it.
-
-Simple and straightforward
---------------------------
-
-Open your favourite editor and create a header file with the content:
-
-.. code-block:: C++
-
-  #include "point.h"
-
-.. code-block:: C++
-
-  namespace  py_details{
-      inline void instantiate(){
-          using namespace geometry;
-          sizeof( point_t<int> );
-          sizeof( point_t<custom_type> );
-          distance( point_t<int>(0,0) );
-          distance( point_t<custom_type>(0,0) );
-      }
-  }
-
-Now, you add this file to the list of files you pass as input to
-``module_builder_t.__init__`` method and excludes the ``py_details`` namespace
-declarations from being exported:
-
-.. code-block:: Python
-
-  mb = module_builder_t( [..., just created file ], ... )
-  mb.namespace( 'py_details' ).exclude()
-
-"Dynamic" instantiation
------------------------
-
-Lets say you are less lucky than I, and you have to create ``X`` instantiations
-of the class\\function. Obviously, the previous approach will not work for you.
-The solution is to build your own code generator, which will generate code similar
-to the one, in the previous paragraph.
-
-.. code-block:: Python
-
-  from module_builder import module_builder_t, create_text_fc
-
-.. code-block:: Python
-
-  def generate_instantiations_string( ... ):
-      ...
-
-.. code-block:: Python
-
-  code = generate_instantiations_string( ... )
-
-.. code-block:: Python
-
-  mb = module_builder_t( [ ..., create_text_fc( code ) ], ... )
-  mb.namespace( 'py_details' ).exclude()
-
-
-`Py++`_ allows you to extract declarations from string, which contains
-valid C++ code. It creates temporal header file and compiles it. At the end of
-the compilation process it will remove it. You can read mode about ``create_text_fc``
-function `here`__.
-
-.. __ : ./../../pygccxml/design.html#parser-configuration-classes
-
-
-
-I understand that the provided solution is not perfect. I understand that something
-better and simpler should be done, but a priority of this is low. There are few
-tasks, that have much higher priority. Allen Bierbaum wants to fix the situation.
-He created a `wiki page`_, that discuss possible solutions. Your contribution is
-welcome too!
-
-.. _`wiki page` : https://realityforge.vrsource.org/view/PyppApi/TemplateSupport
-
----------------------------------------------------
-How to deal with template on return type functions?
----------------------------------------------------
-.. code-block:: C++
-
-  struct environment_t{
-      ...
-      template< class T>
-      T get_value(const std::string& name);
-      ...
-  };
-
-  //Somewhere in your code
-  environment_t env;
-  std::string path = env.get_value< std::string >( "PATH" );
-  int version = env.get_value< int >( "VERSION" );
-
-`GCC-XML`_ will see both instantiations, ``get_value<int>`` and ``get_value< std::string >``,
-and will provide information about them. The name of both member functions,
-reported by `GCC-XML`_ is "**get_value**".
-
-In this case, `Py++`_ generates a code, which contains few errors and if your are
-lucky, depends on the compiler you use, the generated code will not compile.
-Otherwise, you will discover the errors while testing the bindings.
-
-Generated code:
-
-.. code-block:: C++
-
-  bp::class_< environment_t >( "environment_t" )
-      ...
-      .def( "get_value"
-            , (int ( ::environment_t::* )( ::std::string const & ) )( &::environment_t::get_value ) )
-      .def( "get_value"
-            , (::std::string ( ::environment_t::* )( ::std::string const & ) )( &::environment_t::get_value ) );
-
-The correct code:
-
-.. code-block:: C++
-
-  bp::class_< environment_t >( "environment_t" )
-      .def( "get_value"
-            , (int ( ::environment_t::* )( ::std::string const & ) )( &::environment_t::get_value< int > ) )
-            //--------------------------------------------------------------------------^^^^^^^^^^^^^^^^
-      .def( "get_value"
-            , (::std::string ( ::environment_t::* )( ::std::string const & ) )( &::environment_t::get_value< std::string > ) );
-            //------------------------------------------------------------------------------------^^^^^^^^^^^^^^^^^^^^^^^^
-
-The perfect one:
-
-.. code-block:: C++
-
-  bp::class_< environment_t >( "environment_t" )
-      ...
-      .def( "get_value", &::environment_t::get_value< int > )
-      .def( "get_value", &::environment_t::get_value< std::string > );
-
-Solution
---------
-.. code-block:: Python
-
-  mb = module_builder_t( ..., optimize_queries=False, ... )
-  environment = mb.class_( "environment_t" )
-  for f in environment.member_functions( "get_value" ):
-      f.alias = f.name + "_" + f.return_type.decl_string #create new function alias
-      f.name = f.demangled_name
-  mb.run_query_optimizer()
-
-Before you read the rest of the answer, you should understand what is "name mangling"
-means. If you don't, consider reading about it on `Wikipedia`__.
-
-.. __ : http://en.wikipedia.org/wiki/Name_mangling
-
-
-The solution is pretty simple. `GCC-XML`_ reports mangled and demangled function
-names. The demangled function name contains "real" function name:
-``get_value< used type >``. You only have to instruct `Py++`_ to use it.
-
-`Py++`_ does not use by default demangled function name for mainly one reason.
-Demangled function name is a string that contains a lot of information. `Py++`_
-implements a parser, which extracts the only relevant one. The parser
-implementation is a little bit complex and was not heavily tested. By "heavily" I
-mean that I tested it on a lot of crazy use cases and on a real project, but
-there is always some new use case out there. I am almost sure it will work for
-you. The problem, we deal with, is rare, so by default "demangled_name"
-feature is turned off.
-
-By the way, almost the same problem exists for template classes. But, in the
-classes use case `Py++`_ uses demangled name by default.
-
-
--------------------------------------
-Py++ generated file name is too long!
--------------------------------------
-There are use cases, when `Py++`_ generated file name is too long. In some cases
-the code generation process even fails because of this. What can you do in order
-to eliminate the problem?
-
-First of all the problem arises when you expose template instantiated classes
-and you did not set the class alias.
-
-Let me explain:
-
-.. code-block:: C++
-
-  template < class T>
-  struct holder{ ... };
-
-
-Lets say that you want to export ``holder< int >`` class. Class name in `Python`_
-has few `constraints`_. `Py++`_ is aware of the `constraints`_ and if you didn't
-set an alias to the class, `Py++`_ will do it for you. In this case,
-"holder_less_int_grate\_" is the generated alias. Obviously it is much longer
-and not readable.
-
-.. _`constraints` : http://www.python.org/doc/current/ref/identifiers.html
-
-There are few pretty good reasons for this behavior:
-
-* when you just start to work on `Python`_ bindings concentrate your attention
-  on really important things
-
-* if you forgot to set the class alias your users still can use the class
-  functionality, however the class name will be a little bit ugly.
-
-
-In this case the generate alias for ``holder`` instantiation is relatively short.
-Imagine how long it could be for ``std::map`` instantiation.
-
-`Py++`_ uses class alias for the file name. So if you want to force `Py++`_ to
-generate files with short name, you have to set class alias:
-
-.. code-block:: Python
-
-  from pyplusplus import module_builder
-
-  mb = module_builder_t( ... )
-  holder = mb.class_( 'holder< int >' )
-  holder.alias = 'IntHolder'
-  #next line has same effect as the previous one:
-  holder.rename( 'IntHolder' )
-
-The nice thing about this approach is that now `Python`_ users have "normal"
-class name and you have short file name.
-
--------------------
-Full\relative paths
--------------------
-
-Consider next file layout:
-::
-
-  boost/
-    date_time/
-      ptime.hpp
-      time_duration.hpp
-      date_time.hpp //main header, which include all other header files
-
-Py++ currently does not handle relative paths as input very well, so it is 
-recommended that you use ``os.path.abspath()`` to transform the header file to 
-be processed into an absolute path:
-  
-.. code-block:: Python
-    
-   #Next code will expose nothing
-   mb = module_builder( [ 'date_time/date_time.hpp' ], ... ) 
-   mb.split_module( ... )
-
-   #while this one will work as expected
-   import os
-   mb = module_builder( [ os.path.abspath('date_time/date_time.hpp') ], ... ) 
-   mb.split_module( ... )
-
-
-.. _`Py++` : ./../pyplusplus.html
-.. _`Boost.Python`: http://www.boost.org/libs/python/doc/index.html
-.. _`Python`: http://www.python.org
-.. _`GCC-XML`: http://www.gccxml.org


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.