Cross referencing Python objects

When writing your docs, it is usually helpful to have cross references to Python objects.

For cross-referencing Python objects, take a look at the possible roles.

Cross reference syntax takes one of these formats:

• :role:`target`

• :role:`title <target>`

Additionally,

• Prefix the content with ! to avoid creating a link.

• Prefix the content with ~ to the link text will only be the last component of the target. For example, :py:meth:`~Queue.Queue.get` will refer to Queue.Queue.get but only display get as the link text. This does not work with all cross-reference roles, but is domain specific.

The py that precedes each identifier refers to the domain. In this case it implies the Python domain. The Python domain is the default one, but it can be modified using the default-domain directive or the config value primary_domain.

When cross referencing an object of the default domain, it is not required to use the domain. E.g. if Python is the default domain :py:meth:`~Queue.Queue.get` is equivalent to :meth:`~Queue.Queue.get`.

Note

To be able to cross reference object from different projects, take a look at linking to other projects.