[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/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]