move validate_rst_title_capitalization to pre-commit (#39779)

Author: MarcoGorelli

.pre-commit-config.yaml

@@ -180,6 +180,12 @@ repos:
         language: pygrep
         types: [python]
         files: ^pandas/tests/
+    -   id: title-capitalization
+        name: Validate correct capitalization among titles in documentation
+        entry: python scripts/validate_rst_title_capitalization.py
+        language: python
+        types: [rst]
+        files: ^doc/source/(development|reference)/
 -   repo: https://github.com/asottile/yesqa
     rev: v1.2.2
     hooks:

ci/code_checks.sh

@@ -233,10 +233,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
     $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=GL03,GL04,GL05,GL06,GL07,GL09,GL10,SS02,SS04,SS05,PR03,PR04,PR05,PR10,EX04,RT01,RT04,RT05,SA02,SA03
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
-    MSG='Validate correct capitalization among titles in documentation' ; echo $MSG
-    $BASE_DIR/scripts/validate_rst_title_capitalization.py $BASE_DIR/doc/source/development $BASE_DIR/doc/source/reference
-    RET=$(($RET + $?)) ; echo $MSG "DONE"
-
 fi
 
 ### TYPING ###

scripts/validate_rst_title_capitalization.py

@@ -1,17 +1,17 @@
-#!/usr/bin/env python3
 """
 Validate that the titles in the rst files follow the proper capitalization convention.
 
 Print the titles that do not follow the convention.
 
 Usage::
-./scripts/validate_rst_title_capitalization.py doc/source/development/contributing.rst
-./scripts/validate_rst_title_capitalization.py doc/source/
 
+As pre-commit hook (recommended):
+    pre-commit run title-capitalization --all-files
+
+From the command-line:
+    python scripts/validate_rst_title_capitalization.py <rst file>
 """
 import argparse
-import glob
-import os
 import re
 import sys
 from typing import Iterable, List, Tuple
@@ -233,45 +233,14 @@ def find_titles(rst_file: str) -> Iterable[Tuple[str, int]]:
             previous_line = line
 
 
-def find_rst_files(source_paths: List[str]) -> Iterable[str]:
-    """
-    Given the command line arguments of directory paths, this method
-    yields the strings of the .rst file directories that these paths contain.
-
-    Parameters
-    ----------
-    source_paths : str
-        List of directories to validate, provided through command line arguments.
-
-    Yields
-    -------
-    str
-        Directory address of a .rst files found in command line argument directories.
-    """
-
-    for directory_address in source_paths:
-        if not os.path.exists(directory_address):
-            raise ValueError(
-                "Please enter a valid path, pointing to a valid file/directory."
-            )
-        elif directory_address.endswith(".rst"):
-            yield directory_address
-        else:
-            yield from glob.glob(
-                pathname=f"{directory_address}/**/*.rst", recursive=True
-            )
-
-
-def main(source_paths: List[str], output_format: str) -> int:
+def main(source_paths: List[str]) -> int:
     """
     The main method to print all headings with incorrect capitalization.
 
     Parameters
     ----------
     source_paths : str
         List of directories to validate, provided through command line arguments.
-    output_format : str
-        Output format of the script.
 
     Returns
     -------
@@ -281,7 +250,7 @@ def main(source_paths: List[str], output_format: str) -> int:
 
     number_of_errors: int = 0
 
-    for filename in find_rst_files(source_paths):
+    for filename in source_paths:
         for title, line_number in find_titles(filename):
             if title != correct_title_capitalization(title):
                 print(
@@ -297,16 +266,9 @@ def main(source_paths: List[str], output_format: str) -> int:
     parser = argparse.ArgumentParser(description="Validate heading capitalization")
 
     parser.add_argument(
-        "paths", nargs="+", default=".", help="Source paths of file/directory to check."
-    )
-
-    parser.add_argument(
-        "--format",
-        "-f",
-        default="{source_path}:{line_number}:{msg}:{heading}:{correct_heading}",
-        help="Output format of incorrectly capitalized titles",
+        "paths", nargs="*", help="Source paths of file/directory to check."
     )
 
     args = parser.parse_args()
 
-    sys.exit(main(args.paths, args.format))
+    sys.exit(main(args.paths))