DOC Contributing guide update (scikit-learn#13961)

Author: NicolasHug

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

@@ -111,8 +111,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
 -------
@@ -284,58 +299,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 .