Escaping characters in docstring raises DOC103

[haakonvt]

This is more a question than an issue (I'm sorry for opening my third issue in a week's time...).

I am on the brink of adding pydoclint to my company's codebase (started at 1000 issues.... now down to 1), but the only way I'm able to is by excluding the file via pre-commit.

I have the following class:

class Foo:
    r"""Description

    Args:
        with\_ (dict): Description
        select (str): Description
    """
    def __init__(self, with_: dict, select: str):
        ...

pydoclint imo correctly raises:

    8: DOC103: Method `Foo.__init__`: Docstring arguments are different from function arguments.
(Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). 
Arguments in the function signature but not in the docstring: [with_: dict]. Arguments in the docstring but 
not in the function signature: [with\_: dict].

If I try to remove the \ before the underscore, sphinx complains:

$ .Foo:7: ERROR: Unknown target name: "with".

...and the documentation shows with instead of with_.

Do you have a suggested approach here (outside excluding the entire file?) 🙏

[jsh9]

Hi @haakonvt , thanks for raising this issue!

I didn't know that Sphinx requires escaping underscores. And interestingly, only 1 or 2 trailing underscores need to be escaped. 3 or more trailing underscores and preceding underscores don't seem to need to be escaped.

I've pushed a fix and it will be published as v0.2.2.

[haakonvt]

That's great! Thanks a lot (again) @jsh9 🙏 👏