diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2a215a985..2bd3bf2a1 100644 --- a/CONTRIBUTING.md +++ b/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: diff --git a/doc/conf.py b/doc/conf.py index a9f244d6c..88c146fdb 100644 --- a/doc/conf.py +++ b/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) diff --git a/doc/contributing.rst b/doc/contributing.rst new file mode 100644 index 000000000..b8ddc9c90 --- /dev/null +++ b/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 `_ and `scipy `_. +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 `_. +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 `_. +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 `_ 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 `_ if you use it in a scientific + publication. +* Visit one of our `hackathons `_. +* Check out how to `contribute to the main OpenML project `_. + +Contributing code +~~~~~~~~~~~~~~~~~ + +Our guidelines on code contribution can be found in `this file `_. + +.. _installation: + +Installation +============ + +Installation from github +~~~~~~~~~~~~~~~~~~~~~~~~ + +The package source code is available from +`github `_ 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! + diff --git a/doc/developing.rst b/doc/developing.rst deleted file mode 100644 index 9240a602b..000000000 --- a/doc/developing.rst +++ /dev/null @@ -1,19 +0,0 @@ -:orphan: - -.. _developing: - - -Updating the API key for travis-ci -********************************** - -OpenML uses an API key to authenticate a user. The API repository also needs an -API key in order to run tests against the OpenML server. The API key used for -the tests are linked to a special test user. Since API keys are private, we have -to use private environment variables for travis-ci. The API key is stored in an -environment variable `OPENMLAPIKEY` in travis-ci. To encrypt an API key for use -on travis-ci use the following command to create a private string to put into -the `.travis.yml` file - -.. code:: bash - - travis encrypt OPENMLAPIKEY=secretvalue --add \ No newline at end of file diff --git a/doc/index.rst b/doc/index.rst index 3990fc09a..1e2e5c5c1 100644 --- a/doc/index.rst +++ b/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 `_. +---------------------------- +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 `_ +* `OpenML client APIs `_ +* `OpenML developer guide `_ +* `Contact information `_ +* `Citation request `_ +* `OpenML blog `_ +* `OpenML twitter account `_ -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 `_ -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.