DOC A glossary of concepts and API elements (scikit-learn#9517)

Skeleton for a glossary of concepts and API elements.

This responds to at least three issues:

* Many aspects of scikit-learn API for users and developers are known
  tacitly by core contributors (and the stack overflow crowd), but are
  not written down in a consistent place.
* What is written is in an ad-hoc narrative style which may be useful
  for introduction, but is difficult to refer to and to maintain.
* Parameters such as `n_jobs` and methods like `decision_function` are
  described repeatedly in documentation giving sometimes more sometimes
  less information. This glossary allows us to use "See :term:`the
  glossary <n_jobs>`." so that parameter descriptions in the
  API reference can remain brief (just as not every numpy operation
  needs to describe broadcasting).

Author: jnothman

doc/conf.py

@@ -236,6 +236,7 @@
     'numpy': ('https://docs.scipy.org/doc/numpy/', None),
     'scipy': ('https://docs.scipy.org/doc/scipy/reference', None),
     'matplotlib': ('https://matplotlib.org/', None),
+    'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
 }
 
 sphinx_gallery_conf = {

doc/developers/contributing.rst

@@ -752,6 +752,8 @@ when an estimator is ``fit`` twice to the same data,
 it should produce an identical model both times,
 hence the validation in ``fit``, not ``__init__``.
 
+.. _contributing_deprecation:
+
 Deprecation
 -----------
 
@@ -893,6 +895,7 @@ from high-level questions to a more detailed check-list.
 
 :ref:`saved_replies` includes some frequent comments that reviewers may make.
 
+.. _api_overview:
 
 APIs of scikit-learn objects
 ============================
@@ -902,6 +905,9 @@ objects. In addition, to avoid the proliferation of framework code, we
 try to adopt simple conventions and limit to a minimum the number of
 methods an object must implement.
 
+Elements of the scikit-learn API are described more definitively in the
+:ref:`glossary`.
+
 Different objects
 -----------------
 
@@ -1260,7 +1266,9 @@ is implemented using the ``_estimator_type`` attribute, which takes a string val
 It should be ``"classifier"`` for classifiers and ``"regressor"`` for
 regressors and ``"clusterer"`` for clustering methods, to work as expected.
 Inheriting from ``ClassifierMixin``, ``RegressorMixin`` or ``ClusterMixin``
-will set the attribute automatically.
+will set the attribute automatically.  When a meta-estimator needs to distinguish
+among estimator types, instead of checking ``_estimator_type`` directly, helpers
+like :func:`base.is_classifier` should be used.
 
 Working notes
 -------------

doc/documentation.rst

@@ -47,6 +47,12 @@ Documentation of scikit-learn |version|
                     machine learning field.
                     </blockquote>
                 </div>
+                <div class="span4 box">
+                    <h2><a href="glossary.html">Glossary</a></h2>
+                            <blockquote>The definitive description of key concepts
+                            and API elements for using scikit-learn and developing compatible tools.
+                            </blockquote>
+                </div>
                 <div class="span4 box">
                     <h2><a href="modules/classes.html">API</a></h2>
                             <blockquote>The exact API of all functions and classes, as given by the docstrings.
@@ -55,11 +61,6 @@ Documentation of scikit-learn |version|
                             </blockquote>
                 </div>
 
-                <div class="span4 box">
-                    <h2><a href="presentations.html">Additional Resources</a></h2>
-                                <blockquote>Talks given, slide-sets and other information relevant to scikit-learn.
-                                </blockquote>
-                </div>
             </div>
           <!-- row -->
             <div class="row-fluid">
@@ -70,22 +71,27 @@ Documentation of scikit-learn |version|
                             how to build their own estimators.
                             </blockquote>
                 </div>
-
-                <div class="span4 box">
-                    <h2><a href="tutorial/machine_learning_map/index.html">Flow Chart</a></h2>
-                    <blockquote>A graphical overview of basic areas of machine
-                        learning, and guidance which kind of algorithms
-                        to use in a given situation.
-                    </blockquote>
-                </div>
                 <div class="span4 box">
                     <h2><a href="faq.html">FAQ</a></h2>
                     <blockquote>Frequently asked questions about the project and contributing.
                     </blockquote>
                 </div>
+                <div class="span4 box">
+                    <h2><a href="presentations.html">Additional Resources</a></h2>
+                                <blockquote>Talks given, slide-sets and other information relevant to scikit-learn.
+                                </blockquote>
+                </div>
+
             </div>
 
             <div class="row-fluid">
+                <div class="span4 box">
+                    <h2><a href="tutorial/machine_learning_map/index.html">Flow Chart</a></h2>
+                    <blockquote>A graphical overview of basic areas of machine
+                        learning, and guidance which kind of algorithms
+                        to use in a given situation.
+                    </blockquote>
+                </div>
                 <div class="span4 box">
                     <h2><a href="related_projects.html">Related packages</a></h2>
                     <blockquote>Other machine learning packages for Python and

doc/faq.rst

@@ -280,6 +280,8 @@ program: Insert the following instructions in your main script::
 You can find more default on the new start methods in the `multiprocessing
 documentation <https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods>`_.
 
+.. _faq_mkl_threading:
+
 Why does my job use more cores than specified with n_jobs under OSX or Linux?
 -----------------------------------------------------------------------------