3

In a python module, in the docstring of the module I have the following:

:meth:`my_method`

and I have the following class in the current module:

class GameP:

    ...

    def my_method(self):
        return f"{self._name} {self.selected}"

Sphinx does not create a link for that, whilst in the Sphinx documentation we have:

Normally, names in these roles are searched first without any further qualification, then with the current module name prepended, then with the current module and class name (if any) prepended. If you prefix the name with a dot, this order is reversed. For example, in the documentation of Python’s codecs127 module, :py:func:open always refers to the built-in function, while :py:func:.open refers to codecs.open().

Why does the bolded section not hold for me? :meth: role does not make a link for me.

mzjn
  • 48,958
  • 13
  • 128
  • 248
Green Falcon
  • 818
  • 3
  • 17
  • 48

1 Answers1

2

The documentation is not crystal clear IMHO, but it works if you use :meth:`.my_method` (with a dot). The dot makes Sphinx look for a match for my_method anywhere.

The dot is not needed if the cross-reference is in the docstring of the GameP class. But in this case the cross-reference is in the module docstring, and on the module level there is no "current class name".

mzjn
  • 48,958
  • 13
  • 128
  • 248
  • Thank you for your response. I've read the document, and it says that the `.` is used to reverse the searching operation. This differs from what you have referred to. You've said *Anywhere*. Can you tell me what we have in sphinx docs is wrong? – Green Falcon Aug 12 '21 at 10:46
  • 1
    I think *If you prefix the name with a dot, this order is reversed* is unclear. But it also says *if the name is prefixed with a dot, and no exact match is found, the target is taken as a suffix and all object names with that suffix are searched.* That is what I mean when I say that Sphinx will look for a match anywhere. – mzjn Aug 12 '21 at 11:00