fixup! fixup! fixup! DOC: Add ignore_functions option to validate_docstrings.py

Author: Moisan

ci/code_checks.sh

@@ -84,7 +84,33 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
     MSG='Partially validate docstrings (RT02)' ; echo $MSG
-    $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
+    $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
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
 fi

scripts/tests/test_validate_docstrings.py

@@ -199,6 +199,25 @@ def test_leftover_files_raises(self):
                 self._import_path(klass="BadDocstrings", func="leftover_files")
             )
 
+    def test_validate_all_ignore_functions(self, monkeypatch):
+        monkeypatch.setattr(
+            validate_docstrings,
+            "get_all_api_items",
+            lambda: [
+                (
+                    "pandas.DataFrame.align",
+                    "func",
+                    "current_section",
+                    "current_subsection",
+                )
+            ],
+        )
+        result = validate_docstrings.validate_all(
+            prefix=None,
+            ignore_functions=["pandas.DataFrame.align"],
+        )
+        assert len(result) == 0
+
     def test_validate_all_ignore_deprecated(self, monkeypatch):
         monkeypatch.setattr(
             validate_docstrings,

scripts/validate_docstrings.py

@@ -321,12 +321,7 @@ def validate_all(prefix, ignore_deprecated=False, ignore_functions=None):
 
     ignore_functions = set(ignore_functions or [])
 
-    base_path = pathlib.Path(__file__).parent.parent
-    api_doc_fnames = pathlib.Path(base_path, "doc", "source", "reference")
-    api_items = []
-    for api_doc_fname in api_doc_fnames.glob("*.rst"):
-        with open(api_doc_fname) as f:
-            api_items += list(get_api_items(f))
+    api_items = get_all_api_items()
 
     for func_name, _, section, subsection in api_items:
         if func_name in ignore_functions:
@@ -354,6 +349,16 @@ def validate_all(prefix, ignore_deprecated=False, ignore_functions=None):
     return result
 
 
+def get_all_api_items():
+    base_path = pathlib.Path(__file__).parent.parent
+    api_doc_fnames = pathlib.Path(base_path, "doc", "source", "reference")
+    api_items = []
+    for api_doc_fname in api_doc_fnames.glob("*.rst"):
+        with open(api_doc_fname) as f:
+            api_items += list(get_api_items(f))
+    return api_items
+
+
 def print_validate_all_results(
     prefix: str,
     errors: list[str] | None,
@@ -477,7 +482,7 @@ def main(func_name, prefix, errors, output_format, ignore_deprecated, ignore_fun
     )
     argparser.add_argument(
         "--ignore_functions",
-        default=None,
+        nargs="*",
         help="function or method to not validate "
         "(e.g. pandas.DataFrame.head). "
         "Inverse of the `function` argument.",
@@ -491,6 +496,6 @@ def main(func_name, prefix, errors, output_format, ignore_deprecated, ignore_fun
             args.errors.split(",") if args.errors else None,
             args.format,
             args.ignore_deprecated,
-            args.ignore_functions.split(",") if args.ignore_functions else None,
+            args.ignore_functions,
         )
     )