DOC document eli5.explain_weights and eli5.explain_prediction

docs/source/autodocs/base.rst

@@ -0,0 +1,5 @@
+eli5.base
+===============
+
+.. automodule:: eli5.base
+    :members:

docs/source/autodocs/eli5.rst

@@ -0,0 +1,12 @@
+ELI5 top-level API
+==================
+
+.. module:: eli5
+
+The following functions are exposed to a top level, e.g.
+``eli5.explain_weights``.
+
+.. autofunction:: eli5.explain_weights
+
+.. autofunction:: eli5.explain_prediction
+

docs/source/autodocs/formatters.rst

@@ -1,3 +1,5 @@
+.. module:: eli5.formatters
+
 eli5.formatters
 ===============
 

docs/source/autodocs/index.rst

@@ -1,11 +1,13 @@
-Autogenerated API docs
-======================
+API
+===
 
 .. toctree::
    :maxdepth: 2
 
+   ./eli5
    ./formatters
    ./lightning
    ./lime
    ./sklearn
    ./sklearn_crfsuite
+   ./base

docs/source/conf.py

@@ -56,6 +56,7 @@ def __getattr__(cls, name):
     'sphinx.ext.autodoc',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -150,6 +151,11 @@ def __getattr__(cls, name):
 html_theme = "sphinx_rtd_theme"
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
+napoleon_google_docstring = False
+napoleon_use_param = False
+napoleon_use_rtype = False
+
+add_module_names = False
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/source/overview.rst

@@ -56,8 +56,8 @@ There are two main ways to look at a classification or a regression model:
 2. inspect an individual prediction of a model, try to figure out why
    the model makes the decision it makes.
 
-For (1) ELI5 provides ``eli5.explain_weights`` function; for (2) it provides
-``eli5.explain_prediction`` function.
+For (1) ELI5 provides :func:`eli5.explain_weights` function; for (2)
+it provides :func:`eli5.explain_prediction` function.
 
 If the ML library you're working with is supported then you usually
 can enter the following in IPython Notebook::
@@ -72,13 +72,16 @@ and get an explanation like this:
 Supported arguments and the exact way the classifier is visualized depends
 on a library.
 
-To explain an individual prediction (2) use ``eli5.explain_prediction``
+To explain an individual prediction (2) use :func:`eli5.explain_prediction`
 function. Exact parameters depend on a classifier and on input data kind
 (text, tabular, images). For example, you may get text highlighted like this
 if you're using one of the scikit-learn_ vectorizers with char ngrams:
 
 .. image:: static/char-ngrams.png
 
+To learn more, check example IPython
+`notebooks <https://github.com/TeamHG-Memex/eli5/tree/master/notebooks>`_
+and read documentation sections specific to your framework.
 
 Why?
 ----
@@ -87,7 +90,7 @@ For some of classifiers inspection and debugging is easy, for others
 this is hard. It is not a rocket science to take coefficients
 of a linear classifier, relate them to feature names and show in
 an HTML table. ELI5 aims to handle not only simple cases,
-but even for simple cases having unified API for inspection has a value:
+but even for simple cases having a unified API for inspection has a value:
 
 * you can call a ready-made function from ELI5 and get a nicely formatted
   result immediately;

eli5/explain.py

@@ -9,17 +9,125 @@
 
 
 @singledispatch
-def explain_prediction(estimator, doc, **kwargs):
-    """ Return an explanation of an estimator prediction """
+def explain_weights(estimator, **kwargs):
+    """ Return an explanation of estimator parameters (weights).
+
+    :func:`explain_weights` is not doing any work itself, it dispatches
+    to a concrete implementation based on estimator type.
+
+    Parameters
+    ----------
+    estimator : object
+        Estimator instance. This argument must be positional.
+
+    top : int or (int, int) tuple, optional
+        Number of features to show. When ``top`` is int, ``top`` features with
+        a highest absolute values are shown. When it is (pos, neg) tuple,
+        no more than ``pos`` positive features and no more than ``neg``
+        negative features is shown.
+
+        This argument may be supported or not, depending on estimator type.
+
+    target_names : list[str] or {'old_name': 'new_name'} dict, optional
+        Names of targets or classes. This argument can be used to provide
+        human-readable class/target names for estimators which don't expose
+        clss names themselves. It can be also used to rename estimator-provided
+        classes before displaying them.
+
+        This argument may be supported or not, depending on estimator type.
+
+    target_order : list, optional
+        Order of class/target names to show. This argument can be also used
+        to show information only for a subset of classes. It should be a list
+        of class / target names which match names provided by an estimator
+        (i.e. not names defined by ``target_names`` parameter).
+
+        This argument may be supported or not, depending on estimator type.
+
+    feature_names : list, optional
+        A list of feature names. It allows to specify feature
+        names when they are not provided by an estimator object.
+
+        This argument may be supported or not, depending on estimator type.
+
+    **kwargs: dict
+        Keyword arguments. All keyword arguments are passed to
+        concrete explain_weights... implementations.
+
+    Returns
+    -------
+    Explanation
+        :class:`~Explanation` result. Use one of the formatting functions from
+        :mod:`eli5.formatters` to print it in a human-readable form.
+        Explanation instances also have repr which works well with
+        IPython notebook.
+    """
     return Explanation(
         estimator=repr(estimator),
         error="estimator %r is not supported" % estimator,
     )
 
 
 @singledispatch
-def explain_weights(estimator, **kwargs):
-    """ Return an explanation of an estimator weights """
+def explain_prediction(estimator, doc, **kwargs):
+    """
+    Return an explanation of an estimator prediction.
+
+    :func:`explain_prediction` is not doing any work itself, it dispatches
+    to a concrete implementation based on estimator type.
+
+    Parameters
+    ----------
+    estimator : object
+        Estimator instance. This argument must be positional.
+
+    doc : object
+        Example to run estimator on. Estimator makes a prediction for this
+        example, and :func:`explain_prediction` tries to show information
+        about this prediction.
+
+    top : int or (int, int) tuple, optional
+        Number of features to show. When ``top`` is int, ``top`` features with
+        a highest absolute values are shown. When it is (pos, neg) tuple,
+        no more than ``pos`` positive features and no more than ``neg``
+        negative features is shown.
+
+        This argument may be supported or not, depending on estimator type.
+
+    target_names : list[str] or {'old_name': 'new_name'} dict, optional
+        Names of targets or classes. This argument can be used to provide
+        human-readable class/target names for estimators which don't expose
+        clss names themselves. It can be also used to rename estimator-provided
+        classes before displaying them.
+
+        This argument may be supported or not, depending on estimator type.
+
+    target_order : list, optional
+        Order of class/target names to show. This argument can be also used
+        to show information only for a subset of classes. It should be a list
+        of class / target names which match names provided by an estimator
+        (i.e. not names defined by ``target_names`` parameter).
+
+        This argument may be supported or not, depending on estimator type.
+
+    feature_names : list, optional
+        A list of feature names. It allows to specify feature
+        names when they are not provided by an estimator object.
+
+        This argument may be supported or not, depending on estimator type.
+
+    **kwargs: dict
+        Keyword arguments. All keyword arguments are passed to
+        concrete explain_prediction... implementations.
+
+    Returns
+    -------
+    Explanation
+        :class:`~.Explanation` result. Use one of the formatting functions from
+        :mod:`eli5.formatters` to print it in a human-readable form.
+        Explanation instances also have repr which works well with
+        IPython notebook.
+    """
     return Explanation(
         estimator=repr(estimator),
         error="estimator %r is not supported" % estimator,