DOC: Fix reference warning for size. #24348
Conversation
|
This brings us down from 149 warnings (after #24346) to 108 warnings, cool. I do wonder if using italics |
|
This is a bug in numpydoc itself that IMO really ought to be fixed upstream. The "enclose-parameters-in-single-backticks" rule is part of the standard, so this particular numpydoc bug affects not only NumPy but many other projects that rely on the numpydoc sphinx extension. I have started working on a fix for this issue in numpy/numpydoc#484. There's still a lot of work to do, but the upside of that fix is that it would apply to all libraries that have adopted numpydoc. FWIW I've built the numpy docs with numpy/numpydoc#484 and can verify1 that it results in the same reduction down to 108 warnings (albeit at the expense of introducing two new malformatted table errors - another rough edge to iron out).
My vote would be to save this particular set of of warnings for last while trying to get a fix in upstream. @liang3zy22 if you were interested in numpy/numpydoc#484 that'd be great! If after an honest attempt it turns out the upstream fix is untenable, then I'd be +1 for breaking from the standard as proposed here. Footnotes
|
|
I agree fixing numpydoc would be a better solution. I am a bit surprised that only I had a hunch that was the problem when suggesting this be looked at, sorry @liang3zy22 for the work put in here. |
|
It's Ok. I would try the numpy/numpydoc#484. |
|
Closing while numpy/numpydoc#484 is open. If that is closed, this can be revived. Thanks @liang3zy22! |
To fix size reference warning.
I think single backquotes let sphinx recognize size as a function or class name. So I used double backquotes to let it be code examples.
Also update single backquotes for df to double backquotes.