Skip to content

BUG, DOC: Fixes SciPy docs build warnings#20786

Merged
charris merged 1 commit intonumpy:mainfrom
melissawm:f2py-scipy-docs
Jan 11, 2022
Merged

BUG, DOC: Fixes SciPy docs build warnings#20786
charris merged 1 commit intonumpy:mainfrom
melissawm:f2py-scipy-docs

Conversation

@melissawm
Copy link
Member

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

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.
Copy link
Member

@HaoZeke HaoZeke left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fantastic catch! This must have been a nightmare to track down 😅😅
LGTM.

Copy link
Contributor

@pearu pearu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@melissawm
Copy link
Member Author

melissawm commented Jan 11, 2022

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.

@pearu
Copy link
Contributor

pearu commented Jan 11, 2022

If the expressions in the f2py-generated docstrings that contain a colon would be surrounded by double-backquotes, e.g.

  z : rank-2 array('F') with bounds ``((compute_v ? MAX(0,n) : 0),(compute_v ? (*range=='I'?iu-il+1 : MAX(1,n)) : 0))``

would that resolve the issue?

@melissawm
Copy link
Member Author

would that resolve the issue?

Unfortunately it doesn't - I still get the same warnings even with the backticks.

@charris charris merged commit 879ec41 into numpy:main Jan 11, 2022
@charris
Copy link
Member

charris commented Jan 11, 2022

Thanks Melissa. Is there an issue for this in numpydoc? If so, a link would be useful.

@charris charris added the 09 - Backport-Candidate PRs tagged should be backported label Jan 11, 2022
@charris charris added this to the 1.22.1 release milestone Jan 11, 2022
@charris charris added 04 - Documentation and removed 09 - Backport-Candidate PRs tagged should be backported labels Jan 11, 2022
@charris charris removed this from the 1.22.1 release milestone Jan 11, 2022
@melissawm
Copy link
Member Author

@charris I'll open one, thanks!

@melissawm melissawm deleted the f2py-scipy-docs branch February 8, 2022 17:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

New build warnings for SciPy doc build due to f2py changes in 1.22.0

4 participants