Repository navigation
DOC: sphinx warnings because of **kwds in the stats distributions docstrings. #3915
Description
When building the HTML documentation, a warning of the form
/.../scipy/doc/source/generated/scipy.stats.alpha.rst:197: WARNING: Inline strong start-string without end-string.
is generated for each distribution in scipy.stats, and for rv_continuous. (That's over 80 warnings.) The problem is the class docstring includes the signature of the expect method, which is
expect(func, %(shapes)s, loc=0, scale=1, lb=None, ub=None, conditional=False, **kwds)
and ** is the markup for "strong emphasis".
The specific lines (at the time of writing this) are https://github.com/scipy/scipy/blob/master/scipy/stats/_distn_infrastructure.py#L119 and https://github.com/scipy/scipy/blob/master/scipy/stats/_distn_infrastructure.py#L1272
Activity
WarrenWeckesser commentedon Aug 29, 2014
A simple fix is to enclose the function signatures in double backticks:
That prevents the warnings, and it looks OK in the HTML output, but it adds a bit of clutter to the plain text docstring that one sees when using an interactive shell.
If we do this, all the signatures in those docstrings should be handled like this, so we maintain a consistent style.
argriffing commentedon Aug 29, 2014
Maybe someone at euroscipy will be excited to do this at the sprints.
WarrenWeckesser commentedon Aug 29, 2014
It would take a special kind of person to be excited about cleaning up sphinx warnings. :)
But it would be great if someone gave it a shot. If I were there, I'd buy him or her a beer.
jvkersch commentedon Aug 30, 2014
I'm at EuroSciPy, and I really, really hate Sphinx warnings ;-) I can take a look tomorrow if nobody else has done so by then.
rgommers commentedon Aug 30, 2014
That would be great Joris. Will you join the sprint tomorrow?
DOC: surround methods in class docstrings with backticks.