Add contribution section

Author: mfeurer

openml/apiconnector.py

@@ -877,6 +877,30 @@ def _create_task_cache_dir(self, task_id):
 
     def _perform_api_call(self, call, data=None, add_authentication=True,
                           **kwargs):
+        """Perform an API call at the OpenML server.
+
+        This method must be used by all other methods using the REST API.
+
+        Parameters
+        ----------
+        call : str
+            The API call. For example openml.task.search
+        data : dict (default=None)
+            Dictionary containing data which will be sent to the OpenML
+            server via a POST request.
+        add_authentication : bool (default=True)
+            DO NOT CHANGE THIS. The only method which should set this
+            argument to False is `authenticate`.
+        **kwargs
+            Further arguments which are appended as GET arguments.
+
+        Returns
+        -------
+        return_code : int
+            HTTP return code
+        return_value : str
+            Return value of the OpenML server
+        """
         # TODO: do input validation!
         url = self.config.get("FAKE_SECTION", "server") + "/api/?f="
         url += "" + call

source/index.rst

@@ -54,99 +54,23 @@ From within the directory of the cloned package, execute
 
     python setup.py test
 
------------
-Basic Usage
------------
+Usage
+~~~~~
 
-Connecting to the OpenML server
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The OpenML server can only be accessed by users who have signed up to the OpenML
-platform. If you don't have an account yet,
-`sign up now <http://openml.org/register>`_.
-
-.. code:: python
-
-    >>> from openml.apiconnector import APIConnector
-
-    >>> username = "Your OpenML username"
-    >>> password = "Your OpenML password"
-    >>> connector = APIConnector(username=username, password=password)
-
-The :class:`~openml.apiconnector.APIConnector` will create a cache directory
-and authenticate you at the OpenML server. By this you obtain a session key,
-which is valid for one hour.
-
-You can also configure the OpenML package, e.g. change the cache directory.
-Information about the configuration is in the
-`OpenML client API description <https://github
-.com/openml/OpenML/wiki/Client-API>`_.
-
-Working with datasets
-~~~~~~~~~~~~~~~~~~~~~
-
-.. code:: python
-
-    >>> dataset_id = 31
-    >>> dataset = connector.download_dataset(1)
-
-Attributes of the dataset are stored as member variables:
-
-.. code:: python
-
-    >>> dataset.name
-    u'credit-g'
-    >>> dataset.default_target_attribute
-    u'class'
-
-Data can be loaded in the following ways:
-
-.. code:: python
-
-    >>> pd, categorical = dataset.get_pandas()
-
-returns the dataset as a pandas.DataFrame and a list of booleans,
-indicating which attributes are categorical. Categorical attributes are
-already encoded as integers.
-
-.. code:: python
-
-    >>> X, y, categorical = dataset.get_pandas()
-
-returns the dataset split into X and y, as well as a list indicating which
-attributes are categorical. In case you are working with `scikit-learn
-<http://scikit-learn>`_, you can use this data right away:
-
-.. code:: python
-
-    >>> from sklearn import preprocessing, ensemble
-    >>> enc = preprocessing.OneHotEncoder(categorical_features=categorical)
-    OneHotEncoder(categorical_features=[True, False, True, True, False, True,
-        True, False, True, True, False, True, False, True, True, False, True,
-        False, True, True], dtype=<type 'float'>, n_values='auto',
-        sparse=True)
-    >>> X = enc.transform(X).todense()
-    >>> clf = ensemble.RandomForestClassifier()
-    >>> clf.fit(X, y)
-    RandomForestClassifier(bootstrap=True, compute_importances=None,
-            criterion='gini', max_depth=None, max_features='auto',
-            max_leaf_nodes=None, min_density=None, min_samples_leaf=1,
-            min_samples_split=2, n_estimators=10, n_jobs=1,
-            oob_score=False, random_state=None, verbose=0)
-
-Working with tasks
-~~~~~~~~~~~~~~~~~~
-
-Using the cache
-~~~~~~~~~~~~~~~
+* :ref:`usage`
+* :ref:`api`
 
-Large scale experiments
-~~~~~~~~~~~~~~~~~~~~~~~
+Contributing
+~~~~~~~~~~~~
 
-Indices and tables
-==================
+Contribution to the OpenML package is highly appreciated. Currently,
+there is a lot of work left on implementing API calls,
+testing them and providing examples to allow new users to easily use the
+OpenML package. See the :ref:`progress` page for open tasks.
 
-* :ref:`api`
-* :ref:`search`
+Please contact `Matthias <http://aad.informatik.uni-freiburg.de/people/feurer/index.html>`_
+prior to start working on an issue or missing feature to avoid duplicate work
+. Please check the current implementations of the API calls and the method
 
+.. automethod:: openml.apiconnector.APIConnector._perform_api_call