diff --git a/doc/conf.py b/doc/conf.py index 1f016561b..a10187486 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -138,6 +138,7 @@ ("User Guide", "usage"), ("API", "api"), ("Examples", "examples/index"), + ("Extensions", "extensions"), ("Contributing", "contributing"), ("Changelog", "progress"), ], diff --git a/doc/contributing.rst b/doc/contributing.rst index 927c21034..e87a02dfb 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -29,70 +29,4 @@ In particular, a few ways to contribute to openml-python are: .. _extensions: -Connecting new machine learning libraries -========================================= -Content of the Library -~~~~~~~~~~~~~~~~~~~~~~ - -To leverage support from the community and to tap in the potential of OpenML, interfacing -with popular machine learning libraries is essential. However, the OpenML-Python team does -not have the capacity to develop and maintain such interfaces on its own. For this, we -have built an extension interface to allows others to contribute back. Building a suitable -extension for therefore requires an understanding of the current OpenML-Python support. - -The :ref:`sphx_glr_examples_20_basic_simple_flows_and_runs_tutorial.py` tutorial -shows how scikit-learn currently works with OpenML-Python as an extension. The *sklearn* -extension packaged with the `openml-python `_ -repository can be used as a template/benchmark to build the new extension. - - -API -+++ -* The extension scripts must import the `openml` package and be able to interface with - any function from the OpenML-Python :ref:`api`. -* The extension has to be defined as a Python class and must inherit from - :class:`openml.extensions.Extension`. -* This class needs to have all the functions from `class Extension` overloaded as required. -* The redefined functions should have adequate and appropriate docstrings. The - `Sklearn Extension API :class:`openml.extensions.sklearn.SklearnExtension.html` - is a good benchmark to follow. - - -Interfacing with OpenML-Python -++++++++++++++++++++++++++++++ -Once the new extension class has been defined, the openml-python module to -:meth:`openml.extensions.register_extension` must be called to allow OpenML-Python to -interface the new extension. - - -Hosting the library -~~~~~~~~~~~~~~~~~~~ - -Each extension created should be a stand-alone repository, compatible with the -`OpenML-Python repository `_. -The extension repository should work off-the-shelf with *OpenML-Python* installed. - -Create a `public Github repo `_ -with the following directory structure: - -:: - -| [repo name] -| |-- [extension name] -| | |-- __init__.py -| | |-- extension.py -| | |-- config.py (optionally) - - - -Recommended -~~~~~~~~~~~ -* Test cases to keep the extension up to date with the `openml-python` upstream changes. -* Documentation of the extension API, especially if any new functionality added to OpenML-Python's - extension design. -* Examples to show how the new extension interfaces and works with OpenML-Python. -* Create a PR to add the new extension to the OpenML-Python API documentation. - - -Happy contributing! diff --git a/doc/extensions.rst b/doc/extensions.rst new file mode 100644 index 000000000..ea12dda6a --- /dev/null +++ b/doc/extensions.rst @@ -0,0 +1,87 @@ +:orphan: + +.. _extensions: + +========== +Extensions +========== + +OpenML-Python provides an extension interface to connect other machine learning libraries than +scikit-learn to OpenML. Please check the :ref:`api_extensions` and use the +scikit-learn extension in :class:`openml.extensions.sklearn.SklearnExtension` as a starting point. + +List of extensions +================== + +Here is a list of currently maintained OpenML extensions: + +* :class:`openml.extensions.sklearn.SklearnExtension` +* `openml-keras `_ +* `openml-pytorch `_ +* `openml-tensorflow (for tensorflow 2+) `_ + + +Connecting new machine learning libraries +========================================= + +Content of the Library +~~~~~~~~~~~~~~~~~~~~~~ + +To leverage support from the community and to tap in the potential of OpenML, interfacing +with popular machine learning libraries is essential. However, the OpenML-Python team does +not have the capacity to develop and maintain such interfaces on its own. For this, we +have built an extension interface to allows others to contribute back. Building a suitable +extension for therefore requires an understanding of the current OpenML-Python support. + +The :ref:`sphx_glr_examples_20_basic_simple_flows_and_runs_tutorial.py` tutorial +shows how scikit-learn currently works with OpenML-Python as an extension. The *sklearn* +extension packaged with the `openml-python `_ +repository can be used as a template/benchmark to build the new extension. + + +API ++++ +* The extension scripts must import the `openml` package and be able to interface with + any function from the OpenML-Python :ref:`api`. +* The extension has to be defined as a Python class and must inherit from + :class:`openml.extensions.Extension`. +* This class needs to have all the functions from `class Extension` overloaded as required. +* The redefined functions should have adequate and appropriate docstrings. The + `Sklearn Extension API :class:`openml.extensions.sklearn.SklearnExtension.html` + is a good benchmark to follow. + + +Interfacing with OpenML-Python +++++++++++++++++++++++++++++++ +Once the new extension class has been defined, the openml-python module to +:meth:`openml.extensions.register_extension` must be called to allow OpenML-Python to +interface the new extension. + + +Hosting the library +~~~~~~~~~~~~~~~~~~~ + +Each extension created should be a stand-alone repository, compatible with the +`OpenML-Python repository `_. +The extension repository should work off-the-shelf with *OpenML-Python* installed. + +Create a `public Github repo `_ +with the following directory structure: + +:: + +| [repo name] +| |-- [extension name] +| | |-- __init__.py +| | |-- extension.py +| | |-- config.py (optionally) + +Recommended +~~~~~~~~~~~ +* Test cases to keep the extension up to date with the `openml-python` upstream changes. +* Documentation of the extension API, especially if any new functionality added to OpenML-Python's + extension design. +* Examples to show how the new extension interfaces and works with OpenML-Python. +* Create a PR to add the new extension to the OpenML-Python API documentation. + +Happy contributing! diff --git a/doc/index.rst b/doc/index.rst index c4164dc82..b0140c1d0 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -61,6 +61,7 @@ Content * :ref:`usage` * :ref:`api` * :ref:`sphx_glr_examples` +* :ref:`extensions` * :ref:`contributing` * :ref:`progress` diff --git a/doc/usage.rst b/doc/usage.rst index 7bf247f4d..0d51f232a 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -155,19 +155,7 @@ obtained on. Learn how to share your datasets in the following tutorial: Extending OpenML-Python *********************** -OpenML-Python provides an extension interface to connect other machine learning libraries than -scikit-learn to OpenML. Please check the :ref:`api_extensions` and use the -scikit-learn extension in :class:`openml.extensions.sklearn.SklearnExtension` as a starting point. - -Runtime measurement is incorporated in the OpenML sklearn-extension. Example usage and potential -usage for Hyperparameter Optimisation can be found in the example tutorial: - -* :ref:`sphx_glr_examples_30_extended_fetch_runtimes_tutorial.py` - - -Here is a list of currently maintained OpenML extensions: - -* `openml-keras `_ -* `openml-pytorch `_ -* `openml-tensorflow(for tensorflow 2+) `_ +OpenML-Python provides an extension interface to connect machine learning libraries directly to +the API and ships a ``scikit-learn`` extension. You can find more information in the Section +:ref:`extensions`'