terrencepreilly / darglint

A python documentation linter which checks that the docstring description matches the definition.
MIT License
483 stars 41 forks source link

Support backticks for arguments in Sphinx style #170

Open kalibyrn opened 3 years ago

kalibyrn commented 3 years ago

Given the following function:

def key_if_required(key: str, required: bool = True) -> dict:
    """
    Check if key is required and return a dictionary.

    :param `key`: The name of the key to check
    :param `required`: Whether the key is required or not
    :returns: Dictionary
    """
    if key not in ["dogs", "cats"]:
        return {"default": key}
    return {"required": required}

darglint will report these errors when using Sphinx formatting:

test_me.py:key_if_required:4: DAR102: + `key`
test_me.py:key_if_required:4: DAR102: + `required`
test_me.py:key_if_required:4: DAR101: - key
test_me.py:key_if_required:4: DAR101: - required

The backticks are nice because they allow highlighting in editors. If there were an option to ignore backticks for arguments that would be great.

image