clean up installation doc organization #10698

amueller · 2018-02-25T19:24:00Z

This is an attempt to clean up the installation docs which I kinda left in shambles at my last attempt to simplify things.

The advanced_installation.rst is currently a mess, and also quite wrong in a couple of places.

I tried to separate out three use-cases:

90% use case: install binary via conda & pip (install.rst)
dev usecase: build from source (developers/advanced_installation.rst)
Third party distribution for uncommon operating systems (other_distributions.rst).

I moved the "getting the bleeding edge code" from "contributing" to "advanced installation" because I'm convinced the mosts common reason for people to build from source is that they want the development version.

This is motivated by my students asking how to install the dev version and me not being able to figure out where to point them.

amueller · 2018-02-25T19:30:05Z

Maybe three main issues I'm trying to resolve with this:

Currently someone trying to install the dev version is sent from install.rst to developers/advanced_installation.rst#install_bleeding_edge to developers/contributing.rst#git_repo and doesn't get a coherent story.
The docs right now say "At this time scikit-learn does not provide official binary packages for Linux so you have to build from source if you want the latest version. If you don’t need the newest version, consider using your package manager to install scikit-learn. It is usually the easiest way, but might not provide the newest version." which is just plain wrong (http://scikit-learn.org/dev/developers/advanced_installation.html#linux)
The docs for linux, after going through installing all the build dependencies with yum or apt do pip install --user --install-option="--prefix=" -U scikit-learn which will then just download a binary package?!

rth · 2018-02-25T20:06:04Z

This also closes #9881

The docs for linux, after going through installing all the build dependencies with yum or apt do pip install --user --install-option="--prefix=" -U scikit-learn which will then just download a binary package?!

Yes, that is strange...

rth · 2018-02-25T20:14:18Z

doc/developers/advanced_installation.rst

+
+If you run the development version, it is cumbersome to reinstall the
+package each time you update the sources. It is thus preferred that
+you add the scikit-learn directory to your ``PYTHONPATH`` and build the


I'm not sure about suggesting to modify PYTHONPATH as the preferred way to install from source.

I think pip install --editable . + suggesting to use either the --user flag or run it in a virtualenv/conda virtualenv (for contributors) might be more standard.

rth · 2018-02-25T20:15:45Z

doc/other_distributions.rst

+It can be installed by typing the following
+command::
+
+    sudo port install py26-scikit-learn


sudo port install py36-scikit-learn

cf #9881 (comment)

…ult.

amueller · 2018-05-26T18:02:54Z

Updated.
.I'm not sure if we should leave the instructions on using build_ext -i after changes. You could also do pip install -e . again, right?
Also not sure if we want to go into environments. If you have a good resource we can link it, but if we say something half-baked I don't think it's gonna be useful.

jnothman

Otherwise LGTM

jnothman · 2018-05-26T22:42:33Z

doc/developers/advanced_installation.rst


-    pip install -U numpy scipy scikit-learn
+- pytest



Some tests require pandas

not to self: sync with current travis setup. Also maybe point to the travis setup file here?

jnothman · 2018-05-27T10:52:22Z

doc/install.rst

@@ -93,5 +95,4 @@ The `WinPython <https://winpython.github.io/>`_ project distributes
 scikit-learn as an additional plugin.


-For installation instructions for particular operating systems or for compiling
-the bleeding edge version, see the :ref:`advanced-installation`.
+For installation instructions for more distributions see :ref:`install_by_distribution`. For compiling the development version from source, or building the package if no distribution is available for your architecture, see the :ref:`advanced-installation`.


This is awkward because it's under a heading about third party distributions and says "see Third party distributions of scikit-learn". Rather, put this paragraph before Anaconda and WinPython, and alias the link to say "see other distributions".

jnothman · 2018-05-27T10:53:04Z

doc/other_distributions.rst

+
+Some third-party distributions are now providing versions of
+scikit-learn integrated with their package-management systems.
+


You should note that the most popular are listed on the install page.

rth

Also not sure if we want to go into environments. If you have a good resource we can link it, but if we say something half-baked I don't think it's gonna be useful.

Agreed that we don't want to go there. I am not aware of any reference resource that would make sense of virtualenv, pipenv and conda env, but this one does try to. I'm not completely convinced it should be linked.

A few minor comments are below, otherwise LGTM.

rth · 2018-05-27T16:45:39Z

doc/developers/advanced_installation.rst

@@ -7,58 +7,95 @@ Advanced installation instructions

 There are different ways to get scikit-learn installed:

+  * :ref:`Install an official release <install_official_release>`. This
+    is the best approach for most users. It will provide a stable version and pre-build packages are available for most platforms.


Maybe add a line break

I know it's a copy paste but I would remove these two lines. It's unrelated to having to write privileges but rather is to do with registering an SSH key on GitHub (one can clone any repository via ssh). And even for people with write privileges cloning a fork is safer IMO to avoid pushing local branches to the scikit-learn org by accident..

you're right, this is confusing / not true.

rth · 2018-05-27T16:51:53Z

doc/developers/advanced_installation.rst

+
+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 basically


remove "basically"

rth · 2018-05-27T16:58:52Z

doc/developers/advanced_installation.rst

+        python setup.py build_ext --inplace
+
+    every time the source code of a compiled extension is
+    changed (for instance when switching branches or pulling changes from upstream).


I'm not sure if we should leave the instructions on using build_ext -i after changes. You could also do pip install -e . again, right?

Yes, I just run pip install -e . to update - it does only recompile the changed Cython files as far as I can tell. Not sure what's the official position about this upstream, but if we use pip instead of setuptools to install IMO it would also make sense to use pip to re-compile extensions.

rth · 2018-05-27T17:00:01Z

doc/developers/contributing.rst

+
+In case you experience issues using this package, do not hesitate to submit a
+ticket to the
+`Bug Tracker <https://github.com/scikit-learn/scikit-learn/issues>`_. You are


"Github Issue tracker" (just to make it explicit that issues are tracked on Github without having to inspect the URL)

rth · 2018-05-27T17:02:46Z

doc/developers/advanced_installation.rst

    <install_bleeding_edge>`. This is best for users who want the
    latest-and-greatest features and aren't afraid of running
-    brand-new code.
+    brand-new code. This document describes how to build from source 


Dot missing.

rth · 2018-06-13T22:00:22Z

It would be helpful to include these improved installation instructions for the next release...

amueller · 2018-06-26T16:51:51Z

doc/developers/advanced_installation.rst


 Scikit-learn requires:

 - Python (>= 2.7 or >= 3.4),
 - NumPy (>= 1.8.2),
 - SciPy (>= 0.13.3).

+Building Scikit-learn also requires


since this is the building section this header might be superfluous?

amueller · 2018-06-28T15:30:39Z

this could probably do with some more polish but I think it's an improvement. Merge and go from there?

amueller · 2018-06-29T20:33:33Z

thanks @jnothman !

clean up installation doc organization

dd7fcad

rth reviewed Feb 25, 2018

View reviewed changes

update os x instructions to python3, suggest editable install by defa…

279bdb2

…ult.

Merge branch 'master' into install_doc_reorg

cb0a313

jnothman reviewed May 27, 2018

View reviewed changes

rth reviewed May 27, 2018

View reviewed changes

amueller mentioned this pull request Jun 7, 2018

Compiler issue after conda update ContinuumIO/anaconda-issues#7363

Closed

rth added this to the 0.20 milestone Jun 13, 2018

amueller commented Jun 26, 2018

View reviewed changes

amueller added 3 commits June 28, 2018 11:10

Merge branch 'master' into install_doc_reorg

a591d13

address comments.

174c4ef

add pandas dependency for tests.

cd8dffb

jnothman merged commit a320c08 into scikit-learn:master Jun 28, 2018

amueller deleted the install_doc_reorg branch June 29, 2018 20:33

Eschivo mentioned this pull request Jul 20, 2022

DOC Improvements to developer documentation #23551

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

clean up installation doc organization #10698

clean up installation doc organization #10698


		Some third-party distributions are now providing versions of
		scikit-learn integrated with their package-management systems.

-              newest version.
+              or if you have write privileges::
+                  git clone git@github.com:scikit-learn/scikit-learn.git

clean up installation doc organization #10698

clean up installation doc organization #10698

Conversation

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment