Disambiguate argument descriptors from section headers

[charliermarsh]

Summary

Given a docstring like:

def func(x: int, args: tuple[int]):
    """Toggle the gizmo.

    Args:
        x: Some argument.
        args: Some other arguments.
    """

We were considering the args: descriptor to be an indented docstring section header (since Args:) is a valid header name. This led to very confusing diagnostics.

This PR makes the parsing a bit more lax in this case, such that if we see a nested header that's more deeply indented than the preceding header, and the preceding section allows sub-items (like Args:), we avoid treating the nested item as a section header.

Closes #9426.

[github-actions]

ruff-ecosystem results

Linter (stable)

✅ ecosystem check detected no linter changes.

Linter (preview)

✅ ecosystem check detected no linter changes.