Documentation for shiboken module.

Reviewer: Marcelo Lira <marcelo.lira@openbossa.org>
          Luciano Wolf <luciano.wolf@openbossa.org>

4 files changed, 150 insertions, 6 deletions

diff --git a/doc/_themes/pysidedocs/static/pysidedocs.css b/doc/_themes/pysidedocs/static/pysidedocs.css
index fd81f43..708ddf7 100644
--- a/doc/_themes/pysidedocs/static/pysidedocs.css
+++ b/doc/_themes/pysidedocs/static/pysidedocs.css
@@ -10,7 +10,6 @@ html {
 body {
     margin: 0;
     padding: 0;
-    text-align: center;
     background-color: #EBEBEB;
     height: 100%;
     color: #333;
@@ -93,7 +92,6 @@ h1 {
     padding-bottom: 15px;
     padding-top: 15px;
     border-bottom: 1px solid #c2c2c2;
-    text-transform:uppercase;
     margin-right: -100px;
     position: relative;
     left: -50px;
@@ -137,11 +135,15 @@ pre * {
     font: 100% monospace;
 }
 
+.pre {
+    font: 100% monospace;
+}
+
 .headerlink {
     font-size: 100%;
     color: inherit;
     float: right;
-    visibility: Hidden;
+    visibility: Hidden
 }
 
 h1 .headerlink {
@@ -192,6 +194,11 @@ div.warning {
     border: 1px solid #f66;
 }
 
+div.seealso {
+    background-color: #ffffcc;
+    border: 1px solid #ffff66;
+}
+
 div.note {
     border: 1px solid #e3e3e3;
 }
@@ -407,3 +414,62 @@ img {
 table.footnote {
     margin: 0px;
 }
+
+#synopsis table, table.field-list {
+    margin: 0px;
+}
+
+tt.descname {
+    font-size: 120%;
+    font-weight: bold;
+}
+
+#functions ul, #virtual-functions ul, #slots ul, #signals ul, #static-functions ul {
+    list-style: none;
+    margin: 0px;
+    padding: 10px;
+    border: 1px solid #ddd;
+    background-color: #f4f4f4;
+    -moz-border-radius:10px;
+    -webkit-border-radius:10px;
+    -khtml-border-radius:10px;
+}
+
+#synopsis span.pre {
+    color: #009491;
+    font-weight: bolder;
+}
+
+#detailed-description .class dt, #detailed-description .method dt, #detailed-description .attribute dt, #detailed-description .function dt  {
+    margin: 0px;
+    padding: 10px;
+    border: 1px solid #ddd;
+    background-color: #f4f4f4;
+    -moz-border-radius:10px;
+    -webkit-border-radius:10px;
+    -khtml-border-radius:10px;
+}
+
+.pysidetoc ul {
+    list-style: none;
+    padding: 0px;
+    margin: 0px;
+}
+
+.pysidetoc em {
+    font-style: normal;
+}
+
+.pysidetoc strong {
+    display: block;
+    padding: 5px;
+    border: 1px solid #ddd;
+    background-color: #f4f4f4;
+    -moz-border-radius:6px;
+    -webkit-border-radius:6px;
+    -khtml-border-radius:6px;
+}
+
+.hide {
+    display: none;
+}
diff --git a/doc/conf.py.in b/doc/conf.py.in
index e83cc32..b8575b9 100644
--- a/doc/conf.py.in
+++ b/doc/conf.py.in
@@ -143,7 +143,7 @@ html_use_smartypants = True
 html_additional_pages = { 'index' : 'index.html'}
 
 # If false, no module index is generated.
-#html_use_modindex = True
+html_use_modindex = False
 
 # If false, no index is generated.
 html_use_index = False
@@ -164,5 +164,3 @@ html_add_permalinks = True
 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = ''
 
-# Output file base name for HTML help builder.
-#htmlhelp_basename = 'PyQtBdoc'
diff --git a/doc/contents.rst b/doc/contents.rst
index a972169..d7482c6 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -11,3 +11,4 @@ Table of contents
     sequenceprotocol.rst
     ownership.rst
     wordsofadvice.rst
+    shibokenmodule.rst
\ No newline at end of file
diff --git a/doc/shibokenmodule.rst b/doc/shibokenmodule.rst
new file mode 100644
index 0000000..150998c
--- /dev/null
+++ b/doc/shibokenmodule.rst
@@ -0,0 +1,79 @@
+.. module:: shiboken
+
+.. |maya| unicode:: Maya U+2122
+
+Shiboken module
+***************
+
+Functions
+^^^^^^^^^
+
+.. container:: function_list
+
+    *    def :meth:`isValid<shiboken.isValid>` (obj)
+    *    def :meth:`wrapInstance<shiboken.wrapInstance>` (address, type)
+    *    def :meth:`getCppPointer<shiboken.getCppPointer>` (obj)
+    *    def :meth:`delete<shiboken.delete>` (obj)
+    *    def :meth:`isOwnedByPython<shiboken.isOwnedByPython>` (obj)
+    *    def :meth:`wasCreatedByPython<shiboken.wasCreatedByPython>` (obj)
+    *    def :meth:`dump<shiboken.dump>` (obj)
+
+Detailed description
+^^^^^^^^^^^^^^^^^^^^
+
+This Python module can be used to access internal information related to our
+binding technology. Access to this internal information is required to e.g.:
+integrate PySide with Qt based programs that offer Python scripting like |maya|
+or just for debug purposes.
+
+Some function description refer to "Shiboken based objects", wich means
+Python objects instances of any Python Type created using Shiboken.
+
+
+.. function:: isValid(obj)
+
+    Given a Python object, returns True if the object methods can be called
+    without an exception being thrown. A Python wrapper becomes invalid when
+    the underlying C++ object is destroyed or unreachable.
+
+.. function:: wrapInstance(address, type)
+
+    Creates a Python wrapper for a C++ object instantiated at a given memory
+    address - the returned object type will be the same given by the user.
+
+    The type must be a Shiboken type, the C++ object will not be
+    destroyed when the returned Python object reach zero references.
+
+    If the address is invalid or doesn't point to a C++ object of given type
+    the behavior is undefined.
+
+.. function:: getCppPointer(obj)
+
+    Returns a tuple of longs that contain the memory addresses of the
+    C++ instances wrapped by the given object.
+
+.. function:: delete(obj)
+
+    Deletes the C++ object wrapped by the given Python object.
+
+.. function:: isOwnedByPython(obj)
+
+    Given a Python object, returns True if Python is responsible for deleting
+    the underlying C++ object, False otherwise.
+
+    If the object was not a Shiboken based object, a TypeError is
+    thrown.
+
+.. function:: wasCreatedByPython(obj)
+
+    Returns true if the given Python object was created by Python.
+
+.. function:: dump(obj)
+
+    Returns a string with implementation-defined information about the
+    object.
+    This method should be used **only** for debug purposes by developers
+    creating their own bindings as no guarantee is provided that
+    the string format will be the same across different versions.
+
+    If the object is not a Shiboken based object, a TypeError is thrown.