Updated installation instructions

CONTRIBUTING.md

@@ -92,6 +92,8 @@ following rules before you submit a pull request:
    For the Bug-fixes case, at the time of the PR, this tests should fail for
    the code base in develop and pass for the PR code.
 
+ - Add your changes to the changelog in the file doc/progress.rst.
+
 
 You can also check for common programming errors with the following
 tools:

doc/conf.py

@@ -133,7 +133,8 @@
         ('Start', 'index'),
         ('API', 'api'),
         ('User Guide', 'usage'),
-        ('Progress', 'progress'),
+        ('Changelog', 'progress'),
+        ('Contributing', 'contributing')
     ],
 
     # Render the next and previous page links in navbar. (Default: true)

doc/contributing.rst

@@ -0,0 +1,115 @@
+:orphan:
+
+.. _contributing:
+
+
+============
+Contributing
+============
+
+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:`issues` section for open tasks.
+
+Please mark yourself as contributor in a github issue if you start working on
+something to avoid duplicate work. If you're part of the OpenML organization
+you can use github's assign feature, otherwise you can just leave a comment.
+
+.. _scope:
+
+Scope of the package
+====================
+
+The scope of the OpenML python package is to provide a python interface to
+the OpenML platform which integrates well with pythons scientific stack, most
+notably `numpy <http://www.numpy.org/>`_ and `scipy <https://www.scipy.org/>`_.
+To reduce opportunity costs and demonstrate the usage of the package, it also
+implements an interface to the most popular machine learning package written
+in python, `scikit-learn <http://scikit-learn.org/stable/index.html>`_.
+Thereby it will automatically be compatible with many machine learning
+libraries written in Python.
+
+We aim to keep the package as leight-weight as possible and we will try to
+keep the number of potential installation dependencies as low as possible.
+Therefore, the connection to other machine learning libraries such as
+*pytorch*, *keras* or *tensorflow* should not be done directly inside this
+package, but in a separate package using the OpenML python connector.
+
+.. _issues:
+
+Open issues and potential todos
+===============================
+
+We collect open issues and feature requests in an `issue tracker on github <https://github.com/openml/openml-python/issues>`_.
+The issue tracker contains issues marked as *Good first issue*, which shows
+issues which are good for beginers. We also maintain a somewhat up-to-date
+`roadmap <https://github.com/openml/openml-python/issues/410>`_ which
+contains longer-term goals.
+
+.. _how_to_contribute:
+
+How to contribute
+=================
+
+There are many ways to contribute to the development of the OpenML python
+connector and OpenML in general. We welcome all kinds of contributions,
+especially:
+
+* Source code which fixes an issue, improves usability or implements a new
+  feature.
+* Improvements to the documentation, which can be found in the ``doc``
+  directory.
+* New examples - current examples can be found in the ``examples`` directory.
+* Bug reports - if something doesn't work for you or is cumbersome, please
+  open a new issue to let us know about the problem.
+* Use the package and spread the word.
+* `Cite OpenML <https://www.openml.org/cite>`_ if you use it in a scientific
+  publication.
+* Visit one of our `hackathons <https://hackathon.openml.org/>`_.
+* Check out how to `contribute to the main OpenML project <https://github.com/openml/OpenML/blob/master/CONTRIBUTING.md>`_.
+
+Contributing code
+~~~~~~~~~~~~~~~~~
+
+Our guidelines on code contribution can be found in `this file <https://github.com/openml/openml-python/blob/master/CONTRIBUTING.md>`_.
+
+.. _installation:
+
+Installation
+============
+
+Installation from github
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The package source code is available from
+`github <https://github.com/openml/openml-python>`_ and can be obtained with:
+
+.. code:: bash
+
+    git clone https://github.com/openml/openml-python.git
+
+
+Once you cloned the package, change into the new directory ``python`` and
+execute
+
+.. code:: bash
+
+    python setup.py install
+
+Testing
+~~~~~~~
+
+From within the directory of the cloned package, execute:
+
+.. code:: bash
+
+    nosetests tests/
+
+.. _extending:
+
+Connecting new machine learning libraries
+=========================================
+
+Coming soon - please stay tuned!
+

doc/index.rst

@@ -18,74 +18,66 @@ Example
 
 .. code:: python
 
-    # Define a scikit-learn pipeline
-    clf = sklearn.pipeline.Pipeline(
+   import openml
+   from sklearn import preprocessing, tree, pipeline
+
+    # Set the OpenML API Key which is required to upload your runs.
+    # You can get your own API by signing up to OpenML.org.
+    openml.config.apikey = 'ABC'
+
+    # Define a scikit-learn classifier or pipeline
+    clf = pipeline.Pipeline(
         steps=[
-            ('imputer', sklearn.preprocessing.Imputer()),
-            ('estimator', sklearn.tree.DecisionTreeClassifier())
+            ('imputer', preprocessing.Imputer()),
+            ('estimator', 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))
-
-
-------------
-Introduction
-------------
+    print('View the run online: %s/run/%d' % (openml.config.server, run.run_id))
 
+----------------------------
 How to get OpenML for python
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Currently, the OpenML package for python is only available from
-`github <https://github.com/openml/openml-python>`_.
+----------------------------
+You can install the OpenML package via `pip`:
 
 .. code:: bash
 
-    git clone https://github.com/openml/openml-python.git
+    pip install openml
 
-Installation
-~~~~~~~~~~~~
-
-Once you cloned the package, change into the new directory ``python`` and
-execute
-
-.. code:: bash
-
-    python setup.py install
-
-Testing
-~~~~~~~
-
-From within the directory of the cloned package, execute
-
-.. code:: bash
-
-    python setup.py test
+For more advanced installation information, please see the
+:ref:`installation` section.
 
+-----
 Usage
-~~~~~
+-----
 
 * :ref:`usage`
 * :ref:`api`
-* :ref:`developing`
+* :ref:`contributing`
 
-Contributing
-~~~~~~~~~~~~
+-------------------
+Further information
+-------------------
+
+* `OpenML documentation <https://docs.openml.org/>`_
+* `OpenML client APIs <https://docs.openml.org/APIs/>`_
+* `OpenML developer guide <https://docs.openml.org/developers/>`_
+* `Contact information <https://www.openml.org/contact>`_
+* `Citation request <https://www.openml.org/cite>`_
+* `OpenML blog <https://medium.com/open-machine-learning>`_
+* `OpenML twitter account <https://twitter.com/open_ml>`_
 
-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.
+------------
+Contributing
+------------
 
-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
+Contribution to the OpenML package is highly appreciated. The OpenML package
+currently has a 1/4 position for the development and all help possible is
+needed to extend and maintain the package, create new examples and improve
+the usability. Please see the :ref:`contributing` page for more information.