DOC Fix 'size' sphinx warnings.

[cmarmo]

This pull request partially addresses #13114, fixing the sphinx warnings related to single back-quoting size.

[mattip]

It is a bit tricky, since size as a parameter is OK so each case must be carefully examined.

[cmarmo]

It is a bit tricky, since size as a parameter is OK so each case must be carefully examined.

... sorry I don't understand: the parameter names do not produce a sphinx warning because they are not back-quoted. I have only changed the single quote to double quote where the warnings were rising ... do you mind clarifying what I am missing? Thanks.

[rossbar]

sorry I don't understand: the parameter names do not produce a sphinx warning because they are not back-quoted. I have only changed the single quote to double quote where the warnings were rising ... do you mind clarifying what I am missing? Thanks.

The problem is that single backticks around parameter names is correct according to the numpydoc docstring standard which is used not only by numpy but many other projects as well. The root of the problem is that the single backticks around parameter names conflicts with the default role from sphinx itself. This is a common problem which is touched on a bit in #18879 and especially numpy/numpydoc#323.

IMO this should be fixed in numpydoc itself. There was an attempt to solve the collision in backtick semantics in numpy/numpydoc#303 which had some components that I think were headed in the right direction. The way I would try to solve this problem would be to define a new numpydoc configuration parameter (say numpydoc_parameter_role) and apply it to parameters in numpydoc-formatted docstrings to preempt the collision with the default sphinx role. I plan on taking a stab at this at some point but if someone else is interested in picking it up I'm happy to review! All this is a bit of a tangent for this PR but long story short is that I don't think the proposed changes here are the right way to solve the problem as a more comprehensive fix is needed.

[cmarmo]

Thanks @rossbar for the clarification. I'm closing this then.