What requirements are there for cross-referencing a Python object in Sphinx?

Question

I'm using :class: and getting a lot of warnings

WARNING: py:class reference target not found: mypkg.submodule.class.

I can't find anywhere in the documentation what exactly the requirements are for a correct cross-reference.

This is currently an incomplete list of requirements I think there are:

• The module of the object needs to be importable
• The object needs to exist inside of the module
• The object needs to be documented somewhere else in the build with a :py:class::, :py:func:: or similar directive
  • This directive can be generated by the autodoc extension, in which case the object needs to have a docstring associated to it.

Answer 1

For something to be cross-referenced it has to first be "declared".

The Python domain (name py) provides the following directives for module declarations:

There are 2 cases to consider:

• domain directives (.. domain:directive_name::) and
• roles (:domain:role_name:).

The case of :class: you specify is actually the shortened syntax of writing the role :py:class: not to be confused with the directive declaration .. py:class::.

This directive can be generated by the autodoc extension, in which case the object needs to have a docstring associated to it.

The directive declarations are done implicitly by autodoc, but for objects without docstrings to be declared by autodoc you must use :undoc-members: option with the autodoc directives.

Members without docstrings will be left out, unless you give the undoc-members flag option:

.. automodule:: noodle    
   :members:    
   :undoc-members: 

One effect of declaring an object is that it is inserted in the index. So you can check the index to make sure it has been declared and inserted. (However note that labels used in referencing arbitrary locations are not inserted in the index.)