[docs] update Python-package installation guide (#6767)

* Update README.rst

* Update README.rst

* Update pyproject.toml

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update pyproject.toml

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update pyproject.toml

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update pyproject.toml

* Update README.rst

* Update README.rst

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update README.rst

* Update README.rst

* Update build-python.sh

* Update README.rst

* Update README.rst

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update README.rst

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update README.rst

* Update build-python.sh

* Update README.rst

* Update README.rst

* Update README.rst

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update build-python.sh

* Update LightGBM.vcxproj

* Update LightGBM.vcxproj

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* Update README.rst

* no more than one sentence per one line

* address review comments

* address review comments

---------
Co-authored-by: James Lamb <jaylamb20@gmail.com>

build-python.sh

@@ -55,14 +55,14 @@
 #                                   Use precompiled library.
 #                                   Only used with 'install' command.
 #     --time-costs
-#                                   Output time costs for different internal routines.
+#                                   Compile version that outputs time costs for different internal routines.
 #     --user
 #                                   Install into user-specific instead of global site-packages directory.
 #                                   Only used with 'install' command.
 
 set -e -u
 
-echo "building lightgbm"
+echo "[INFO] building lightgbm"
 
 # Default values of arguments
 INSTALL="false"
@@ -136,9 +136,8 @@ while [ $# -gt 0 ]; do
     # flags #
     #########
     --bit32)
-        export CMAKE_GENERATOR="Visual Studio 17 2022"
-        export CMAKE_GENERATOR_PLATFORM="Win32"
-        echo "[INFO] Attempting to build 32-bit version of LightGBM, which is only supported on Windows with generator '${CMAKE_GENERATOR}'."
+        echo "[INFO] Attempting to build 32-bit version of LightGBM, which is only supported on Windows with Visual Studio."
+        BUILD_ARGS="${BUILD_ARGS} --config-setting=cmake.args=-AWin32"
         ;;
     --cuda)
         BUILD_ARGS="${BUILD_ARGS} --config-setting=cmake.define.USE_CUDA=ON"
@@ -150,9 +149,9 @@ while [ $# -gt 0 ]; do
         BUILD_ARGS="${BUILD_ARGS} --config-setting=cmake.define.__INTEGRATE_OPENCL=ON"
         ;;
     --mingw)
-        export CMAKE_GENERATOR='MinGW Makefiles'
         # ref: https://stackoverflow.com/a/45104058/3986677
         BUILD_ARGS="${BUILD_ARGS} --config-setting=cmake.define.CMAKE_SH=CMAKE_SH-NOTFOUND"
+        BUILD_ARGS="${BUILD_ARGS} --config-setting=cmake.args=-G'MinGW Makefiles'"
         ;;
     --mpi)
         BUILD_ARGS="${BUILD_ARGS} --config-setting=cmake.define.USE_MPI=ON"
@@ -174,7 +173,7 @@ while [ $# -gt 0 ]; do
         PIP_INSTALL_ARGS="${PIP_INSTALL_ARGS} --user"
         ;;
     *)
-        echo "invalid argument '${1}'"
+        echo "[ERROR] invalid argument '${1}'. Aborting"
         exit 1
         ;;
   esac
@@ -315,18 +314,28 @@ if test "${INSTALL}" = true; then
         echo "" >> ./MANIFEST.in
         mkdir -p ./lightgbm/lib
         if test -f ../lib_lightgbm.so; then
-            echo "found pre-compiled lib_lightgbm.so"
+            echo "[INFO] found pre-compiled lib_lightgbm.so"
             cp ../lib_lightgbm.so ./lightgbm/lib/lib_lightgbm.so
         elif test -f ../lib_lightgbm.dylib; then
-            echo "found pre-compiled lib_lightgbm.dylib"
+            echo "[INFO] found pre-compiled lib_lightgbm.dylib"
             cp ../lib_lightgbm.dylib ./lightgbm/lib/lib_lightgbm.dylib
+        elif test -f ../lib_lightgbm.dll; then
+            echo "[INFO] found pre-compiled lib_lightgbm.dll"
+            cp ../lib_lightgbm.dll ./lightgbm/lib/lib_lightgbm.dll
         elif test -f ../Release/lib_lightgbm.dll; then
