Function check_docstrings

tools/precommit/docstrings.py:852–1073

Check salt's docstrings

(
    ctx: Context,
    files: list[pathlib.Path],
    suppress_warnings: bool = False,
    check_proper_formatting: bool = False,
    error_on_known_failures: bool = False,
)

    },
)
def check_docstrings(
    ctx: Context,
    files: list[pathlib.Path],
    suppress_warnings: bool = False,
    check_proper_formatting: bool = False,
    error_on_known_failures: bool = False,
) -> None:
    """
    Check salt's docstrings
    """
    if not files:
        _files = list(SALT_CODE_DIR.rglob("*.py"))
    else:
        _files = [fpath.resolve() for fpath in files if fpath.suffix == ".py"]

    errors = 0
    exitcode = 0
    warnings = 0
    for path in _files:
        if str(path).startswith(str(tools.utils.REPO_ROOT / "salt" / "ext")):
            continue
        contents = path.read_text()
        try:
            module = ast.parse(path.read_text(), filename=str(path))
            module_docstring = ast.get_docstring(module, clean=False)
            if module_docstring:
                error = _check_valid_versions_on_docstrings(module_docstring)
                if error:
                    errors += 1
                    exitcode = 1
                    ctx.error(
                        "The module '{}' does not provide a proper `{}` version: {!r} is not valid.".format(
                            path.relative_to(tools.utils.REPO_ROOT),
                            *error,
                        )
                    )

            for funcdef in [
                node for node in module.body if isinstance(node, ast.FunctionDef)
            ]:
                docstring = ast.get_docstring(funcdef, clean=False)
                if docstring:
                    error = _check_valid_versions_on_docstrings(docstring)
                    if error:
                        errors += 1
                        exitcode = 1
                        ctx.error(
                            "The module '{}' does not provide a proper `{}` version: {!r} is not valid.".format(
                                path,
                                *error,
                            )
                        )
                        annotate(
                            ctx,
                            "error",
                            path,
                            funcdef.lineno,
                            funcdef.body[0].lineno,