Napoleon overescapes trailing underscore in parameter name leading to Unknown target name error

Question

I now have exactly the problem that was described in this issue: https://github.com/sphinx-doc/sphinx/issues/7734. An MWE is also provided in that issue.

My problem is just that the fix doesn't seem to be activated by default. In the source code I found that a setting called strip_signature_backslash in the config has to be set to True for the fix to be activated.

I have tried:

napoleon_strip_signature_backslash = True
autodoc_strip_signature_backslash = True
strip_signature_backslash = True

All at the bottom of conf.py, but none of them seems to activate this setting. I have googled for about an hour now, but I couldn't find any documentation on how to set this. The setting also appears in ext/autodoc/__init__.py and directives/__init__.py but as I said I couldn't figure out how to set it.

Any suggestions?

Answer 1

I actually figured it out trying to create a proper MWE. What caused the errors was actually not the issue pointed out here https://github.com/sphinx-doc/sphinx/issues/7734, but me writing unescaped backslashes in the docs.

However I noticed that even though no errors are thrown, the default configuration will strip function-parameters whose name ends with _.

E.g.

def f(self, p_):
    """
    Args:
        p_: hei

    Returns:
    """
    pass

renders as rendered such that p has no trailing underscore

In order to fix that issue you actually have to set strip_signature_backslash = True at the bottom of your conf.py file. It activates the fix pointed out in the pull-request.

Without the error I would probably never have noticed this.

Again - thanks for getting back to me so quickly @mzjn and @steve-piercy