From dd7fcad589d590371f52f3bcad389ae05f0c5c6e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andreas=20M=C3=BCller?= Date: Sun, 25 Feb 2018 14:19:21 -0500 Subject: [PATCH 1/4] clean up installation doc organization --- doc/developers/advanced_installation.rst | 240 +++++++---------------- doc/developers/contributing.rst | 54 +---- doc/install.rst | 5 +- doc/other_distributions.rst | 73 +++++++ 4 files changed, 151 insertions(+), 221 deletions(-) create mode 100644 doc/other_distributions.rst diff --git a/doc/developers/advanced_installation.rst b/doc/developers/advanced_installation.rst index 4129ac1cc7c86..215b677d8d272 100644 --- a/doc/developers/advanced_installation.rst +++ b/doc/developers/advanced_installation.rst @@ -7,31 +7,28 @@ Advanced installation instructions There are different ways to get scikit-learn installed: + * :ref:`Install an 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. + * Install the version of scikit-learn provided by your :ref:`operating system or Python distribution `. - This is the quickest option for those who have operating systems that - distribute scikit-learn. - - * :ref:`Install an official release `. This - is the best approach for users who want a stable version number - and aren't concerned about running a slightly older version of - scikit-learn. + This is a quick option for those who have operating systems + that distribute scikit-learn. It might not provide the latest release version. - * :ref:`Install the latest development version + * :ref:`Building the package from source `. 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 .. note:: If you wish to contribute to the project, you need to :ref:`install the latest development version`. +.. _install_bleeding_edge: -.. _install_official_release: - -Installing an official release -============================== +Building from source +===================== Scikit-learn requires: @@ -39,26 +36,73 @@ Scikit-learn requires: - NumPy (>= 1.8.2), - SciPy (>= 0.13.3). +Building Scikit-learn also requires -Mac OSX -------- +- Cython >=0.23 -Scikit-learn and its dependencies are all available as wheel packages for OSX:: +Running tests requires - pip install -U numpy scipy scikit-learn +- pytest +.. _git_repo: -Linux ------ +Retrieving the latest code +-------------------------- + +We use `Git `_ for version control and +`GitHub `_ for hosting our main repository. + +You can check out the latest sources with the command:: + + git clone git://github.com/scikit-learn/scikit-learn.git -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. +or if you have write privileges:: + + git clone git@github.com:scikit-learn/scikit-learn.git + +If you want to build a stable version, you can ``git checkout `` to get the code for that particular version, or download an zip archive of the version from github. + +Building from source +-------------------- +If 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. It is thus preferred that +you add the scikit-learn directory to your ``PYTHONPATH`` and build the +extension in place:: + + python setup.py build_ext --inplace + + +Another option is to install the package in editable mode if you change your +code a lot and do not want to have to reinstall every time. This basically +builds the extension in place and creates a link to the development directory +(see `the pip docs `_):: + + pip install --editable . + +.. note:: + + This is fundamentally similar to using the command ``python setup.py develop`` (see `the setuptool docs `_). It is however preferred to use pip. + +.. note:: + + If you decide to do an editable install you have to rerun:: + + 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). + +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. 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. @@ -118,145 +162,9 @@ On Red Hat and clones (e.g. CentOS), install the dependencies using:: sudo yum -y install gcc gcc-c++ numpy python-devel scipy -Building scikit-learn with pip -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is usually the fastest way to install or upgrade to the latest stable -release:: - - pip install --user --install-option="--prefix=" -U scikit-learn - -The ``--user`` flag asks pip to install scikit-learn in the ``$HOME/.local`` -folder therefore not requiring root permission. This flag should make pip -ignore any old version of scikit-learn previously installed on the system while -benefiting from system packages for numpy and scipy. Those dependencies can -be long and complex to build correctly from source. - -The ``--install-option="--prefix="`` flag is only required if Python has a -``distutils.cfg`` configuration with a predefined ``prefix=`` entry. - - -From source package -~~~~~~~~~~~~~~~~~~~ - -download the source package from -`pypi `_, unpack the sources and -cd into the source directory. - -This packages uses distutils, which is the default way of installing -python modules. The install command is:: - - python setup.py install - -or alternatively (also from within the scikit-learn source folder):: - - pip install . - -.. warning:: - - Packages installed with the ``python setup.py install`` command cannot - be uninstalled nor upgraded by ``pip`` later. To properly uninstall - scikit-learn in that case it is necessary to delete the ``sklearn`` folder - from your Python ``site-packages`` directory. - - Windows ------- -First, you need to install `numpy `_ and `scipy -`_ from their own official installers. - -Wheel packages (.whl files) for scikit-learn from `pypi -`_ can be installed with the `pip -`_ utility. -Open a console and type the following to install or upgrade scikit-learn to the -latest stable release:: - - pip install -U scikit-learn - -If there are no binary packages matching your python, version you might -to try to install scikit-learn and its dependencies from `christoph gohlke -unofficial windows installers -`_ -or from a :ref:`python distribution ` instead. - - -.. _install_by_distribution: - -Third party distributions of scikit-learn -========================================= - -Some third-party distributions are now providing versions of -scikit-learn integrated with their package-management systems. - -These can make installation and upgrading much easier for users since -the integration includes the ability to automatically install -dependencies (numpy, scipy) that scikit-learn requires. - -The following is an incomplete list of python and os distributions -that provide their own version of scikit-learn. - - -MacPorts for Mac OSX --------------------- - -The MacPorts package is named ``py-scikits-learn``, -where ``XY`` denotes the Python version. -It can be installed by typing the following -command:: - - sudo port install py26-scikit-learn - -or:: - - sudo port install py27-scikit-learn - - -Arch Linux ----------- - -Arch Linux's package is provided through the `official repositories -`_ as -``python-scikit-learn`` for Python 3 and ``python2-scikit-learn`` for Python 2. -It can be installed by typing the following command: - -.. code-block:: none - - # pacman -S python-scikit-learn - -or: - -.. code-block:: none - - # pacman -S python2-scikit-learn - -depending on the version of Python you use. - - -NetBSD ------- - -scikit-learn is available via `pkgsrc-wip `_: - - http://pkgsrc.se/wip/py-scikit_learn - -Fedora ------- - -The Fedora package is called ``python-scikit-learn`` for the Python 2 version -and ``python3-scikit-learn`` for the Python 3 version. Both versions can -be installed using ``yum``:: - - $ sudo yum install python-scikit-learn - -or:: - - $ sudo yum install python3-scikit-learn - - -Building on windows -------------------- - To build scikit-learn on Windows you need a working C/C++ compiler in addition to numpy, scipy and setuptools. @@ -358,16 +266,6 @@ build step:: where ``my_compiler`` should be one of ``mingw32`` or ``msvc``. -.. _install_bleeding_edge: - -Bleeding Edge -============= - -See section :ref:`git_repo` on how to get the development version. Then follow -the previous instructions to build from source depending on your platform. -You will also require Cython >=0.23 in order to build the development version. - - .. _testing: Testing diff --git a/doc/developers/contributing.rst b/doc/developers/contributing.rst index 7117d9ade4348..8dba9dfe63375 100644 --- a/doc/developers/contributing.rst +++ b/doc/developers/contributing.rst @@ -34,6 +34,12 @@ See :ref:`new_contributors` to get started. | +.. note:: + + If you wish to contribute to the project, you need to + :ref:`install the latest development version`. + + Submitting a bug report ======================= @@ -69,54 +75,6 @@ and articles, link to it from your website, or simply say "I use it": -.. _git_repo: - -Retrieving the latest code -========================== - -We use `Git `_ for version control and -`GitHub `_ for hosting our main repository. - -You can check out the latest sources with the command:: - - git clone git://github.com/scikit-learn/scikit-learn.git - -or if you have write privileges:: - - git clone git@github.com:scikit-learn/scikit-learn.git - -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 -extension in place:: - - python setup.py build_ext --inplace - - -Another option is to install the package in editable mode if you change your -code a lot and do not want to have to reinstall every time. This basically -builds the extension in place and creates a link to the development directory -(see `the pip docs `_):: - - pip install --editable . - -.. note:: - - This is fundamentally similar to using the command ``python setup.py develop`` (see `the setuptool docs `_). It is however preferred to use pip. - -.. note:: - - If you decide to do an editable install you have to rerun:: - - 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). - -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. - Contributing code ================= diff --git a/doc/install.rst b/doc/install.rst index 6fecec888c24f..8e626aad9d70f 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -10,6 +10,8 @@ Installing scikit-learn :ref:`install the latest development version`. +.. _install_official_release: + Installing the latest release ============================= @@ -93,5 +95,4 @@ The `WinPython `_ 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`. diff --git a/doc/other_distributions.rst b/doc/other_distributions.rst new file mode 100644 index 0000000000000..5024ad9502070 --- /dev/null +++ b/doc/other_distributions.rst @@ -0,0 +1,73 @@ + +.. _install_by_distribution: + +Third party distributions of scikit-learn +========================================= + +Some third-party distributions are now providing versions of +scikit-learn integrated with their package-management systems. + +These can make installation and upgrading much easier for users since +the integration includes the ability to automatically install +dependencies (numpy, scipy) that scikit-learn requires. + +The following is an incomplete list of python and os distributions +that provide their own version of scikit-learn. + + +MacPorts for Mac OSX +-------------------- + +The MacPorts package is named ``py-scikits-learn``, +where ``XY`` denotes the Python version. +It can be installed by typing the following +command:: + + sudo port install py26-scikit-learn + +or:: + + sudo port install py27-scikit-learn + + +Arch Linux +---------- + +Arch Linux's package is provided through the `official repositories +`_ as +``python-scikit-learn`` for Python 3 and ``python2-scikit-learn`` for Python 2. +It can be installed by typing the following command: + +.. code-block:: none + + # pacman -S python-scikit-learn + +or: + +.. code-block:: none + + # pacman -S python2-scikit-learn + +depending on the version of Python you use. + + +NetBSD +------ + +scikit-learn is available via `pkgsrc-wip `_: + + http://pkgsrc.se/wip/py-scikit_learn + +Fedora +------ + +The Fedora package is called ``python-scikit-learn`` for the Python 2 version +and ``python3-scikit-learn`` for the Python 3 version. Both versions can +be installed using ``yum``:: + + $ sudo yum install python-scikit-learn + +or:: + + $ sudo yum install python3-scikit-learn + From 279bdb2358e3369a06f4cbe89cb191cada618452 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andreas=20M=C3=BCller?= Date: Sat, 26 May 2018 14:00:58 -0400 Subject: [PATCH 2/4] update os x instructions to python3, suggest editable install by default. --- doc/developers/advanced_installation.rst | 11 ++--------- doc/other_distributions.rst | 4 ++-- 2 files changed, 4 insertions(+), 11 deletions(-) diff --git a/doc/developers/advanced_installation.rst b/doc/developers/advanced_installation.rst index 215b677d8d272..b777d627ca2d3 100644 --- a/doc/developers/advanced_installation.rst +++ b/doc/developers/advanced_installation.rst @@ -67,15 +67,8 @@ Building from source If 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. It is thus preferred that -you add the scikit-learn directory to your ``PYTHONPATH`` and build the -extension in place:: - - python setup.py build_ext --inplace - - -Another option is to install the package in editable mode if you change your -code a lot and do not want to have to reinstall every time. This basically +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 builds the extension in place and creates a link to the development directory (see `the pip docs `_):: diff --git a/doc/other_distributions.rst b/doc/other_distributions.rst index 5024ad9502070..9ca70b7fc36f2 100644 --- a/doc/other_distributions.rst +++ b/doc/other_distributions.rst @@ -23,11 +23,11 @@ where ``XY`` denotes the Python version. It can be installed by typing the following command:: - sudo port install py26-scikit-learn + sudo port install py27-scikit-learn or:: - sudo port install py27-scikit-learn + sudo port install py36-scikit-learn Arch Linux From 174c4ef6103606a2c5e602d6fd40b549df936aa3 Mon Sep 17 00:00:00 2001 From: Andreas Mueller Date: Thu, 28 Jun 2018 11:26:48 -0400 Subject: [PATCH 3/4] address comments. --- doc/developers/advanced_installation.rst | 38 +++++++++++++----------- doc/developers/contributing.rst | 2 +- doc/install.rst | 8 +++-- doc/other_distributions.rst | 1 + 4 files changed, 28 insertions(+), 21 deletions(-) diff --git a/doc/developers/advanced_installation.rst b/doc/developers/advanced_installation.rst index b777d627ca2d3..ed05b7dc1cd8e 100644 --- a/doc/developers/advanced_installation.rst +++ b/doc/developers/advanced_installation.rst @@ -8,17 +8,19 @@ Advanced installation instructions There are different ways to get scikit-learn installed: * :ref:`Install an 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. + is the best approach for most users. It will provide a stable version + and pre-build packages are available for most platforms. * Install the version of scikit-learn provided by your :ref:`operating system or Python distribution `. This is a quick option for those who have operating systems - that distribute scikit-learn. It might not provide the latest release version. + that distribute scikit-learn. It might not provide the latest release + version. * :ref:`Building the package from source `. This is best for users who want the latest-and-greatest features and aren't afraid of running - brand-new code. This document describes how to build from source + brand-new code. This document describes how to build from source. .. note:: @@ -56,19 +58,16 @@ You can check out the latest sources with the command:: git clone git://github.com/scikit-learn/scikit-learn.git -or if you have write privileges:: +If you want to build a stable version, you can ``git checkout `` +to get the code for that particular version, or download an zip archive of +the version from github. - git clone git@github.com:scikit-learn/scikit-learn.git - -If you want to build a stable version, you can ``git checkout `` to get the code for that particular version, or download an zip archive of the version from github. - -Building from source --------------------- -If you have all the build requirements installed (see below for details), you can build and install the package in the following way. +If 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 basically +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 builds the extension in place and creates a link to the development directory (see `the pip docs `_):: @@ -76,13 +75,15 @@ builds the extension in place and creates a link to the development directory .. note:: - This is fundamentally similar to using the command ``python setup.py develop`` (see `the setuptool docs `_). It is however preferred to use pip. + This is fundamentally similar to using the command ``python setup.py develop`` + (see `the setuptool docs `_). + It is however preferred to use pip. .. note:: If you decide to do an editable install you have to rerun:: - python setup.py build_ext --inplace + pip install --editable . every time the source code of a compiled extension is changed (for instance when switching branches or pulling changes from upstream). @@ -268,8 +269,9 @@ Testing scikit-learn once installed ----------------------------------- Testing requires having the `pytest -`_ library. After -installation, the package can be tested by executing *from outside* the +`_ library. Some tests also require having +`pandas ` installed. +After installation, the package can be tested by executing *from outside* the source directory:: $ pytest sklearn @@ -279,7 +281,7 @@ 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 `bug tracker +Otherwise, please consider posting an issue into the `GitHub issue tracker `_ 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 diff --git a/doc/developers/contributing.rst b/doc/developers/contributing.rst index f60eb571208a1..83e336e6d04d6 100644 --- a/doc/developers/contributing.rst +++ b/doc/developers/contributing.rst @@ -37,7 +37,7 @@ See :ref:`new_contributors` to get started. In case you experience issues using this package, do not hesitate to submit a ticket to the -`Bug Tracker `_. You are +`GitHub issue tracker `_. You are also welcome to post feature requests or pull requests. diff --git a/doc/install.rst b/doc/install.rst index 8e626aad9d70f..20a409a6872d4 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -46,6 +46,12 @@ it as ``scikit-learn[alldeps]``. The most common use case for this is in a application or a Docker image. This option is not intended for manual installation from the command line. +For installation instructions for more distributions see +:ref:`other distributions `. +For compiling the development version from source, or building the package +if no distribution is available for your architecture, see the +:ref:`advanced-installation`. + Third-party Distributions ========================== If you don't already have a python installation with numpy and scipy, we @@ -94,5 +100,3 @@ WinPython for Windows The `WinPython `_ project distributes scikit-learn as an additional plugin. - -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`. diff --git a/doc/other_distributions.rst b/doc/other_distributions.rst index 9ca70b7fc36f2..a5c5251e67e34 100644 --- a/doc/other_distributions.rst +++ b/doc/other_distributions.rst @@ -6,6 +6,7 @@ Third party distributions of scikit-learn Some third-party distributions are now providing versions of scikit-learn integrated with their package-management systems. +The most popular ones are listed on the :ref:`install` page. These can make installation and upgrading much easier for users since the integration includes the ability to automatically install From cd8dffb1b442b1fb92455a9ef60f7020fdb3c3df Mon Sep 17 00:00:00 2001 From: Andreas Mueller Date: Thu, 28 Jun 2018 11:28:58 -0400 Subject: [PATCH 4/4] add pandas dependency for tests. --- doc/developers/advanced_installation.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/developers/advanced_installation.rst b/doc/developers/advanced_installation.rst index ed05b7dc1cd8e..19b6c2e455578 100644 --- a/doc/developers/advanced_installation.rst +++ b/doc/developers/advanced_installation.rst @@ -46,6 +46,8 @@ Running tests requires - pytest +Some tests also require `pandas `_. + .. _git_repo: Retrieving the latest code