DOC: Add ignore_functions option to validate_docstrings.py

Author: Moisan

ci/code_checks.sh

@@ -83,6 +83,8 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
     $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX04,GL01,GL02,GL03,GL04,GL05,GL06,GL07,GL09,GL10,PR03,PR04,PR05,PR06,PR08,PR09,PR10,RT01,RT04,RT05,SA02,SA03,SA04,SS01,SS02,SS03,SS04,SS05,SS06
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
+    $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=RT02 --ignore_functions=pandas.Series.align,pandas.Series.dt.total_seconds,pandas.Series.cat.rename_categories,pandas.Series.cat.reorder_categories,pandas.Series.cat.add_categories,pandas.Series.cat.remove_categories,pandas.Series.cat.remove_unused_categories,pandas.Index.all,pandas.Index.any,pandas.CategoricalIndex.rename_categories,pandas.CategoricalIndex.reorder_categories,pandas.CategoricalIndex.add_categories,pandas.CategoricalIndex.remove_categories,pandas.CategoricalIndex.remove_unused_categories,pandas.MultiIndex.drop,pandas.DatetimeIndex.to_pydatetime,pandas.TimedeltaIndex.to_pytimedelta,pandas.core.groupby.SeriesGroupBy.apply,pandas.core.groupby.DataFrameGroupBy.apply,pandas.io.formats.style.Styler.export,pandas.api.extensions.ExtensionArray.astype,pandas.api.extensions.ExtensionArray.dropna,pandas.api.extensions.ExtensionArray.isna,pandas.api.extensions.ExtensionArray.repeat,pandas.api.extensions.ExtensionArray.unique,pandas.DataFrame.align
+
 fi
 
 ### DOCUMENTATION NOTEBOOKS ###

scripts/validate_docstrings.py

@@ -295,7 +295,7 @@ def pandas_validate(func_name: str):
     return result
 
 
-def validate_all(prefix, ignore_deprecated=False):
+def validate_all(prefix, ignore_deprecated=False, ignore_functions=None):
     """
     Execute the validation of all docstrings, and return a dict with the
     results.
@@ -307,6 +307,8 @@ def validate_all(prefix, ignore_deprecated=False):
         validated. If None, all docstrings will be validated.
     ignore_deprecated: bool, default False
         If True, deprecated objects are ignored when validating docstrings.
+    ignore_functions: list of str or None, default None
+        If not None, contains a list of function to ignore
 
     Returns
     -------
@@ -317,6 +319,11 @@ def validate_all(prefix, ignore_deprecated=False):
     result = {}
     seen = {}
 
+    if ignore_functions is None:
+        ignore_functions = {}
+    else:
+        ignore_functions = set(ignore_functions)
+
     base_path = pathlib.Path(__file__).parent.parent
     api_doc_fnames = pathlib.Path(base_path, "doc", "source", "reference")
     api_items = []
@@ -325,7 +332,9 @@ def validate_all(prefix, ignore_deprecated=False):
             api_items += list(get_api_items(f))
 
     for func_name, _, section, subsection in api_items:
-        if prefix and not func_name.startswith(prefix):
+        if (
+            prefix and not func_name.startswith(prefix)
+        ) or func_name in ignore_functions:
             continue
         doc_info = pandas_validate(func_name)
         if ignore_deprecated and doc_info["deprecated"]:
@@ -353,11 +362,12 @@ def print_validate_all_results(
     errors: list[str] | None,
     output_format: str,
     ignore_deprecated: bool,
+    ignore_functions: list[str] | None,
 ):
     if output_format not in ("default", "json", "actions"):
         raise ValueError(f'Unknown output_format "{output_format}"')
 
-    result = validate_all(prefix, ignore_deprecated)
+    result = validate_all(prefix, ignore_deprecated, ignore_functions)
 
     if output_format == "json":
         sys.stdout.write(json.dumps(result))
@@ -408,13 +418,17 @@ def header(title, width=80, char="#"):
         sys.stderr.write(result["examples_errs"])
 
 
-def main(func_name, prefix, errors, output_format, ignore_deprecated):
+def main(func_name, prefix, errors, output_format, ignore_deprecated, ignore_functions):
     """
     Main entry point. Call the validation for one or for all docstrings.
     """
     if func_name is None:
         return print_validate_all_results(
-            prefix, errors, output_format, ignore_deprecated
+            prefix,
+            errors,
+            output_format,
+            ignore_deprecated,
+            ignore_functions,
         )
     else:
         print_validate_one_results(func_name)
@@ -464,6 +478,13 @@ def main(func_name, prefix, errors, output_format, ignore_deprecated):
         "deprecated objects are ignored when validating "
         "all docstrings",
     )
+    argparser.add_argument(
+        "--ignore_functions",
+        default=None,
+        help="function or method to not validate "
+        "(e.g. Pandas.DataFrame.head). "
+        "Inverse of the `function` argument.",
+    )
 
     args = argparser.parse_args()
     sys.exit(
@@ -473,5 +494,6 @@ def main(func_name, prefix, errors, output_format, ignore_deprecated):
             args.errors.split(",") if args.errors else None,
             args.format,
             args.ignore_deprecated,
+            args.ignore_functions.split(",") if args.ignore_functions else None,
         )
     )