From 8d12dca13677190f37de58621cc6d65243c7fc76 Mon Sep 17 00:00:00 2001 From: James Lamb Date: Wed, 27 Jul 2022 23:23:44 -0500 Subject: [PATCH] [ci] make check-docs job compatible with rstcheck 6.x (#5388) --- .ci/test.sh | 16 ++++-- docs/Experiments.rst | 10 ++-- docs/GPU-Windows.rst | 32 +++++------ docs/Installation-Guide.rst | 98 ++++++++++++++++---------------- docs/Parallel-Learning-Guide.rst | 12 ++-- 5 files changed, 87 insertions(+), 81 deletions(-) diff --git a/.ci/test.sh b/.ci/test.sh index e549416d5..5bebe61cb 100755 --- a/.ci/test.sh +++ b/.ci/test.sh @@ -44,12 +44,12 @@ if [[ $TASK == "check-docs" ]] || [[ $TASK == "check-links" ]]; then -y \ -n $CONDA_ENV \ doxygen \ - rstcheck || exit -1 + 'rstcheck>=6.0.0' || exit -1 # check reStructuredText formatting cd $BUILD_DIRECTORY/python-package - rstcheck --report warning $(find . -type f -name "*.rst") || exit -1 + rstcheck --report-level warning $(find . -type f -name "*.rst") || exit -1 cd $BUILD_DIRECTORY/docs - rstcheck --report warning --ignore-directives=autoclass,autofunction,doxygenfile $(find . -type f -name "*.rst") || exit -1 + rstcheck --report-level warning --ignore-directives=autoclass,autofunction,autosummary,doxygenfile $(find . -type f -name "*.rst") || exit -1 # build docs make html || exit -1 if [[ $TASK == "check-links" ]]; then @@ -118,10 +118,16 @@ if [[ $TASK == "swig" ]]; then exit 0 fi +# temporary fix for https://github.com/microsoft/LightGBM/issues/5390 +if [[ $PYTHON_VERSION == "3.7" ]]; then + DASK_DEPENDENCIES="dask distributed" +else + DASK_DEPENDENCIES="dask=2022.7.0 distributed=2022.7.0" +fi + conda install -q -y -n $CONDA_ENV \ cloudpickle \ - dask \ - distributed \ + ${DASK_DEPENDENCIES} \ joblib \ matplotlib \ numpy \ diff --git a/docs/Experiments.rst b/docs/Experiments.rst index ebaa41340..ede19cf3a 100644 --- a/docs/Experiments.rst +++ b/docs/Experiments.rst @@ -57,7 +57,7 @@ We set up total 3 settings for experiments. The parameters of these settings are 1. xgboost: - .. code:: + .. code:: text eta = 0.1 max_depth = 8 @@ -68,7 +68,7 @@ We set up total 3 settings for experiments. The parameters of these settings are 2. xgboost\_hist (using histogram based algorithm): - .. code:: + .. code:: text eta = 0.1 num_round = 500 @@ -81,7 +81,7 @@ We set up total 3 settings for experiments. The parameters of these settings are 3. LightGBM: - .. code:: + .. code:: text learning_rate = 0.1 num_leaves = 255 @@ -102,7 +102,7 @@ Result Speed ''''' -We compared speed using only the training task without any test or metric output. We didn't count the time for IO. +We compared speed using only the training task without any test or metric output. We didn't count the time for IO. For the ranking tasks, since XGBoost and LightGBM implement different ranking objective functions, we used ``regression`` objective for speed benchmark, for the fair comparison. The following table is the comparison of time cost: @@ -212,7 +212,7 @@ We ran our experiments on 16 Windows servers with the following specifications: Settings ^^^^^^^^ -.. code:: +.. code:: text learning_rate = 0.1 num_leaves = 255 diff --git a/docs/GPU-Windows.rst b/docs/GPU-Windows.rst index ccc1aab7c..e92714fab 100644 --- a/docs/GPU-Windows.rst +++ b/docs/GPU-Windows.rst @@ -112,7 +112,7 @@ You may choose a version other than the most recent one if you need a previous M Then, add to your PATH the following (to adjust to your MinGW version): -:: +.. code:: text C:\Program Files\mingw-w64\x86_64-5.3.0-posix-seh-rt_v4-rev0\mingw64\bin @@ -181,7 +181,7 @@ We can now start downloading and compiling the required Boost libraries: - Open a command prompt, and run - .. code:: + .. code:: console cd C:\boost\boost_1_63_0\tools\build bootstrap.bat gcc @@ -192,14 +192,14 @@ To build the Boost libraries, you have two choices for command prompt: - If you have only one single core, you can use the default - .. code:: + .. code:: console b2 install --build_dir="C:\boost\boost-build" --prefix="C:\boost\boost-build" toolset=gcc --with=filesystem,system threading=multi --layout=system release - If you want to do a multithreaded library building (faster), add ``-j N`` by replacing N by the number of cores/threads you have. For instance, for 2 cores, you would do - .. code:: + .. code:: console b2 install --build_dir="C:\boost\boost-build" --prefix="C:\boost\boost-build" toolset=gcc --with=filesystem,system threading=multi --layout=system release -j 2 @@ -207,7 +207,7 @@ Ignore all the errors popping up, like Python, etc., they do not matter for us. Your folder should look like this at the end (not fully detailed): -:: +.. code:: text - C |--- boost @@ -253,7 +253,7 @@ Installing Git for Windows is straightforward, use the following `link`_. Now, we can fetch LightGBM repository for GitHub. Run Git Bash and the following command: -:: +.. code:: console cd C:/ mkdir github_repos @@ -319,7 +319,7 @@ Installing CMake requires one download first and then a lot of configuration for :target: ./_static/images/screenshot-configured-lightgbm.png :alt: A screenshot of the C Make window after clicking on the configure button. - :: + .. code:: text Looking for CL_VERSION_2_0 Looking for CL_VERSION_2_0 - found @@ -333,7 +333,7 @@ Installing CMake requires one download first and then a lot of configuration for - Click ``Generate`` to get the following message: - :: + .. code:: text Generating done @@ -355,19 +355,19 @@ You can do everything in the Git Bash console you left open: - If you closed Git Bash console previously, run this to get back to the build folder: - :: + .. code:: console cd C:/github_repos/LightGBM/build - If you did not close the Git Bash console previously, run this to get to the build folder: - :: + .. code:: console cd LightGBM/build - Setup MinGW as ``make`` using - :: + .. code:: console alias make='mingw32-make' @@ -387,7 +387,7 @@ Testing in CLI You can now test LightGBM directly in CLI in a **command prompt** (not Git Bash): -:: +.. code:: console cd C:/github_repos/LightGBM/examples/binary_classification "../../lightgbm.exe" config=train.conf data=binary.train valid=binary.test objective=binary device=gpu @@ -448,7 +448,7 @@ And then, follow the regular LightGBM CLI installation from there. Once you have installed LightGBM CLI, assuming your LightGBM is in ``C:\github_repos\LightGBM``, open a command prompt and run the following: -:: +.. code:: console gdb --args "../../lightgbm.exe" config=train.conf data=binary.train valid=binary.test objective=binary device=gpu @@ -461,7 +461,7 @@ Type ``run`` and press the Enter key. You will probably get something similar to this: -:: +.. code:: text [LightGBM] [Info] This is the GPU trainer!! [LightGBM] [Info] Total Bins 6143 @@ -476,7 +476,7 @@ You will probably get something similar to this: There, write ``backtrace`` and press the Enter key as many times as gdb requests two choices: -:: +.. code:: text Program received signal SIGSEGV, Segmentation fault. 0x00007ffbb37c11f1 in strlen () from C:\Windows\system32\msvcrt.dll @@ -511,7 +511,7 @@ There, write ``backtrace`` and press the Enter key as many times as gdb requests Right-click the command prompt, click "Mark", and select all the text from the first line (with the command prompt containing gdb) to the last line printed, containing all the log, such as: -:: +.. code:: text C:\LightGBM\examples\binary_classification>gdb --args "../../lightgbm.exe" config=train.conf data=binary.train valid=binary.test objective=binary device=gpu GNU gdb (GDB) 7.10.1 diff --git a/docs/Installation-Guide.rst b/docs/Installation-Guide.rst index 596daf80d..8cb46b4e5 100644 --- a/docs/Installation-Guide.rst +++ b/docs/Installation-Guide.rst @@ -73,7 +73,7 @@ From Command Line 2. Run the following commands: - .. code:: + .. code:: console git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -91,7 +91,7 @@ MinGW-w64 2. Run the following commands: - .. code:: + .. code:: console git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -118,7 +118,7 @@ On Linux LightGBM can be built using **CMake** and **gcc** or **Clang**. 2. Run the following commands: - .. code:: + .. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -146,7 +146,7 @@ Only **Apple Clang** version 8.1 or higher is supported. Install Using ``Homebrew`` ************************** -.. code:: +.. code:: sh brew install lightgbm @@ -155,19 +155,19 @@ Build from GitHub 1. Install `CMake`_ (3.16 or higher): - .. code:: + .. code:: sh brew install cmake 2. Install **OpenMP**: - .. code:: + .. code:: sh brew install libomp 3. Run the following commands: - .. code:: + .. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -181,19 +181,19 @@ gcc 1. Install `CMake`_ (3.2 or higher): - .. code:: + .. code:: sh brew install cmake 2. Install **gcc**: - .. code:: + .. code:: sh brew install gcc 3. Run the following commands: - .. code:: + .. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -256,7 +256,7 @@ From Command Line 2. Run the following commands: - .. code:: + .. code:: console git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -274,7 +274,7 @@ MinGW-w64 2. Run the following commands: - .. code:: + .. code:: console git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -296,7 +296,7 @@ On Linux a version of LightGBM without OpenMP support can be built using **CMake 2. Run the following commands: - .. code:: + .. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -319,13 +319,13 @@ Only **Apple Clang** version 8.1 or higher is supported. 1. Install `CMake`_ (3.16 or higher): - .. code:: + .. code:: sh brew install cmake 2. Run the following commands: - .. code:: + .. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -339,19 +339,19 @@ gcc 1. Install `CMake`_ (3.2 or higher): - .. code:: + .. code:: sh brew install cmake 2. Install **gcc**: - .. code:: + .. code:: sh brew install gcc 3. Run the following commands: - .. code:: + .. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -404,7 +404,7 @@ From Command Line 3. Run the following commands: - .. code:: + .. code:: console git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -428,7 +428,7 @@ On Linux an MPI version of LightGBM can be built using **Open MPI**, **CMake** a 3. Run the following commands: - .. code:: + .. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -453,25 +453,25 @@ Only **Apple Clang** version 8.1 or higher is supported. 1. Install `CMake`_ (3.16 or higher): - .. code:: + .. code:: sh brew install cmake 2. Install **OpenMP**: - .. code:: + .. code:: sh brew install libomp 3. Install **Open MPI**: - .. code:: + .. code:: sh brew install open-mpi 4. Run the following commands: - .. code:: + .. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -485,25 +485,25 @@ gcc 1. Install `CMake`_ (3.2 or higher): - .. code:: + .. code:: sh brew install cmake 2. Install **gcc**: - .. code:: + .. code:: sh brew install gcc 3. Install **Open MPI**: - .. code:: + .. code:: sh brew install open-mpi 4. Run the following commands: - .. code:: + .. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -537,7 +537,7 @@ The following dependencies should be installed before compilation: To build LightGBM GPU version, run the following commands: -.. code:: +.. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -576,7 +576,7 @@ Following procedure is for the **MSVC** (Microsoft Visual C++) build. 3. Install `Boost Binaries`_. **Note**: Match your Visual C++ version: - + Visual Studio 2015 -> ``msvc-14.0-64.exe``, Visual Studio 2017 -> ``msvc-14.1-64.exe``, @@ -587,7 +587,7 @@ Following procedure is for the **MSVC** (Microsoft Visual C++) build. 4. Run the following commands: - .. code:: + .. code:: console git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -627,7 +627,7 @@ The following dependencies should be installed before compilation: To build LightGBM CUDA version, run the following commands: -.. code:: +.. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -656,7 +656,7 @@ On Linux a HDFS version of LightGBM can be built using **CMake** and **gcc**. 2. Run the following commands: - .. code:: + .. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -694,7 +694,7 @@ VS Build Tools 3. Run the following commands: - .. code:: + .. code:: console git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -714,7 +714,7 @@ MinGW-w64 3. Run the following commands: - .. code:: + .. code:: console git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -741,7 +741,7 @@ On Linux a Java wrapper of LightGBM can be built using **Java**, **SWIG**, **CMa 2. Run the following commands: - .. code:: + .. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -769,19 +769,19 @@ Only **Apple Clang** version 8.1 or higher is supported. 1. Install `CMake`_ (3.16 or higher): - .. code:: + .. code:: sh brew install cmake 2. Install **OpenMP**: - .. code:: + .. code:: sh brew install libomp 3. Run the following commands: - .. code:: + .. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -795,19 +795,19 @@ gcc 1. Install `CMake`_ (3.2 or higher): - .. code:: + .. code:: sh brew install cmake 2. Install **gcc**: - .. code:: + .. code:: sh brew install gcc 3. Run the following commands: - .. code:: + .. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -831,7 +831,7 @@ On Windows, C++ unit tests of LightGBM can be built using **CMake** and **VS Bui 2. Run the following commands: - .. code:: + .. code:: console git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -851,7 +851,7 @@ On Linux a C++ unit tests of LightGBM can be built using **CMake** and **gcc** o 2. Run the following commands: - .. code:: + .. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -874,13 +874,13 @@ Only **Apple Clang** version 8.1 or higher is supported. 1. Install `CMake`_ (3.16 or higher): - .. code:: + .. code:: sh brew install cmake 2. Run the following commands: - .. code:: + .. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM @@ -894,19 +894,19 @@ gcc 1. Install `CMake`_ (3.2 or higher): - .. code:: + .. code:: sh brew install cmake 2. Install **gcc**: - .. code:: + .. code:: sh brew install gcc 3. Run the following commands: - .. code:: + .. code:: sh git clone --recursive https://github.com/microsoft/LightGBM cd LightGBM diff --git a/docs/Parallel-Learning-Guide.rst b/docs/Parallel-Learning-Guide.rst index f220ebe7c..a5abb2479 100644 --- a/docs/Parallel-Learning-Guide.rst +++ b/docs/Parallel-Learning-Guide.rst @@ -166,7 +166,7 @@ LightGBM supports a parameter ``machines``, a comma-delimited string where each For example, consider the case where you are running one Dask worker process on each of the following IP addresses: -:: +.. code:: text 10.0.1.0 10.0.2.0 @@ -209,7 +209,7 @@ If you are only running one Dask worker process on each host, and if you can rel For example, consider the case where you are running one Dask worker process on each of the following IP addresses: -:: +.. code:: text 10.0.1.0 10.0.2.0 @@ -410,7 +410,7 @@ Socket Version It needs to collect IP of all machines that want to run distributed learning in and allocate one TCP port (assume 12345 here) for all machines, and change firewall rules to allow income of this port (12345). Then write these IP and ports in one file (assume ``mlist.txt``), like following: -.. code:: +.. code:: text machine1_ip 12345 machine2_ip 12345 @@ -421,7 +421,7 @@ MPI Version It needs to collect IP (or hostname) of all machines that want to run distributed learning in. Then write these IP in one file (assume ``mlist.txt``) like following: -.. code:: +.. code:: text machine1_ip machine2_ip @@ -471,13 +471,13 @@ MPI Version For Windows: - .. code:: + .. code:: console mpiexec.exe /machinefile mlist.txt lightgbm.exe config=your_config_file For Linux: - .. code:: + .. code:: console mpiexec --machinefile mlist.txt ./lightgbm config=your_config_file