From 82828621d020299d1a1226b3131444298fe92278 Mon Sep 17 00:00:00 2001
From: Jiaming Yuan <jm.yuan@outlook.com>
Date: Tue, 7 Nov 2023 05:03:30 +0800
Subject: [PATCH] [doc] Add doc for linters and simplify c++ lint script.
 (#9750)

---
 .github/workflows/main.yml   |  8 +-------
 doc/contrib/coding_guide.rst | 32 ++++++++++++++++++++++++++++----
 tests/ci_build/lint_cpp.py   |  9 ++++++++-
 3 files changed, 37 insertions(+), 12 deletions(-)

diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 3fd39bc36..67e77ad6e 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -144,11 +144,5 @@ jobs:
         python -m pip install wheel setuptools cmakelint cpplint pylint
     - name: Run lint
       run: |
-        python3 tests/ci_build/lint_cpp.py xgboost cpp R-package/src
-
-        python3 tests/ci_build/lint_cpp.py xgboost cpp include src python-package \
-            --exclude_path python-package/xgboost/dmlc-core python-package/xgboost/include \
-                           python-package/xgboost/lib python-package/xgboost/rabit \
-                           python-package/xgboost/src
-
+        python3 tests/ci_build/lint_cpp.py
         sh ./tests/ci_build/lint_cmake.sh
diff --git a/doc/contrib/coding_guide.rst b/doc/contrib/coding_guide.rst
index 1169921bb..f7ed88b6c 100644
--- a/doc/contrib/coding_guide.rst
+++ b/doc/contrib/coding_guide.rst
@@ -118,16 +118,40 @@ two automatic checks to enforce coding style conventions. To expedite the code r
 
 Linter
 ======
-We use `pylint <https://github.com/PyCQA/pylint>`_ and `cpplint <https://github.com/cpplint/cpplint>`_ to enforce style convention and find potential errors. Linting is especially useful for Python, as we can catch many errors that would have otherwise occurred at run-time.
+We use a combination of linters to enforce style convention and find potential errors. Linting is especially useful for scripting languages like Python, as we can catch many errors that would have otherwise occurred at run-time.
 
-To run this check locally, run the following command from the top level source tree:
+For Python scripts, `pylint <https://github.com/PyCQA/pylint>`_, `black <https://github.com/psf/black>`__ and `isort <https://github.com/PyCQA/isort>`__ are used for providing guidance on coding style, and `mypy <https://github.com/python/mypy>`__ is required for type checking. For C++, `cpplint <https://github.com/cpplint/cpplint>`_ is used along with ``clang-tidy``. For R, ``lintr`` is used.
+
+To run checks for Python locally, install the checkers mentioned previously and run:
 
 .. code-block:: bash
 
   cd /path/to/xgboost/
-  make lint
+  python ./tests/ci_build/lint_python.py --fix
+
+To run checks for R:
+
+.. code-block:: bash
+
+  cd /path/to/xgboost/
+  Rscript tests/ci_build/lint_r.R $(pwd)
+
+To run checks for cpplint locally:
+
+.. code-block:: bash
+
+  cd /path/to/xgboost/
+  python ./tests/ci_build/lint_cpp.py
+
+
+See next section for clang-tidy. For CMake scripts:
+
+.. code-block:: bash
+
+  bash ./tests/ci_build/lint_cmake.sh
+
+Lastly, the linter for jvm-packages is integrated into the maven build process.
 
-This command requires the Python packages pylint and cpplint.
 
 Clang-tidy
 ==========
diff --git a/tests/ci_build/lint_cpp.py b/tests/ci_build/lint_cpp.py
index 593b8f870..6ec2b4e7f 100644
--- a/tests/ci_build/lint_cpp.py
+++ b/tests/ci_build/lint_cpp.py
@@ -134,7 +134,12 @@ def process(fname, allow_type):
 
 def main():
     parser = argparse.ArgumentParser(description="run cpp lint")
-    parser.add_argument("path", nargs="+", help="path to traverse")
+    parser.add_argument(
+        "path",
+        nargs="*",
+        help="Path to traverse",
+        default=["src", "include", os.path.join("R-package", "src"), "python-package"],
+    )
     parser.add_argument(
         "--exclude_path",
         nargs="+",
@@ -148,6 +153,8 @@ def main():
     allow_type += CXX_SUFFIX
 
     for path in args.path:
+        if not os.path.exists(path):
+            raise ValueError(f"Unknown path: {path}")
         if os.path.isfile(path):
             normpath = os.path.normpath(path)
             if normpath not in excluded_paths: