ENH: Modify the markups for parameters (x to *x*)

[takanori-pskq]

Related to numpy/numpy#17714 .

Currently, numpydoc do nothing about the markup for single backticks (`x`). Sphinx seems to interpret `x` as a parameter name (*x*) when the python object x doesn't exists, and a reference (:obj:`x`) otherwise. This process works fine in most cases, but doesn't work if a python object which has the same name as the parameter name exists (see numpy/numpy#17714 (comment) : collision between `size` parameter and numpy.size). So I added a process to convert `x` to *x* for a parameter name x.

[mattip]

There is a failing test. It would be good to add a test that fails before, passes after this change.

[mattip]

Is this the same issue in gh-295?

[takanori-pskq]

I think it's not the same issue, because gh-295 is about whether to convert from `x` to :obj:`x`.

[jnothman]

Changing to using asterisks is a big change. Putting a specific role before or would be okay, but it should be configurable. The library can also configure how the role is interpreted and can make it visually appear the same as asterisks would.

[takanori-pskq]

Now I changed to use a new config variable numpy_role_param. The default value is None, which means "do nothing". The expected behavier can be achieved by setting numpy_role_param = ':emphasis:'. Later I'll add documents and tests.

[takanori-pskq]

I noticed that adding a role could break a table structure. In the docstring of numpy.arctan2, with numpy_role_param = ':emphasis:' :

====== ====== ================
:emphasis:`x1`   :emphasis:`x2`   `arctan2(x1,x2)`
====== ====== ================
+/- 0  +0     +/- 0
+/- 0  -0     +/- pi
 > 0   +/-inf +0 / +pi
 < 0   +/-inf -0 / -pi
+/-inf +inf   +/- (pi/4)
+/-inf -inf   +/- (3*pi/4)
====== ====== ================

[jnothman]

Indeed, that will be hard to fix, but... I don't get why we're substituting every mention of the param name in any case. Why are we doing that?

[jnothman]

In fact, I would like to see an example docstrng use case of where this PR is needed.

[takanori-pskq]

There are some functions which have size parameter, so `size` appears in some docstrings (For example: polynomial.truncate() ).
These should be interpreted as a parameter (*size* or :emphasis:`size` ), but the existence of the python object numpy.size causes them to be interpreted as the reference.