Merge branch 'for0.21.3' into 0.21.X

Author: jnothman

CONTRIBUTING.md

@@ -2,6 +2,11 @@
 Contributing to scikit-learn
 ============================
 
+The latest contributing guide is available in the repository at
+`doc/developers/contributing.rst`, or online at:
+
+https://scikit-learn.org/dev/developers/contributing.html
+
 There are many ways to contribute to scikit-learn, with the most common ones
 being contribution of code or documentation to the project. Improving the
 documentation is no less important than improving the library itself. If you
@@ -22,15 +27,9 @@ up" on issues that others reported and that are relevant to you. It also helps
 us if you spread the word: reference the project from your blog and articles,
 link to it from your website, or simply star it in GitHub to say "I use it".
 
-Guideline
----------
-
-Full contribution guidelines are available in the repository at
-`doc/developers/contributing.rst`, or online at:
-
-http://scikit-learn.org/dev/developers/contributing.html
+Quick links
+-----------
 
-Quick links to:
 * [Submitting a bug report or feature request](http://scikit-learn.org/dev/developers/contributing.html#submitting-a-bug-report-or-a-feature-request)
 * [Contributing code](http://scikit-learn.org/dev/developers/contributing.html#contributing-code)
 * [Coding guidelines](http://scikit-learn.org/dev/developers/contributing.html#coding-guidelines)

README.rst

@@ -58,13 +58,6 @@ Scikit-learn 0.21 and later require Python 3.5 or newer.
 For running the examples Matplotlib >= 1.5.1 is required. A few examples
 require scikit-image >= 0.12.3, a few examples require pandas >= 0.18.0.
 
-scikit-learn also uses CBLAS, the C interface to the Basic Linear Algebra
-Subprograms library. scikit-learn comes with a reference implementation, but
-the system CBLAS will be detected by the build system and used if present.
-CBLAS exists in many implementations; see `Linear algebra libraries
-<http://scikit-learn.org/stable/modules/computing#linear-algebra-libraries>`_
-for known issues.
-
 User installation
 ~~~~~~~~~~~~~~~~~
 
@@ -111,8 +104,10 @@ You can check the latest sources with the command::
 
 Contributing
 ~~~~~~~~~~~~
-To learn more about making a contribution to scikit-learn, please view the contributing document: 
-https://github.com/scikit-learn/scikit-learn/blob/master/CONTRIBUTING.md
+
+To learn more about making a contribution to scikit-learn, please see our
+`Contributing guide
+<https://scikit-learn.org/dev/developers/contributing.html>`_.
 
 Testing
 ~~~~~~~

doc/about.rst

@@ -1,3 +1,5 @@
+.. _about:
+
 About us
 ========
 
@@ -14,6 +16,11 @@ release, February the 1st 2010. Since then, several releases have appeared
 following a ~3 month cycle, and a thriving international community has
 been leading the development.
 
+Governance
+----------
+The decision making process and governance structure of scikit-learn is laid
+out in the :ref:`governance document <governance>`.
+
 Authors
 -------
 
@@ -69,11 +76,6 @@ The following people have been active contributors in the past, but are no longe
 - Virgile Fritsch
 - Wei Li
 
-Governance
-----------
-The decision making process and governance structure of scikit-learn is laid
-out in the :ref:`governance document <governance>`.
-
 .. _citing-scikit-learn:
 
 Citing scikit-learn

doc/developers/advanced_installation.rst

@@ -44,11 +44,26 @@ basis to help users test bleeding edge features or bug fixes::
 Building from source
 =====================
 
+In the vast majority of cases, building scikit-learn for development purposes
+can be done with::
+
+    pip install cython pytest flake8
+
+Then, in the main repository::
+
+    pip install --editable .
+
+Please read below for details and more advanced instructions.
+
+Dependencies
+------------
+
 Scikit-learn requires:
 
 - Python (>= 3.5),
 - NumPy (>= 1.11),
-- SciPy (>= 0.17).
+- SciPy (>= 0.17),
+- Joblib (>= 0.11).
 
 .. note::
 
@@ -93,12 +108,12 @@ If you want to build a stable version, you can ``git checkout <VERSION>``
 to get the code for that particular version, or download an zip archive of
 the version from github.
 
-If you have all the build requirements installed (see below for details), you
-can build and install the package in the following way.
+Once you have all the build requirements installed (see below for details),
+you can build and install the package in the following way.
 
 If you run the development version, it is cumbersome to reinstall the
 package each time you update the sources. Therefore it's recommended that you
-install in editable, which allows you to edit the code in-place. This
+install in editable mode, which allows you to edit the code in-place. This
 builds the extension in place and creates a link to the development directory
 (see `the pip docs <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_)::
 
@@ -112,16 +127,16 @@ builds the extension in place and creates a link to the development directory
 
 .. note::
 
-    If you decide to do an editable install you have to rerun::
+    You will have to re-run::
 
         pip install --editable .
 
-    every time the source code of a compiled extension is
-    changed (for instance when switching branches or pulling changes from upstream).
+    every time the source code of a compiled extension is changed (for
+    instance when switching branches or pulling changes from upstream).
+    Compiled extensions are Cython files (ending in `.pyx` or `.pxd`).
 
-On Unix-like systems, you can simply type ``make`` in the top-level folder to
-build in-place and launch all the tests. Have a look at the ``Makefile`` for
-additional utilities.
+On Unix-like systems, you can equivalently type ``make in`` from the
+top-level folder. Have a look at the ``Makefile`` for additional utilities.
 
 Mac OSX
 -------
@@ -148,62 +163,68 @@ Then you need to set the following environment variables::
 
 Finally you can build the package using the standard command.
 
+FreeBSD
+-------
+
+The clang compiler included in FreeBSD 12.0 and 11.2 base systems does not 
+include OpenMP support. You need to install the `openmp` library from packages 
+(or ports)::
+
+    sudo pkg install openmp
+    
+This will install header files in ``/usr/local/include`` and libs in 
+``/usr/local/lib``. Since these directories are not searched by default, you 
+can set the environment variables to these locations::
+
+    export CFLAGS="$CFLAGS -I/usr/local/include"
+    export CXXFLAGS="$CXXFLAGS -I/usr/local/include"
+    export LDFLAGS="$LDFLAGS -L/usr/local/lib -lomp"
+    export DYLD_LIBRARY_PATH=/usr/local/lib
+
+Finally you can build the package using the standard command.
+
+For the upcomming FreeBSD 12.1 and 11.3 versions, OpenMP will be included in 
+the base system and these steps will not be necessary.
+
+
 Installing build dependencies
 =============================
 
 Linux
 -----
 
-Installing from source requires you to have installed the scikit-learn runtime
-dependencies, Python development headers and a working C/C++ compiler.
-Under Debian-based operating systems, which include Ubuntu::
+Installing from source without conda requires you to have installed the
+scikit-learn runtime dependencies, Python development headers and a working
+C/C++ compiler. Under Debian-based operating systems, which include Ubuntu::
 
     sudo apt-get install build-essential python3-dev python3-setuptools \
-                     python3-numpy python3-scipy \
-                     libatlas-dev libatlas3-base
-
-On recent Debian and Ubuntu (e.g. Ubuntu 14.04 or later) make sure that ATLAS
-is used to provide the implementation of the BLAS and LAPACK linear algebra
-routines::
+                     python3-pip
+    
+and then::
 
-    sudo update-alternatives --set libblas.so.3 \
-        /usr/lib/atlas-base/atlas/libblas.so.3
-    sudo update-alternatives --set liblapack.so.3 \
-        /usr/lib/atlas-base/atlas/liblapack.so.3
+    pip3 install numpy scipy cython
 
 .. note::
 
     In order to build the documentation and run the example code contains in
     this documentation you will need matplotlib::
 
-        sudo apt-get install python-matplotlib
-
-.. note::
-
-    The above installs the ATLAS implementation of BLAS
-    (the Basic Linear Algebra Subprograms library).
-    Ubuntu 11.10 and later, and recent (testing) versions of Debian,
-    offer an alternative implementation called OpenBLAS.
-
-    Using OpenBLAS can give speedups in some scikit-learn modules,
-    but can freeze joblib/multiprocessing prior to OpenBLAS version 0.2.8-4,
-    so using it is not recommended unless you know what you're doing.
+        pip3 install matplotlib
 
-    If you do want to use OpenBLAS, then replacing ATLAS only requires a couple
-    of commands. ATLAS has to be removed, otherwise NumPy may not work::
+When precompiled wheels are not avalaible for your architecture, you can
+install the system versions::
 
-        sudo apt-get remove libatlas3gf-base libatlas-dev
-        sudo apt-get install libopenblas-dev
-
-        sudo update-alternatives  --set libblas.so.3 \
-            /usr/lib/openblas-base/libopenblas.so.0
-        sudo update-alternatives --set liblapack.so.3 \
-            /usr/lib/lapack/liblapack.so.3
+    sudo apt-get install cython3 python3-numpy python3-scipy python3-matplotlib
 
 On Red Hat and clones (e.g. CentOS), install the dependencies using::
 
-    sudo yum -y install gcc gcc-c++ numpy python-devel scipy
+    sudo yum -y install gcc gcc-c++ python-devel numpy scipy
+
+.. note::
 
+    To use a high performance BLAS library (e.g. OpenBlas) see 
+    `scipy installation instructions
+    <https://docs.scipy.org/doc/scipy/reference/building/linux.html>`_.
 
 Windows
 -------
@@ -260,58 +281,3 @@ build step::
     python setup.py build --compiler=my_compiler install
 
 where ``my_compiler`` should be one of ``mingw32`` or ``msvc``.
-
-
-.. _testing:
-
-Testing
-=======
-
-Testing scikit-learn once installed
------------------------------------
-
-Testing requires having `pytest <https://docs.pytest.org>`_ >=\ |PytestMinVersion|\ .
-Some tests also require having `pandas <https://pandas.pydata.org/>` installed.
-After installation, the package can be tested by executing *from outside* the
-source directory::
-
-    $ pytest sklearn
-
-This should give you a lot of output (and some warnings) but
-eventually should finish with a message similar to::
-
-    =========== 8304 passed, 26 skipped, 4659 warnings in 557.76 seconds ===========
-
-Otherwise, please consider posting an issue into the `GitHub issue tracker
-<https://github.com/scikit-learn/scikit-learn/issues>`_ or to the
-:ref:`mailing_lists` including the traceback of the individual failures
-and errors. Please include your operating system, your version of NumPy, SciPy
-and scikit-learn, and how you installed scikit-learn.
-
-
-Testing scikit-learn from within the source folder
---------------------------------------------------
-
-Scikit-learn can also be tested without having the package
-installed. For this you must compile the sources inplace from the
-source directory::
-
-    python setup.py build_ext --inplace
-
-Test can now be run using pytest::
-
-    pytest sklearn
-
-This is automated by the commands::
-
-    make in
-
-and::
-
-    make test
-
-
-You can also install a symlink named ``site-packages/scikit-learn.egg-link``
-to the development folder of scikit-learn with::
-
-    pip install --editable .