[ci] [python-package] enforce 'numpydoc-validation' and 'pydoclint' checks (#7478)

Author: jameslamb

.ci/parameter-generator.py

@@ -23,9 +23,9 @@ def get_parameter_infos(config_hpp: Path) -> Tuple[List[Tuple[str, int]], List[L
 
     Returns
     -------
-    infos : tuple
+    tuple
         Tuple with names and content of sections.
-    """
+    """  # noqa: DOC105
     is_inparameter = False
     cur_key = None
     key_lvl = 0
@@ -96,9 +96,9 @@ def get_names(infos: List[List[Dict[str, List]]]) -> List[str]:
 
     Returns
     -------
-    names : list
+    list
         Names of all parameters.
-    """
+    """  # noqa: DOC105
     names = []
     for x in infos:
         for y in x:
@@ -116,9 +116,9 @@ def get_alias(infos: List[List[Dict[str, List]]]) -> List[Tuple[str, str]]:
 
     Returns
     -------
-    pairs : list
+    list
         List of tuples (param alias, param name).
-    """
+    """  # noqa: DOC105
     pairs = []
     for x in infos:
         for y in x:
@@ -142,9 +142,9 @@ def parse_check(check: str, reverse: bool = False) -> Tuple[str, str]:
 
     Returns
     -------
-    pair : tuple
+    tuple
         Parsed constraint in the form of tuple (value, sign).
-    """
+    """  # noqa: DOC105
     try:
         idx = 1
         float(check[idx:])
@@ -172,9 +172,9 @@ def set_one_var_from_string(name: str, param_type: str, checks: List[str]) -> st
 
     Returns
     -------
-    ret : str
+    str
         Lines of auto config file with getting and checks of one parameter value.
-    """
+    """  # noqa: DOC105
     ret = ""
     univar_mapper = {"int": "GetInt", "double": "GetDouble", "bool": "GetBool", "std::string": "GetString"}
     if "vector" not in param_type:
@@ -209,7 +209,7 @@ def gen_parameter_description(
         Structured descriptions of parameters.
     params_rst : pathlib.Path
         Path to the file with parameters documentation.
-    """
+    """  # noqa: DOC105
     params_to_write = []
     lvl_mapper = {1: "-", 2: "~"}
     for (section_name, section_lvl), section_params in zip(sections, descriptions, strict=True):
@@ -274,9 +274,9 @@ def gen_parameter_code(
 
     Returns
     -------
-    infos : tuple
+    tuple
         Tuple with names and content of sections.
-    """
+    """  # noqa: DOC105
     keys, infos = get_parameter_infos(config_hpp)
     names = get_names(infos)
     alias = get_alias(infos)

.pre-commit-config.yaml

@@ -2,10 +2,12 @@
 exclude: |
   (?x)^(
       build|
+      dist|
       external_libs|
       lightgbm-python|
       lightgbm_r|
       \.pixi|
+      \.venv|
   )$
   |R-package/configure$
   |R-package/inst/Makevars$
@@ -77,6 +79,16 @@ repos:
           - ./.ci/parameter-generator.py
         language: python
         pass_filenames: false
+  - repo: https://github.com/numpy/numpydoc
+    rev: v1.11.0
+    hooks:
+      - id: numpydoc-validation
+        args: [--config=python-package]
+  - repo: https://github.com/jsh9/pydoclint
+    rev: 0.10.1
+    hooks:
+      - id: pydoclint
+        args: [--config=python-package/pyproject.toml]
   - repo: https://github.com/rstcheck/rstcheck
     rev: v6.2.5
     hooks:

docs/conf.py

@@ -239,7 +239,7 @@ def generate_doxygen_xml(app: Sphinx) -> None:
     ----------
     app : sphinx.application.Sphinx
         The application object representing the Sphinx process.
-    """
+    """  # noqa: DOC105
     doxygen_args = [
         f"INPUT={CURR_PATH.parent / 'include' / 'LightGBM' / 'c_api.h'}",
         f"OUTPUT_DIRECTORY={CURR_PATH / 'doxyoutput'}",
@@ -283,7 +283,7 @@ def generate_r_docs(app: Sphinx) -> None:
     ----------
     app : sphinx.application.Sphinx
         The application object representing the Sphinx process.
-    """
+    """  # noqa: DOC105
     commands = f"""
     export TAR=/bin/tar
     cd {CURR_PATH.parent}
@@ -316,7 +316,7 @@ def replace_reference_to_r_docs(app: Sphinx) -> None:
     ----------
     app : sphinx.application.Sphinx
         The application object representing the Sphinx process.
-    """
+    """  # noqa: DOC105
     index_doc_path = CURR_PATH / "index.rst"
     with open(index_doc_path, "r+t", encoding="utf-8") as index_doc:
         content = index_doc.read()
@@ -332,7 +332,7 @@ def setup(app: Sphinx) -> None:
     ----------
     app : sphinx.application.Sphinx
         The application object representing the Sphinx process.
-    """
+    """  # noqa: DOC105
     first_run = not (CURR_PATH / "_FIRST_RUN.flag").exists()
     if first_run and RTD:
         (CURR_PATH / "_FIRST_RUN.flag").touch()