-            echo "found pre-compiled Release/lib_lightgbm.dll"
+            echo "[INFO] found pre-compiled Release/lib_lightgbm.dll"
             cp ../Release/lib_lightgbm.dll ./lightgbm/lib/lib_lightgbm.dll
         elif test -f ../windows/x64/DLL/lib_lightgbm.dll; then
-            echo "found pre-compiled windows/x64/DLL/lib_lightgbm.dll"
+            echo "[INFO] found pre-compiled windows/x64/DLL/lib_lightgbm.dll"
             cp ../windows/x64/DLL/lib_lightgbm.dll ./lightgbm/lib/lib_lightgbm.dll
             cp ../windows/x64/DLL/lib_lightgbm.lib ./lightgbm/lib/lib_lightgbm.lib
+        elif test -f ../windows/x64/Debug_DLL/lib_lightgbm.dll; then
+            echo "[INFO] found pre-compiled windows/x64/Debug_DLL/lib_lightgbm.dll"
+            cp ../windows/x64/Debug_DLL/lib_lightgbm.dll ./lightgbm/lib/lib_lightgbm.dll
+            cp ../windows/x64/Debug_DLL/lib_lightgbm.lib ./lightgbm/lib/lib_lightgbm.lib
+        else
+            echo "[ERROR] cannot find pre-compiled library. Aborting"
+            exit 1
         fi
         rm -f ./*.bak
     else
@@ -336,29 +345,27 @@ if test "${INSTALL}" = true; then
 fi
 
 if test "${BUILD_SDIST}" = true; then
-    echo "--- building sdist ---"
+    echo "[INFO] --- building sdist ---"
     rm -f ../dist/*.tar.gz
-    # shellcheck disable=SC2086
-    python -m build \
-        --sdist \
-        --outdir ../dist \
-        ${BUILD_ARGS} \
-        .
+    # use xargs to work with args that contain whitespaces
+    # note that empty echo string leads to that xargs doesn't run the command
+    # in some implementations of xargs
+    # ref: https://stackoverflow.com/a/8296746
+    echo "--sdist --outdir ../dist ${BUILD_ARGS} ." | xargs python -m build
 fi
 
 if test "${BUILD_WHEEL}" = true; then
-    echo "--- building wheel ---"
+    echo "[INFO] --- building wheel ---"
     rm -f ../dist/*.whl || true
-    # shellcheck disable=SC2086
-    python -m build \
-        --wheel \
-        --outdir ../dist \
-        ${BUILD_ARGS} \
-        .
+    # use xargs to work with args that contain whitespaces
+    # note that empty echo string leads to that xargs doesn't run the command
+    # in some implementations of xargs
+    # ref: https://stackoverflow.com/a/8296746
+    echo "--wheel --outdir ../dist ${BUILD_ARGS} ." | xargs python -m build
 fi
 
 if test "${INSTALL}" = true; then
-    echo "--- installing lightgbm ---"
+    echo "[INFO] --- installing lightgbm ---"
     cd ../dist
     if test "${BUILD_WHEEL}" = true; then
         PACKAGE_NAME="$(echo lightgbm*.whl)"
@@ -377,5 +384,5 @@ if test "${INSTALL}" = true; then
     cd ../
 fi
 
-echo "cleaning up"
+echo "[INFO] cleaning up"
 rm -rf ./lightgbm-python

python-package/README.rst

@@ -9,7 +9,11 @@ Installation
 Preparation
 '''''''''''
 
-32-bit Python is not supported. Please install 64-bit version. If you have a strong need to install with 32-bit Python, refer to `Build 32-bit Version with 32-bit Python section <#build-32-bit-version-with-32-bit-python>`__.
+32-bit Python is not supported.
+Please install 64-bit version.
+If you have a strong need to install with 32-bit Python, refer to `Build 32-bit Version with 32-bit Python section <#build-32-bit-version-with-32-bit-python>`__.
+
+|
 
 Install from `PyPI <https://pypi.org/project/lightgbm>`_
 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''
@@ -18,26 +22,36 @@ Install from `PyPI <https://pypi.org/project/lightgbm>`_
 
     pip install lightgbm
 
-Compiled library that is included in the wheel file supports both **GPU** and **CPU** versions out of the box. This feature is experimental and available only for **Windows** and **Linux** currently. To use **GPU** version you only need to install OpenCL Runtime libraries. For NVIDIA and AMD GPU they are included in the ordinary drivers for your graphics card, so no action is required. If you would like your AMD or Intel CPU to act like a GPU (for testing and debugging) you can install `AMD APP SDK <https://github.com/microsoft/LightGBM/releases/download/v2.0.12/AMD-APP-SDKInstaller-v3.0.130.135-GA-windows-F-x64.exe>`_ on **Windows** and `PoCL <http://portablecl.org>`_ on **Linux**. Many modern Linux distributions provide packages for PoCL, look for ``pocl-opencl-icd`` on Debian-based distributions and ``pocl`` on RedHat-based distributions.
+Compiled library that is included in the wheel file supports both **GPU** (don't confuse with CUDA version) and **CPU** versions out of the box.
+This feature is available only for **Windows** and **Linux** currently.
+To use **GPU** version you only need to install OpenCL Runtime libraries.
+For NVIDIA and AMD GPU they are included in the ordinary drivers for your graphics card, so no action is required.
+If you would like your AMD or Intel CPU to act like a GPU (for testing and debugging),
+you can install `AMD APP SDK <https://github.com/microsoft/LightGBM/releases/download/v2.0.12/AMD-APP-SDKInstaller-v3.0.130.135-GA-windows-F-x64.exe>`_ on **Windows** and `PoCL <https://portablecl.org>`_ on **Linux**.
+Many modern Linux distributions provide packages for PoCL, look for ``pocl-opencl-icd`` on Debian-based distributions and ``pocl`` on RedHat-based distributions.
+
+For **Windows** users, `VC runtime <https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads>`_ is needed if **Visual Studio** is not installed.
+
+For **macOS** users, the **OpenMP** library is needed.
+You can install it by the following command: ``brew install libomp``.
 
-For **Windows** users, `VC runtime <https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads>`_ is needed if **Visual Studio** (2015 or newer) is not installed.
+|
 
-In some rare cases, when you hit ``OSError: libgomp.so.1: cannot open shared object file: No such file or directory`` error during importing LightGBM, you need to install OpenMP runtime library separately (use your package manager and search for ``lib[g|i]omp`` for doing this).
+Use LightGBM with PyArrow
+*************************
 
-For **macOS** (we provide wheels for 3 newest macOS versions) users:
+To install all dependencies needed to use ``PyArrow`` in LightGBM, append ``[arrow]``.
 
-- Starting from version 2.2.1, the library file in distribution wheels is built by the **Apple Clang** (Xcode_8.3.3 for versions 2.2.1 - 2.3.1, Xcode_9.4.1 for versions 2.3.2 - 3.3.2 and Xcode_11.7 from version 4.0.0) compiler. This means that you don't need to install the **gcc** compiler anymore. Instead of that you need to install the **OpenMP** library, which is required for running LightGBM on the system with the **Apple Clang** compiler. You can install the **OpenMP** library by the following command: ``brew install libomp``.
+.. code:: sh
 
-- For version smaller than 2.2.1 and not smaller than 2.1.2, **gcc-8** with **OpenMP** support must be installed first. Refer to `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#gcc>`__ for installation of **gcc-8** with **OpenMP** support.
+    pip install 'lightgbm[arrow]'
 
-- For version smaller than 2.1.2, **gcc-7** with **OpenMP** is required.
+|
 
 Use LightGBM with Dask
 **********************
 
-.. warning::
-
-    Dask-package is only tested on Linux.
+Warning: Dask-package is only tested on macOS and Linux.
 
 To install all dependencies needed to use ``lightgbm.dask``, append ``[dask]``.
 
@@ -45,6 +59,8 @@ To install all dependencies needed to use ``lightgbm.dask``, append ``[dask]``.
 
     pip install 'lightgbm[dask]'
 
+|
+
 Use LightGBM with pandas
 ************************
 
@@ -54,49 +70,66 @@ To install all dependencies needed to use ``pandas`` in LightGBM, append ``[pand
 
     pip install 'lightgbm[pandas]'
 
+|
+
+Use LightGBM Plotting Capabilities
+**********************************
+
+To install all dependencies needed to use ``lightgbm.plotting``, append ``[plotting]``.
+
+.. code:: sh
+
+    pip install 'lightgbm[plotting]'
+
+|
+
 Use LightGBM with scikit-learn
 ******************************
 
-To install all dependencies needed to use ``scikit-learn`` in LightGBM, append ``[scikit-learn]``.
+To install all dependencies needed to use ``lightgbm.sklearn``, append ``[scikit-learn]``.
 
 .. code:: sh
 
     pip install 'lightgbm[scikit-learn]'
 
+|
+
 Build from Sources
 ******************
 
 .. code:: sh
 
-    pip install --no-binary lightgbm lightgbm
-
-Also, in some rare cases you may need to install OpenMP runtime library separately (use your package manager and search for ``lib[g|i]omp`` for doing this).
+    pip install lightgbm --no-binary lightgbm
 
 For **macOS** users, you can perform installation either with **Apple Clang** or **gcc**.
 
 - In case you prefer **Apple Clang**, you should install **OpenMP** (details for installation can be found in `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#apple-clang>`__) first.
 
-- In case you prefer **gcc**, you need to install it (details for installation can be found in `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#gcc>`__) and specify compilers by running ``export CXX=g++-7 CC=gcc-7`` (replace "7" with version of **gcc** installed on your machine) first.
+- In case you prefer **gcc**, you need to install it (details for installation can be found in `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#gcc-1>`__) and specify compilers by running ``export CXX=g++-7 CC=gcc-7`` (replace "7" with version of **gcc** installed on your machine) first.
 
 For **Windows** users, **Visual Studio** (or `VS Build Tools <https://visualstudio.microsoft.com/downloads/>`_) is needed.
 
+|
+
 Build Threadless Version
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code:: sh
 
-    pip install lightgbm --config-settings=cmake.define.USE_OPENMP=OFF
+    pip install lightgbm --no-binary lightgbm --config-settings=cmake.define.USE_OPENMP=OFF
 
 All requirements, except the **OpenMP** requirement, from `Build from Sources section <#build-from-sources>`__ apply for this installation option as well.
 
 It is **strongly not recommended** to use this version of LightGBM!
 
+|
+
 Build MPI Version
 ~~~~~~~~~~~~~~~~~
 
 .. code:: sh
 
-    pip install lightgbm --config-settings=cmake.define.USE_MPI=ON
+    pip install lightgbm --no-binary lightgbm --config-settings=cmake.define.USE_MPI=ON
 
 All requirements from `Build from Sources section <#build-from-sources>`__ apply for this installation option as well.
 
@@ -104,27 +137,29 @@ For **Windows** users, compilation with **MinGW-w64** is not supported.
 
 **MPI** libraries are needed: details for installation can be found in `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-mpi-version>`__.
 
+|
+
 Build GPU Version
 ~~~~~~~~~~~~~~~~~
 
 .. code:: sh
 
-    pip install lightgbm --config-settings=cmake.define.USE_GPU=ON
+    pip install lightgbm --no-binary lightgbm --config-settings=cmake.define.USE_GPU=ON
 
 All requirements from `Build from Sources section <#build-from-sources>`__ apply for this installation option as well.
 
-**Boost** and **OpenCL** are needed: details for installation can be found in `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-gpu-version>`__. Almost always you also need to pass ``OpenCL_INCLUDE_DIR``, ``OpenCL_LIBRARY`` options for **Linux** and ``BOOST_ROOT``, ``BOOST_LIBRARYDIR`` options for **Windows** to **CMake** via ``pip`` options, like
+For **macOS** users, the GPU version is not supported.
+
+**Boost** and **OpenCL** are needed: details for installation can be found in `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-gpu-version>`__.
+Almost always you also need to pass ``OpenCL_INCLUDE_DIR``, ``OpenCL_LIBRARY`` options for **Linux** and ``BOOST_ROOT``, ``BOOST_LIBRARYDIR`` options for **Windows** to **CMake** via ``pip`` options, like
 
 .. code:: sh
 
-    pip install lightgbm \
-      --config-settings=cmake.define.USE_GPU=ON \
-      --config-settings=cmake.define.OpenCL_INCLUDE_DIR="/usr/local/cuda/include/" \
-      --config-settings=cmake.define.OpenCL_LIBRARY="/usr/local/cuda/lib64/libOpenCL.so"
+    pip install lightgbm --no-binary lightgbm --config-settings=cmake.define.USE_GPU=ON --config-settings=cmake.define.OpenCL_INCLUDE_DIR="/usr/local/cuda/include/" --config-settings=cmake.define.OpenCL_LIBRARY="/usr/local/cuda/lib64/libOpenCL.so"
 
 All available options that can be passed via ``cmake.define.{option}``.
 
-- Boost_ROOT
+- BOOST_ROOT
 
 - Boost_DIR
 
@@ -138,56 +173,70 @@ All available options that can be passed via ``cmake.define.{option}``.
 
 For more details see `FindBoost <https://cmake.org/cmake/help/latest/module/FindBoost.html>`__ and `FindOpenCL <https://cmake.org/cmake/help/latest/module/FindOpenCL.html>`__.
 
+Don't confuse with `CUDA version <#build-cuda-version>`__.
+To use the GPU version within Python, pass ``{"device": "gpu"}`` respectively in parameters.
+
+|
+
 Build CUDA Version
 ~~~~~~~~~~~~~~~~~~
 
 .. code:: sh
 
-    pip install lightgbm --config-settings=cmake.define.USE_CUDA=ON
+    pip install lightgbm --no-binary lightgbm --config-settings=cmake.define.USE_CUDA=ON
 
 All requirements from `Build from Sources section <#build-from-sources>`__ apply for this installation option as well.
 
+For **macOS** and **Windows** users, the CUDA version is not supported.
+
 **CUDA** library is needed: details for installation can be found in `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst#build-cuda-version>`__.
 
+Don't confuse with `GPU version <#build-gpu-version>`__.
 To use the CUDA version within Python, pass ``{"device": "cuda"}`` respectively in parameters.
 
+|
+
 Build with MinGW-w64 on Windows
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code:: sh
 
-    # in sh.exe, git bash, or other Unix-like shell
-    export CMAKE_GENERATOR='MinGW Makefiles'
-    pip install lightgbm --config-settings=cmake.define.CMAKE_SH=CMAKE_SH-NOTFOUND
+    pip install lightgbm --no-binary lightgbm --config-settings=cmake.define.CMAKE_SH=CMAKE_SH-NOTFOUND --config-settings=cmake.args="-GMinGW Makefiles"
 
 `MinGW-w64 <https://www.mingw-w64.org/>`_ should be installed first.
 
 It is recommended to use **Visual Studio** for its better multithreading efficiency in **Windows** for many-core systems
-(see `Question 4 <https://github.com/microsoft/LightGBM/blob/master/docs/FAQ.rst#4-i-am-using-windows-should-i-use-visual-studio-or-mingw-for-compiling-lightgbm>`__ and `Question 8 <https://github.com/microsoft/LightGBM/blob/master/docs/FAQ.rst#8-cpu-usage-is-low-like-10-in-windows-when-using-lightgbm-on-very-large-datasets-with-many-core-systems>`__).
+(see `Question 4 <https://github.com/microsoft/LightGBM/blob/master/docs/FAQ.rst#4-i-am-using-windows-should-i-use-visual-studio-or-mingw-for-compiling-lightgbm>`__
+and `Question 8 <https://github.com/microsoft/LightGBM/blob/master/docs/FAQ.rst#8-cpu-usage-is-low-like-10-in-windows-when-using-lightgbm-on-very-large-datasets-with-many-core-systems>`__).
+
+|
 
 Build 32-bit Version with 32-bit Python
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code:: sh
 
-    # in sh.exe, git bash, or other Unix-like shell
-    export CMAKE_GENERATOR='Visual Studio 17 2022'
-    export CMAKE_GENERATOR_PLATFORM='Win32'
-    pip install --no-binary lightgbm lightgbm
+    pip install lightgbm --no-binary lightgbm --config-settings=cmake.args="-AWin32"
+
+For **Windows** users, compilation with **MinGW-w64** is not supported.
 
-By default, installation in environment with 32-bit Python is prohibited. However, you can remove this prohibition on your own risk by passing ``bit32`` option.
+For **macOS** and **Linux** users, the 32-bit version is not supported.
 
 It is **strongly not recommended** to use this version of LightGBM!
 
+|
+
 Build with Time Costs Output
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code:: sh
 
-    pip install lightgbm --config-settings=cmake.define.USE_TIMETAG=ON
+    pip install lightgbm --no-binary lightgbm --config-settings=cmake.define.USE_TIMETAG=ON
 
 Use this option to make LightGBM output time costs for different internal routines, to investigate and benchmark its performance.
 
+|
+
 Install from `conda-forge channel <https://anaconda.org/conda-forge/lightgbm>`_
 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
@@ -197,77 +246,82 @@ Install from `conda-forge channel <https://anaconda.org/conda-forge/lightgbm>`_
 
     conda install -c conda-forge lightgbm
 
-These are precompiled packages that are fast to install.
-Use them instead of ``pip install`` if any of the following are true:
+These packages support **CPU**, **GPU** and **CUDA** versions out of the box.
 
-* you prefer to use ``conda`` to manage software environments
-* you want to use GPU-accelerated LightGBM
-* you are using a platform that ``lightgbm`` does not provide wheels for (like PowerPC)
+**GPU**-enabled version is available only for **Windows** and **Linux** currently.
 
-For ``lightgbm>=4.4.0``, if you are on a system where CUDA is installed, ``conda install`` will automatically
-select a CUDA-enabled build of ``lightgbm``.
+**CUDA**-enabled version (since ``lightgbm>=4.4.0``) is available only for **Linux** currently and will be automatically selected if you are on a system where CUDA is installed.
 
-.. code:: sh
-
-    conda install -c conda-forge 'lightgbm>=4.4.0'
+|
 
 Install from GitHub
 '''''''''''''''''''
 
 All requirements from `Build from Sources section <#build-from-sources>`__ apply for this installation option as well.
 
-For **Windows** users, if you get any errors during installation and there is the warning ``WARNING:LightGBM:Compilation with MSBuild from existing solution file failed.`` in the log.
-
 .. code:: sh
 
     git clone --recursive https://github.com/microsoft/LightGBM.git
+    cd LightGBM
     # export CXX=g++-14 CC=gcc-14  # macOS users, if you decided to compile with gcc, don't forget to specify compilers
     sh ./build-python.sh install
 
 Note: ``sudo`` (or administrator rights in **Windows**) may be needed to perform the command.
+Run ``sh ./build-python.sh install --user`` to install into user-specific instead of global site-packages directory.
 
-Run ``sh ./build-python.sh install --nomp`` to disable **OpenMP** support. All requirements from `Build Threadless Version section <#build-threadless-version>`__ apply for this installation option as well.
+Run ``sh ./build-python.sh install --no-isolation`` to assume all build and install dependencies are already installed, don't go to the internet to get them.
 
-Run ``sh ./build-python.sh install --mpi`` to enable **MPI** support. All requirements from `Build MPI Version section <#build-mpi-version>`__ apply for this installation option as well.
+|
 
-Run ``sh ./build-python.sh install --mingw``, if you want to use **MinGW-w64** on **Windows** instead of **Visual Studio**. All requirements from `Build with MinGW-w64 on Windows section <#build-with-mingw-w64-on-windows>`__ apply for this installation option as well.
+Run ``sh ./build-python.sh install --nomp`` to disable **OpenMP** support.
+All requirements from `Build Threadless Version section <#build-threadless-version>`__ apply for this installation option as well.
 
-Run ``sh ./build-python.sh install --gpu`` to enable GPU support. All requirements from `Build GPU Version section <#build-gpu-version>`__ apply for this installation option as well. To pass additional options to **CMake** use the following syntax: ``sh ./build-python.sh install --gpu --opencl-include-dir="/usr/local/cuda/include/"``, see `Build GPU Version section <#build-gpu-version>`__ for the complete list of them.
+Run ``sh ./build-python.sh install --mpi`` to enable **MPI** support.
+All requirements from `Build MPI Version section <#build-mpi-version>`__ apply for this installation option as well.
 
-Run ``sh ./build-python.sh install --cuda`` to enable CUDA support. All requirements from `Build CUDA Version section <#build-cuda-version>`__ apply for this installation option as well.
+Run ``sh ./build-python.sh install --gpu`` to enable GPU support.
+All requirements from `Build GPU Version section <#build-gpu-version>`__ apply for this installation option as well.
+To pass additional options to **CMake** use the following syntax: ``sh ./build-python.sh install --gpu --opencl-include-dir="/usr/local/cuda/include/"``,
+see `Build GPU Version section <#build-gpu-version>`__ for the complete list of them.
 
-Run ``sh ./build-python.sh install --bit32``, if you want to use 32-bit version. All requirements from `Build 32-bit Version with 32-bit Python section <#build-32-bit-version-with-32-bit-python>`__ apply for this installation option as well.
+Run ``sh ./build-python.sh install --cuda`` to enable CUDA support.
+All requirements from `Build CUDA Version section <#build-cuda-version>`__ apply for this installation option as well.
 
-Run ``sh ./build-python.sh install --time-costs``, if you want to output time costs for different internal routines. All requirements from `Build with Time Costs Output section <#build-with-time-costs-output>`__ apply for this installation option as well.
+Run ``sh ./build-python.sh install --mingw``, if you want to use **MinGW-w64** on **Windows** instead of **Visual Studio**.
+All requirements from `Build with MinGW-w64 on Windows section <#build-with-mingw-w64-on-windows>`__ apply for this installation option as well.
 
-If you get any errors during installation or due to any other reasons, you may want to build dynamic library from sources by any method you prefer (see `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst>`__) and then just run ``sh ./build-python.sh install --precompile``.
+Run ``sh ./build-python.sh install --bit32``, if you want to use 32-bit version.
+All requirements from `Build 32-bit Version with 32-bit Python section <#build-32-bit-version-with-32-bit-python>`__ apply for this installation option as well.
 
-Build Wheel File
-****************
+Run ``sh ./build-python.sh install --time-costs``, if you want to output time costs for different internal routines.
+All requirements from `Build with Time Costs Output section <#build-with-time-costs-output>`__ apply for this installation option as well.
 
-You can use ``sh ./build-python.sh bdist_wheel`` to build a wheel file but not install it.
+|
 
-That script requires some dependencies like ``build``, ``scikit-build-core``, and ``wheel``.
-In environments with restricted or no internet access, install those tools and then pass ``--no-isolation``.
+If you get any errors during installation or due to any other reasons,
+you may want to build dynamic library from sources by any method you prefer
+(see `Installation Guide <https://github.com/microsoft/LightGBM/blob/master/docs/Installation-Guide.rst>`__).
+For example, you can use ``MSBuild`` tool and `solution file <https://github.com/microsoft/LightGBM/blob/master/windows/LightGBM.sln>`__ from the repo.
 
 .. code:: sh
 
-  sh ./build-python.sh bdist_wheel --no-isolation
+  MSBuild.exe windows/LightGBM.sln /p:Configuration=DLL /p:Platform=x64 /p:PlatformToolset=v143
 
-Build With MSBuild
-******************
+After compiling dynamic library just run ``sh ./build-python.sh install --precompile`` to install the Python-package using that library.
 
-To use ``MSBuild`` (Windows-only), first build ``lib_lightgbm.dll`` by running the following from the root of the repo.
+|
 
-.. code:: sh
+Build Wheel File
+****************
 
-  MSBuild.exe windows/LightGBM.sln /p:Configuration=DLL /p:Platform=x64 /p:PlatformToolset=v143
+You can run ``sh ./build-python.sh bdist_wheel`` to build a wheel file but not install it.
 
-Then install the Python-package using that library.
+That script requires some dependencies like ``build``, ``scikit-build-core``, and ``wheel``.
+In environments with restricted or no internet access, install those tools and then pass ``--no-isolation``.
 
 .. code:: sh
 
-  sh ./build-python.sh install --precompile
+  sh ./build-python.sh bdist_wheel --no-isolation
 
 Troubleshooting
 ---------------

python-package/pyproject.toml

@@ -45,6 +45,10 @@ dask = [
 pandas = [
     "pandas>=0.24.0"
 ]
+plotting = [
+    "graphviz",
+    "matplotlib"
+]
 scikit-learn = [
     "scikit-learn>=0.24.2"
 ]
@@ -63,15 +67,9 @@ build-backend = "scikit_build_core.build"
 
 # based on https://github.com/scikit-build/scikit-build-core#configuration
 [tool.scikit-build]
-
-cmake.version = "CMakeLists.txt"
 ninja.version = ">=1.11"
 ninja.make-fallback = true
-cmake.args = [
-    "-D__BUILD_FOR_PYTHON:BOOL=ON"
-]
 build.verbose = false
-cmake.build-type = "Release"
 build.targets = ["_lightgbm"]
 install.strip = true
 logging.level = "INFO"
@@ -81,6 +79,13 @@ experimental = false
 strict-config = false
 minimum-version = "build-system.requires"
 
+[tool.scikit-build.cmake]
+version = "CMakeLists.txt"
+build-type = "Release"
+
+[tool.scikit-build.cmake.define]
+__BUILD_FOR_PYTHON = "ON"
+
 # end:build-system
 
 [tool.mypy]