Add some introduction text to the Python documentation.

tools/python/doc/source/index.rst

@@ -3,10 +3,56 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Linphone's documentation!
-====================================
+Linphone for Python documentation
+=================================
 
-Contents:
+Getting started
+---------------
+
+Installing the Python module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can install prebuilt packages of Linphone for Python. You will find the
+releases at https://pypi.python.org/pypi/linphone. This includes only packages
+for the Windows platform right now. The easiest way to install is to use pip,
+eg.:
+
+.. code-block:: none
+
+   > pip install linphone --pre
+
+You can also find nightly-built packages for Windows, Mac OS X and Linux at
+https://www.linphone.org/snapshots/linphone-python/.
+
+Otherwise you can compile the Python module. To do so get the build system code
+using the command:
+
+.. code-block:: none
+
+   > git clone git://git.linphone.org/linphone-cmake-builder.git
+
+Then follow the instructions in the *README.python* file.
+
+Running some code
+^^^^^^^^^^^^^^^^^
+
+Here is a sample source code using PyQt4 that enables you to register on a SIP
+server in just a few lines of code. This is a very basic example, but it shows
+how to create a linphone.Core object that is the main object of Linphone. From
+there, you can use the API reference below to use more advanced feature and
+perform some SIP calls, use text messaging and more...
+
+.. literalinclude:: pyqt_linphone_example.py
+
+In the Linphone Python module package you installed previously you will also
+find some unit tests that you can run. These unit tests will be located in the
+*site-packages/linphone/unittests/* directory of Python installation where you
+installed the Linphone Python module package. To run these unit tests, follow
+the instructions contained in the README.txt file of this *unittests/*
+directory.
+
+API reference
+-------------
 
 .. toctree::
    :maxdepth: 2
@@ -19,7 +65,7 @@ Contents:
 
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`search`

tools/python/doc/source/pyqt_linphone_example.py

@@ -0,0 +1,47 @@
+import linphone
+import logging
+import sys
+from PyQt4.QtCore import QTimer
+from PyQt4.QtGui import QApplication
+
+
+def main():
+    logging.basicConfig(level=logging.INFO)
+
+    app = QApplication(sys.argv)
+
+    def log_handler(level, msg):
+        method = getattr(logging, level)
+        method(msg)
+
+    def global_state_changed(*args, **kwargs):
+        logging.warning("global_state_changed: %r %r" % (args, kwargs))
+
+    def registration_state_changed(core, call, state, message):
+        logging.warning("registration_state_changed: " + str(state) + ", " + message)
+
+    callbacks = {
+        'global_state_changed': global_state_changed,
+        'registration_state_changed': registration_state_changed,
+    }
+
+    linphone.set_log_handler(log_handler)
+    core = linphone.Core.new(callbacks, None, None)
+    proxy_cfg = core.create_proxy_config()
+    proxy_cfg.identity = "sip:toto@test.linphone.org"
+    proxy_cfg.server_addr = "sip:test.linphone.org"
+    proxy_cfg.register_enabled = True
+    core.add_proxy_config(proxy_cfg)
+
+    iterate_timer = QTimer()
+    iterate_timer.timeout.connect(core.iterate)
+    stop_timer = QTimer()
+    stop_timer.timeout.connect(app.quit)
+    iterate_timer.start(20)
+    stop_timer.start(5000)
+
+    exitcode = app.exec_()
+    sys.exit(exitcode)
+
+
+main()