BUG, DOC: Fixes SciPy docs build warnings#20786
Conversation
The new f2py symbolic parser writes ternary expressions with spaces surrounding the colon operator, which causes the generated docstrings to be incorrectly parsed. Removing the spaces solves the issue.
dd6dffd to
9cdc237
Compare
HaoZeke
left a comment
There was a problem hiding this comment.
Fantastic catch! This must have been a nightmare to track down 😅😅
LGTM.
There was a problem hiding this comment.
LGTM!
Although, I think it is rather a doc-string parser bug or we should adjust doc-string generation: users can use ternary operators in .pyf files and this issue will raise again if they (rightfully) use spaces.
EDIT: On the second thought, if f2py symbolic parser is able to parse the ternary expressions correctly then user-specified spaces will be removed and this fix will resolve the issue terminally for ternary operations but may appear in other situations where spaces are used. So, looking into adjusting the doc-string generation to make it more robust for doc-string parser would make sense.
Yes: this only solves the issue for the ternary operators, but at the same time from my (limited) research it is only related to colons. See for example this stackoverflow question. This is only a workaround, and should probably be fixed in numpydoc but it looks slightly trickier than it appears. |
|
If the expressions in the f2py-generated docstrings that contain a colon would be surrounded by double-backquotes, e.g. would that resolve the issue? |
Unfortunately it doesn't - I still get the same warnings even with the backticks. |
|
Thanks Melissa. Is there an issue for this in numpydoc? If so, a link would be useful. |
|
@charris I'll open one, thanks! |
The new f2py symbolic parser writes ternary expressions with
spaces surrounding the colon operator, which causes the generated
docstrings to be incorrectly parsed. Removing the spaces solves the
issue.
Fixes #20696