Justification for enquoting parameters in single backticks

[timhoffm]

https://numpydoc.readthedocs.io/en/latest/format.html#parameters states

Enclose variables in single backticks.

e.g.

x : type
    Description of parameter `x`.

Is there a specification backing this format? I have not found single backticks as valid markup in sphinx or docutils documentation. In contrast if using a default role in sphinx, this generates warning that the role traget cannot be resolved.

While that may (or may not)* work for numpy specifically, it can be a source of confusion for other projects that adopt the numpydoc style. It should at least be mentioned that single backticks can cause trouble with the default_role.

• see Default sphinx role "autolink" appears to be deprecated numpy#18879

[larsoner]

Agreed I have never really understood this.

I think one that that could be really cool is figure out how to actually add linkable params as

:py:parameter:`numpy.asarray.dtype`

to link to the dtype param of numpy.asarray for example. I think then with default_role being default_role = "py:obj" for example, things like "Description of parameter x" could probably in principle automagically link when used in a given function's parameter list this way.

This might require expanding https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html to have a new role or something, so an upstream issue might be the place to start. But to start we could just document as :py:obj: as this is for "unspecified" types, and always make it more specific later.

[timhoffm]

While linking to a parameter could in principle be possible. That's likely not as simple as one could imagine:

One aspect is that parameters are ReST field lists within Python object description directives, e.g.:

.. py:function:: send_message(sender, recipient, message_body, [priority=1])

   Send a message to a recipient

   :param str sender: The person sending the message
   :param str recipient: The recipient of the message
   [...]

Since I don't think one can reasonably change that syntax, you cannot have a new role. Rather, one would need to make these fields referencable. While I haven't looked into the sphinx source code, I anticipate that this is not easy because field lists and roles are quite different things.

Another serious issue is the link resolution. Parameter names are usually note unique, we need to make their id unique using the contained function, e.g. numpy.asarray-dtype. But you don't want to write the full id as a reference. You'd need some mechanism to resolve such references to the corresponding name in the docstring. This logic is quite different from the regular resolution of code objects and thus may again be difficult to integrate with the extisting code.

[jnothman]

I'm pretty sure the Sphinx glossary similarly uses a definition list, but it's entries are referanceable. So it might out be available off the shelf, but I don't see why it should not be possible with the right hook. But that barely relates to the question of backticks. Backticks will execute the default role which can merely be mapped to italic or monospace font; it can resolve a reference but can be customised to not raise a warning.

[timhoffm]

can be customised to not raise a warning.

Is that suppress_warnings? Unfortunately, the sphinx docs are not quite clear on this.

Anyway, my point is that using the default role for parameters does not work well for arbitrary sphinx configurations. numpydoc should communicate clearly which assumptions and configurations are supported (in the minimal scenario only stating your preferred config and that others may not work with using the default role for parameters.