Add usage snippet to docs page (#434)

* ADD introductory snippet to front page of the docs

* FIX issues with rst formatting

Author: mfeurer

doc/index.rst

@@ -3,11 +3,39 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to OpenML's documentation!
-==================================
-
-The OpenML module is still under development. You can watch its progress
-:ref:`here <progress>`.
+======
+OpenML
+======
+
+Welcome to the documentation of the OpenML Python API, a connector to the
+collaborative machine learning platform `OpenML.org <https://www.openml.org>`_.
+The OpenML Python package allows to use datasets and tasks from OpenML together
+with scikit-learn and share the results online.
+
+-------
+Example
+-------
+
+.. code:: python
+
+    # Define a scikit-learn pipeline
+    clf = sklearn.pipeline.Pipeline(
+        steps=[
+            ('imputer', sklearn.preprocessing.Imputer()),
+            ('estimator', sklearn.tree.DecisionTreeClassifier())
+        ]
+    )
+    # Download the OpenML task for the german credit card dataset with 10-fold
+    # cross-validation.
+    task = openml.tasks.get_task(31)
+    # Set the OpenML API Key which is required to upload the runs.
+    # You can get your own API by signing up to OpenML.org.
+    openml.config.apikey = 'ABC'
+    # Run the scikit-learn model on the task (requires an API key).
+    run = openml.runs.run_model_on_task(task, clf)
+    # Publish the experiment on OpenML (optional, requires an API key).
+    run.publish()
+    print('URL for run: %s/run/%d' % (openml.config.server, run.run_id))
 
 
 ------------

openml/__init__.py

@@ -28,6 +28,7 @@
 from .runs import OpenMLRun
 from .tasks import OpenMLTask, OpenMLSplit
 from .flows import OpenMLFlow
+from .evaluations import OpenMLEvaluation
 
 from .__version__ import __version__
 

openml/evaluations/evaluation.py

@@ -5,24 +5,29 @@ class OpenMLEvaluation(object):
     according to the evaluation/list function
 
     Parameters
-       ----------
-        run_id : int
-        task_id : int
-        setup_id : int
-        flow_id : int
-        flow_name : str
-        data_id : int
-        data_name : str
-            the name of the dataset
-        function : str
-            the evaluation function of this item (e.g., accuracy)
-        upload_time : str
-            the time of evaluation
-        value : float
-            the value of this evaluation
-        array_data : str
-            list of information per class (e.g., in case of precision, auroc,
-            recall)
+    ----------
+    run_id : int
+    
+    task_id : int
+    
+    setup_id : int
+    
+    flow_id : int
+    
+    flow_name : str
+    
+    data_id : int
+    
+    data_name : str
+        the name of the dataset
+    function : str
+        the evaluation function of this item (e.g., accuracy)
+    upload_time : str
+        the time of evaluation
+    value : float
+        the value of this evaluation
+    array_data : str
+        list of information per class (e.g., in case of precision, auroc, recall)
     '''
     def __init__(self, run_id, task_id, setup_id, flow_id, flow_name,
                  data_id, data_name, function, upload_time, value,