DOC: Ensure pandas warnings & exceptions are always documented in API docs (#43029)

* DOC: Ensure all pandas.errors are documents in general_utility_functions.rst

* Use ast to check for the errors

* Use pathlib to ensure Windows support

Author: mroeschke

.pre-commit-config.yaml

@@ -164,3 +164,8 @@ repos:
         entry: python scripts/no_bool_in_generic.py
         language: python
         files: ^pandas/core/generic\.py$
+    -   id: pandas-errors-documented
+        name: Ensure pandas errors are documented in doc/source/reference/general_utility_functions.rst
+        entry: python scripts/pandas_errors_documented.py
+        language: python
+        files: ^pandas/errors/__init__.py$

doc/source/reference/general_utility_functions.rst

@@ -35,14 +35,17 @@ Exceptions and warnings
 .. autosummary::
    :toctree: api/
 
+   errors.AbstractMethodError
    errors.AccessorRegistrationWarning
    errors.DtypeWarning
    errors.DuplicateLabelError
    errors.EmptyDataError
    errors.InvalidIndexError
+   errors.IntCastingNaNError
    errors.MergeError
    errors.NullFrequencyError
    errors.NumbaUtilError
+   errors.OptionError
    errors.OutOfBoundsDatetime
    errors.OutOfBoundsTimedelta
    errors.ParserError

pandas/errors/__init__.py

@@ -14,7 +14,7 @@
 
 class IntCastingNaNError(ValueError):
     """
-    raised when attempting an astype operation on an array with NaN to an integer
+    Raised when attempting an astype operation on an array with NaN to an integer
     dtype.
     """
 

scripts/pandas_errors_documented.py

@@ -0,0 +1,52 @@
+"""
+Check that doc/source/reference/general_utility_functions.rst documents
+all exceptions and warnings in pandas/errors/__init__.py.
+
+This is meant to be run as a pre-commit hook - to run it manually, you can do:
+
+    pre-commit run pandas-errors-documented --all-files
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import pathlib
+import sys
+from typing import Sequence
+
+API_PATH = pathlib.Path("doc/source/reference/general_utility_functions.rst").resolve()
+
+
+def get_defined_errors(content: str) -> set[str]:
+    errors = set()
+    for node in ast.walk(ast.parse(content)):
+        if isinstance(node, ast.ClassDef):
+            errors.add(node.name)
+        elif isinstance(node, ast.ImportFrom):
+            for alias in node.names:
+                errors.add(alias.name)
+    return errors
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("path")
+    args = parser.parse_args(argv)
+    with open(args.path, encoding="utf-8") as f:
+        file_errors = get_defined_errors(f.read())
+    with open(API_PATH) as f:
+        doc_errors = {
+            line.split(".")[1].strip() for line in f.readlines() if "errors" in line
+        }
+    missing = file_errors.difference(doc_errors)
+    if missing:
+        sys.stdout.write(
+            f"The follow exceptions and/or warnings are not documented "
+            f"in {API_PATH}: {missing}"
+        )
+        sys.exit(1)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()