From e8a68f2e22439c9f81a426308b0412dd46efa0a4 Mon Sep 17 00:00:00 2001 From: Nikita Titov Date: Mon, 7 Oct 2024 05:49:20 +0300 Subject: [PATCH] [docs] use consistent naming for R-package and Python-package across the repo (#6655) --- .ci/check-python-dists.sh | 4 ++-- .ci/test-python-oldest.sh | 2 +- .ci/test-r-package-windows.ps1 | 6 +++--- .ci/test-r-package.sh | 4 ++-- CMakeLists.txt | 10 +++++----- R-package/README.md | 20 ++++++++++---------- R-package/tests/testthat/test_basic.R | 4 ++-- R-package/tests/testthat/test_lgb.Booster.R | 6 +++--- R-package/vignettes/basic_walkthrough.Rmd | 2 +- build-cran-package.sh | 10 +++++----- build-python.sh | 8 ++++---- build_r.R | 2 +- cmake/modules/FindLibR.cmake | 2 +- docker/README.md | 12 ++++++------ docs/FAQ.rst | 10 +++++----- docs/Parallel-Learning-Guide.rst | 2 +- python-package/README.rst | 2 +- python-package/pyproject.toml | 2 +- tests/c_api_test/test_.py | 2 +- 19 files changed, 55 insertions(+), 55 deletions(-) diff --git a/.ci/check-python-dists.sh b/.ci/check-python-dists.sh index c9c4eb6d11b4..f753f85dd6c0 100644 --- a/.ci/check-python-dists.sh +++ b/.ci/check-python-dists.sh @@ -8,7 +8,7 @@ DIST_DIR=${1} METHOD=${METHOD:-""} TASK=${TASK:-""} -echo "checking Python package distributions in '${DIST_DIR}'" +echo "checking Python-package distributions in '${DIST_DIR}'" pip install \ -qq \ @@ -55,4 +55,4 @@ else echo "skipping pydistcheck (does not support Python 3.${PY_MINOR_VER})" fi -echo "done checking Python package distributions" +echo "done checking Python-package distributions" diff --git a/.ci/test-python-oldest.sh b/.ci/test-python-oldest.sh index c6de079351e3..002a1c95833c 100644 --- a/.ci/test-python-oldest.sh +++ b/.ci/test-python-oldest.sh @@ -30,7 +30,7 @@ pip freeze echo "" echo "checking that examples run without error" -# run a few examples to test that Python package minimally works +# run a few examples to test that Python-package minimally works echo "" echo "--- advanced_example.py ---" echo "" diff --git a/.ci/test-r-package-windows.ps1 b/.ci/test-r-package-windows.ps1 index 8b17156749ea..269695c51462 100644 --- a/.ci/test-r-package-windows.ps1 +++ b/.ci/test-r-package-windows.ps1 @@ -144,7 +144,7 @@ Write-Output "Installing dependencies" $packages = "c('data.table', 'jsonlite', 'knitr', 'markdown', 'Matrix', 'processx', 'R6', 'RhpcBLASctl', 'testthat'), dependencies = c('Imports', 'Depends', 'LinkingTo')" Run-R-Code-Redirect-Stderr "options(install.packages.check.source = 'no'); install.packages($packages, repos = '$env:CRAN_MIRROR', type = 'binary', lib = '$env:R_LIB_PATH', Ncpus = parallel::detectCores())" ; Check-Output $? -Write-Output "Building R package" +Write-Output "Building R-package" # R CMD check is not used for MSVC builds if ($env:COMPILER -ne "MSVC") { @@ -234,7 +234,7 @@ if ($checks_cnt -eq 0) { Check-Output $False } -# Checking that we actually got the expected compiler. The R package has some logic +# Checking that we actually got the expected compiler. The R-package has some logic # to fail back to MinGW if MSVC fails, but for CI builds we need to check that the correct # compiler was used. if ($env:R_BUILD_TYPE -eq "cmake") { @@ -303,4 +303,4 @@ if ($env:COMPILER -eq "MSVC") { Rscript.exe --vanilla "testthat.R" ; Check-Output $? } -Write-Output "No issues were found checking the R package" +Write-Output "No issues were found checking the R-package" diff --git a/.ci/test-r-package.sh b/.ci/test-r-package.sh index 5eba7669ad14..6618d5450db4 100755 --- a/.ci/test-r-package.sh +++ b/.ci/test-r-package.sh @@ -155,7 +155,7 @@ elif [[ $R_BUILD_TYPE == "cran" ]]; then git diff --name-only | wc -l ) if [[ ${num_files_changed} -gt 0 ]]; then - echo "'configure' in the R package has changed. Please recreate it and commit the changes." + echo "'configure' in the R-package has changed. Please recreate it and commit the changes." echo "Changed files:" git diff --compact-summary echo "See R-package/README.md for details on how to recreate this script." @@ -167,7 +167,7 @@ elif [[ $R_BUILD_TYPE == "cran" ]]; then ./build-cran-package.sh || exit 1 if [[ "${TASK}" == "r-rchk" ]]; then - echo "Checking R package with rchk" + echo "Checking R-package with rchk" mkdir -p packages cp ${PKG_TARBALL} packages RCHK_LOG_FILE="rchk-logs.txt" diff --git a/CMakeLists.txt b/CMakeLists.txt index 4df470844434..b2859a96d351 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -19,8 +19,8 @@ option(BUILD_CLI "Build the 'lightbgm' command-line interface in addition to lib option(BUILD_CPP_TEST "Build C++ tests with Google Test" OFF) option(BUILD_STATIC_LIB "Build static library" OFF) option(INSTALL_HEADERS "Install headers to CMAKE_INSTALL_PREFIX (e.g. '/usr/local/include')" ON) -option(__BUILD_FOR_PYTHON "Set to ON if building lib_lightgbm for use with the Python package" OFF) -option(__BUILD_FOR_R "Set to ON if building lib_lightgbm for use with the R package" OFF) +option(__BUILD_FOR_PYTHON "Set to ON if building lib_lightgbm for use with the Python-package" OFF) +option(__BUILD_FOR_R "Set to ON if building lib_lightgbm for use with the R-package" OFF) option(__INTEGRATE_OPENCL "Set to ON if building LightGBM with the OpenCL ICD Loader and its dependencies included" OFF) cmake_minimum_required(VERSION 3.28) @@ -60,9 +60,9 @@ if(__INTEGRATE_OPENCL) endif() if(__BUILD_FOR_PYTHON OR __BUILD_FOR_R OR USE_SWIG) - # the SWIG wrapper, the Python and R package don't require the CLI + # the SWIG wrapper, the Python and R packages don't require the CLI set(BUILD_CLI OFF) - # installing the SWIG wrapper, the R and Python package shouldn't place LightGBM's headers + # installing the SWIG wrapper, the R and Python packages shouldn't place LightGBM's headers # outside of where the package is installed set(INSTALL_HEADERS OFF) endif() @@ -497,7 +497,7 @@ endif() set(API_SOURCES "src/c_api.cpp") # Only build the R part of the library if building for -# use with the R package +# use with the R-package if(__BUILD_FOR_R) list(APPEND API_SOURCES "src/lightgbm_R.cpp") endif() diff --git a/R-package/README.md b/R-package/README.md index cde306a81654..f1821f5cc6be 100644 --- a/R-package/README.md +++ b/R-package/README.md @@ -112,7 +112,7 @@ NOTE: `Rtools42` and later take a very different approach to the compiler toolch #### Windows Toolchain Options -A "toolchain" refers to the collection of software used to build the library. The R package can be built with three different toolchains. +A "toolchain" refers to the collection of software used to build the library. The R-package can be built with three different toolchains. **Warning for Windows users**: it is recommended to use *Visual Studio* for its better multi-threading efficiency in Windows for many core systems. For very simple systems (dual core computers or worse), MinGW64 is recommended for maximum performance. If you do not know what to choose, it is recommended to use [Visual Studio](https://visualstudio.microsoft.com/downloads/), the default compiler. **Do not try using MinGW in Windows on many core systems. It may result in 10x slower results than Visual Studio.** @@ -221,7 +221,7 @@ CRAN does not prepare precompiled binaries for Linux, and as of this writing nei ### Installing from a Pre-compiled lib_lightgbm -Previous versions of LightGBM offered the ability to first compile the C++ library (`lib_lightgbm.{dll,dylib,so}`) and then build an R package that wraps it. +Previous versions of LightGBM offered the ability to first compile the C++ library (`lib_lightgbm.{dll,dylib,so}`) and then build an R-package that wraps it. As of version 3.0.0, this is no longer supported. If building from source is difficult for you, please [open an issue](https://github.com/microsoft/LightGBM/issues). @@ -241,11 +241,11 @@ Please visit [demo](https://github.com/microsoft/LightGBM/tree/master/R-package/ Testing ------- -The R package's unit tests are run automatically on every commit, via integrations like [GitHub Actions](https://github.com/microsoft/LightGBM/actions). Adding new tests in `R-package/tests/testthat` is a valuable way to improve the reliability of the R package. +The R-package's unit tests are run automatically on every commit, via integrations like [GitHub Actions](https://github.com/microsoft/LightGBM/actions). Adding new tests in `R-package/tests/testthat` is a valuable way to improve the reliability of the R-package. ### Running the Tests -While developing the R package, run the code below to run the unit tests. +While developing the R-package, run the code below to run the unit tests. ```shell sh build-cran-package.sh \ @@ -268,7 +268,7 @@ Rscript testthat.R When adding tests, you may want to use test coverage to identify untested areas and to check if the tests you've added are covering all branches of the intended code. -The example below shows how to generate code coverage for the R package on a macOS or Linux setup. To adjust for your environment, refer to [the customization step described above](#custom-installation-linux-mac). +The example below shows how to generate code coverage for the R-package on a macOS or Linux setup. To adjust for your environment, refer to [the customization step described above](#custom-installation-linux-mac). ```shell # Install @@ -287,7 +287,7 @@ Rscript -e " \ Updating Documentation ---------------------- -The R package uses [`{roxygen2}`](https://CRAN.R-project.org/package=roxygen2) to generate its documentation. +The R-package uses [`{roxygen2}`](https://CRAN.R-project.org/package=roxygen2) to generate its documentation. The generated `DESCRIPTION`, `NAMESPACE`, and `man/` files are checked into source control. To regenerate those files, run the following. @@ -310,9 +310,9 @@ Rscript \ Preparing a CRAN Package ------------------------ -This section is primarily for maintainers, but may help users and contributors to understand the structure of the R package. +This section is primarily for maintainers, but may help users and contributors to understand the structure of the R-package. -Most of `LightGBM` uses `CMake` to handle tasks like setting compiler and linker flags, including header file locations, and linking to other libraries. Because CRAN packages typically do not assume the presence of `CMake`, the R package uses an alternative method that is in the CRAN-supported toolchain for building R packages with C++ code: `Autoconf`. +Most of `LightGBM` uses `CMake` to handle tasks like setting compiler and linker flags, including header file locations, and linking to other libraries. Because CRAN packages typically do not assume the presence of `CMake`, the R-package uses an alternative method that is in the CRAN-supported toolchain for building R packages with C++ code: `Autoconf`. For more information on this approach, see ["Writing R Extensions"](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#Configure-and-cleanup). @@ -344,7 +344,7 @@ R CMD install lightgbm_*.tar.gz ### Changing the CRAN Package -A lot of details are handled automatically by `R CMD build` and `R CMD install`, so it can be difficult to understand how the files in the R package are related to each other. An extensive treatment of those details is available in ["Writing R Extensions"](https://cran.r-project.org/doc/manuals/r-release/R-exts.html). +A lot of details are handled automatically by `R CMD build` and `R CMD install`, so it can be difficult to understand how the files in the R-package are related to each other. An extensive treatment of those details is available in ["Writing R Extensions"](https://cran.r-project.org/doc/manuals/r-release/R-exts.html). This section briefly explains the key files for building a CRAN package. To update the package, edit the files relevant to your change and re-run the steps in [Build a CRAN Package](#build-a-cran-package). @@ -488,4 +488,4 @@ These tests can also be triggered on any pull request by leaving a comment in a Known Issues ------------ -For information about known issues with the R package, see the [R-package section of LightGBM's main FAQ page](https://lightgbm.readthedocs.io/en/latest/FAQ.html#r-package). +For information about known issues with the R-package, see the [R-package section of LightGBM's main FAQ page](https://lightgbm.readthedocs.io/en/latest/FAQ.html#r-package). diff --git a/R-package/tests/testthat/test_basic.R b/R-package/tests/testthat/test_basic.R index ed477a42c00b..c734816b4038 100644 --- a/R-package/tests/testthat/test_basic.R +++ b/R-package/tests/testthat/test_basic.R @@ -634,7 +634,7 @@ test_that("lgb.cv() prefers objective in params to keyword argument", { for (bst_list in cv_bst$boosters) { bst <- bst_list[["booster"]] expect_equal(bst$params$objective, "regression_l1") - # NOTE: using save_model_to_string() since that is the simplest public API in the R package + # NOTE: using save_model_to_string() since that is the simplest public API in the R-package # allowing access to the "objective" attribute of the Booster object on the C++ side model_txt_lines <- strsplit( x = bst$save_model_to_string() @@ -807,7 +807,7 @@ test_that("lgb.train() prefers objective in params to keyword argument", { , obj = "regression_l2" ) expect_equal(bst$params$objective, "regression_l1") - # NOTE: using save_model_to_string() since that is the simplest public API in the R package + # NOTE: using save_model_to_string() since that is the simplest public API in the R-package # allowing access to the "objective" attribute of the Booster object on the C++ side model_txt_lines <- strsplit( x = bst$save_model_to_string() diff --git a/R-package/tests/testthat/test_lgb.Booster.R b/R-package/tests/testthat/test_lgb.Booster.R index 80cf7775813d..9197fd7226af 100644 --- a/R-package/tests/testthat/test_lgb.Booster.R +++ b/R-package/tests/testthat/test_lgb.Booster.R @@ -1111,7 +1111,7 @@ test_that("all parameters are stored correctly with save_model_to_string()", { ) all_param_entries <- c(non_default_param_entries, default_param_entries) - # parameters should match what was passed from the R package + # parameters should match what was passed from the R-package model_str <- bst$save_model_to_string() params_in_file <- .params_from_model_string(model_str = model_str) .expect_in(all_param_entries, params_in_file) @@ -1176,7 +1176,7 @@ test_that("early_stopping, num_iterations are stored correctly in model string e model_str <- bst$save_model_to_string() params_in_file <- .params_from_model_string(model_str = model_str) - # parameters should match what was passed from the R package, and the "main" (non-alias) + # parameters should match what was passed from the R-package, and the "main" (non-alias) # params values in `params` should be preferred to keyword argumentts or aliases expect_equal(sum(startsWith(params_in_file, "[num_iterations:")), 1L) expect_equal(sum(params_in_file == sprintf("[num_iterations: %s]", num_iterations)), 1L) @@ -1406,7 +1406,7 @@ test_that("lgb.cv() correctly handles passing through params to the model file", model_str <- bst[["booster"]]$save_model_to_string() params_in_file <- .params_from_model_string(model_str = model_str) - # parameters should match what was passed from the R package, and the "main" (non-alias) + # parameters should match what was passed from the R-package, and the "main" (non-alias) # params values in `params` should be preferred to keyword argumentts or aliases expect_equal(sum(startsWith(params_in_file, "[num_iterations:")), 1L) expect_equal(sum(params_in_file == sprintf("[num_iterations: %s]", num_iterations)), 1L) diff --git a/R-package/vignettes/basic_walkthrough.Rmd b/R-package/vignettes/basic_walkthrough.Rmd index 01e2410d501e..f9f4720c408f 100644 --- a/R-package/vignettes/basic_walkthrough.Rmd +++ b/R-package/vignettes/basic_walkthrough.Rmd @@ -54,7 +54,7 @@ table(bank$y) ## Training the model -The R package of LightGBM offers two functions to train a model: +The R-package of LightGBM offers two functions to train a model: - `lgb.train()`: This is the main training logic. It offers full flexibility but requires a `Dataset` object created by the `lgb.Dataset()` function. - `lightgbm()`: Simpler, but less flexible. Data can be passed without having to bother with `lgb.Dataset()`. diff --git a/build-cran-package.sh b/build-cran-package.sh index 90df29247b15..25965b42d7d7 100755 --- a/build-cran-package.sh +++ b/build-cran-package.sh @@ -1,13 +1,13 @@ #!/bin/sh # [description] -# Prepare a source distribution of the R package +# Prepare a source distribution of the R-package # to be submitted to CRAN. # # [arguments] # # --r-executable Customize the R executable used by `R CMD build`. -# Useful if building the R package in an environment with +# Useful if building the R-package in an environment with # non-standard builds of R, such as those provided in # https://github.com/wch/r-debug. # @@ -83,7 +83,7 @@ cp \ external_libs/fmt/include/fmt/*.h \ "${TEMP_R_DIR}/src/include/LightGBM/utils/fmt" -# including only specific files from Eigen, to keep the R package +# including only specific files from Eigen, to keep the R-package # small and avoid redistributing code with licenses incompatible with # LightGBM's license EIGEN_R_DIR="${TEMP_R_DIR}/src/include/Eigen" @@ -116,7 +116,7 @@ cd "${TEMP_R_DIR}" rm recreate-configure.sh # files only used by the lightgbm CLI aren't needed for - # the R package + # the R-package rm src/application/application.cpp rm src/include/LightGBM/application.h rm src/main.cpp @@ -223,4 +223,4 @@ else lightgbm_r fi -echo "Done building R package" +echo "Done building R-package" diff --git a/build-python.sh b/build-python.sh index de71c1f6a981..ee92380126d4 100755 --- a/build-python.sh +++ b/build-python.sh @@ -3,7 +3,7 @@ # [description] # # Prepare a source distribution (sdist) or built distribution (wheel) -# of the Python package, and optionally install it. +# of the Python-package, and optionally install it. # # [usage] # @@ -13,10 +13,10 @@ # # build wheel and put it in dist/ # sh ./build-python.sh bdist_wheel [OPTIONS] # -# # compile lib_lightgbm and install the Python package wrapping it +# # compile lib_lightgbm and install the Python-package wrapping it # sh ./build-python.sh install [OPTIONS] # -# # install the Python package using a pre-compiled lib_lightgbm +# # install the Python-package using a pre-compiled lib_lightgbm # # (assumes lib_lightgbm.{dll,so} is located at the root of the repo) # sh ./build-python.sh install --precompile # @@ -184,7 +184,7 @@ done pip install --prefer-binary 'build>=0.10.0' # create a new directory that just contains the files needed -# to build the Python package +# to build the Python-package create_isolated_source_dir() { rm -rf \ ./lightgbm-python \ diff --git a/build_r.R b/build_r.R index c2703778a7dd..1d824d60bbba 100644 --- a/build_r.R +++ b/build_r.R @@ -321,7 +321,7 @@ for (submodule in list.dirs( , recursive = FALSE )) { # compute/ is a submodule with boost, only needed if - # building the R package with GPU support; + # building the R-package with GPU support; # eigen/ has a special treatment due to licensing aspects if ((submodule == "compute" && !USING_GPU) || submodule == "eigen") { next diff --git a/cmake/modules/FindLibR.cmake b/cmake/modules/FindLibR.cmake index 8af0b5ac4179..f40a8cc5db83 100644 --- a/cmake/modules/FindLibR.cmake +++ b/cmake/modules/FindLibR.cmake @@ -24,7 +24,7 @@ if(NOT R_ARCH) endif() if(NOT ("${R_ARCH}" STREQUAL "x64")) - message(FATAL_ERROR "LightGBM's R package currently only supports 64-bit operating systems") + message(FATAL_ERROR "LightGBM's R-package currently only supports 64-bit operating systems") endif() # Creates R.lib and R.def in the build directory for linking with MSVC diff --git a/docker/README.md b/docker/README.md index 7e9e3276dd33..dfedc2f4e3f1 100644 --- a/docker/README.md +++ b/docker/README.md @@ -57,7 +57,7 @@ For more details on how to configure and use the LightGBM CLI, see https://light ## Running the Python-package Сontainer -Build an image with the LightGBM Python package installed. +Build an image with the LightGBM Python-package installed. ```shell mkdir lightgbm-docker @@ -69,8 +69,8 @@ docker build \ . ``` -Once that completes, the built image can be used to run LightGBM's Python package in a container. -Run the following to produce a model using the Python package. +Once that completes, the built image can be used to run LightGBM's Python-package in a container. +Run the following to produce a model using the Python-package. ```shell # get training data @@ -116,7 +116,7 @@ docker run \ ## Running the R-package Сontainer -Build an image with the LightGBM R package installed. +Build an image with the LightGBM R-package installed. ```shell mkdir lightgbm-docker @@ -129,8 +129,8 @@ docker build \ . ``` -Once that completes, the built image can be used to run LightGBM's R package in a container. -Run the following to produce a model using the R package. +Once that completes, the built image can be used to run LightGBM's R-package in a container. +Run the following to produce a model using the R-package. ```shell # get training data diff --git a/docs/FAQ.rst b/docs/FAQ.rst index 2cec5fee06f6..14c7f7dd7265 100644 --- a/docs/FAQ.rst +++ b/docs/FAQ.rst @@ -187,7 +187,7 @@ You can find LightGBM's logo in different file formats and resolutions `here `__. +In older versions of the R-package (prior to ``v3.3.0``), this could happen occasionally and the solution was to run ``lgb.unloader(wipe = TRUE)`` to remove all LightGBM-related objects. Some conversation about this could be found in `Microsoft/LightGBM#698 `__. -That is no longer necessary as of ``v3.3.0``, and function ``lgb.unloader()`` has since been removed from the R package. +That is no longer necessary as of ``v3.3.0``, and function ``lgb.unloader()`` has since been removed from the R-package. 2. I used ``setinfo()``, tried to print my ``lgb.Dataset``, and now the R console froze! ---------------------------------------------------------------------------------------- diff --git a/docs/Parallel-Learning-Guide.rst b/docs/Parallel-Learning-Guide.rst index cbc7b1012b98..a3d0a9d14f89 100644 --- a/docs/Parallel-Learning-Guide.rst +++ b/docs/Parallel-Learning-Guide.rst @@ -60,7 +60,7 @@ Dask .. versionadded:: 3.2.0 -LightGBM's Python package supports distributed learning via `Dask`_. This integration is maintained by LightGBM's maintainers. +LightGBM's Python-package supports distributed learning via `Dask`_. This integration is maintained by LightGBM's maintainers. .. warning:: diff --git a/python-package/README.rst b/python-package/README.rst index 2b37973bc052..0e007e5ee7ec 100644 --- a/python-package/README.rst +++ b/python-package/README.rst @@ -263,7 +263,7 @@ To use ``MSBuild`` (Windows-only), first build ``lib_lightgbm.dll`` by running t MSBuild.exe windows/LightGBM.sln /p:Configuration=DLL /p:Platform=x64 /p:PlatformToolset=v143 -Then install the Python package using that library. +Then install the Python-package using that library. .. code:: sh diff --git a/python-package/pyproject.toml b/python-package/pyproject.toml index 0d3d70feac66..2212347637e6 100644 --- a/python-package/pyproject.toml +++ b/python-package/pyproject.toml @@ -22,7 +22,7 @@ dependencies = [ "numpy>=1.17.0", "scipy" ] -description = "LightGBM Python Package" +description = "LightGBM Python-package" license = {file = "LICENSE"} maintainers = [ {name = "Yu Shi", email = "yushi@microsoft.com"} diff --git a/tests/c_api_test/test_.py b/tests/c_api_test/test_.py index fdaa4e941693..75530f7cb0c6 100644 --- a/tests/c_api_test/test_.py +++ b/tests/c_api_test/test_.py @@ -9,7 +9,7 @@ try: from lightgbm.basic import _LIB as LIB except ModuleNotFoundError: - print("Could not import lightgbm Python package, looking for lib_lightgbm at the repo root") + print("Could not import lightgbm Python-package, looking for lib_lightgbm at the repo root") if system() in ("Windows", "Microsoft"): lib_file = Path(__file__).absolute().parents[2] / "Release" / "lib_lightgbm.dll" else: