error if a docstring ends in ()

[shimizukawa]

With sphinx-apidoc generated module documentation, when the first line of a docstring includes two or more (), the HTML output is malformed:

dotfiles_status() -- print dotfiles_status()¶

There's probably a feature here that I'm unintentionally utilizing. Is there a greedy match for a manual override of argdocs in the first line of a docstring?

conf.py

#!python
extensions = [
    'sphinx.ext.autodoc',
]

Examples:

#!python

def dotfiles_status(self, line):
    """dotfiles_status()  -- print dotfiles_status()"""
    pass

#!python

def dotfiles_status(self, line):
    """
    dotfiles_status()  -- print dotfiles_status()"""
    pass

#!python

def dotfiles_status(self, line):
    """
    dotfiles_status()  -- print dotfiles_status()
    """
    pass

#!python

def dotfiles_status(self, line):
    """
    dotfiles_status()  -- print dotfiles_status()
    .
    """
    pass

With an initial period in the first line containing text, or a terminal period, the output looks correct (does not break the output):

#!python
def dotfiles_status(self, line):
    """
    .
    dotfiles_status()  -- print dotfiles_status()
    """
    pass

#!python
def dotfiles_status(self, line):
    """
    dotfiles_status()  -- print dotfiles_status() .
    """
    pass

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1626
• Originally reported by: Wes Turner
• Originally created at: 2014-11-14T03:28:01.748

[shimizukawa]

From Takayuki Shimizukawa on 2014-11-14 04:04:15+00:00

It's caused by the docstring signature feature: http://sphinx-doc.org/ext/autodoc.html#confval-autodoc_docstring_signature
autodoc_docstring_signature = False in conf.py will generate a documentation what you want to get.

However, maybe we should fix the signature matching pattern for it:

sphinx/sphinx/ext/autodoc.py

Line 38 in 9bd9d8a

py_ext_sig_re = re.compile(

[shimizukawa]

From Georg Brandl on 2014-11-14 18:58:15+00:00

I'm not sure it's possible to change the pattern. Parsing a "valid" signature is definitely not possible with a regex.

However, I'd argue that this is a unconventional docstring. Usually the signature doesn't need to be repeated in the docstring (unless you want to override it or it's a C function). If you want to use this style, turning autodoc_docstring_signature off might be your best option.