Cross reference documentation of function or class in Sphinx for Python

Question

I want, within an explanatory documentation, a reference to the documentation of a Python class and, a little later, to its constructor. So imagine there is a file

# MyLib/MyClass.py
class MyClass:
    """Class Introduction"""
    def __init__(paramX):
        """:param paramX: Xes out things"""

and my rst file

#MyLib/docs/source/MyDoc.rst
Some text where :ref:`here` is my reference to "Class Introduction"
 and :ref:`there` follows my reference to the __init__ method documentation

How can I get the reference working: How and where within the Sphinx files do I need to include the Python file and how do I define (in the Python file) and resolve (in the rst file) the references? The expected output would be something like this:

Some text where <link to documentation of class _MyClass_>...
 and 
    'class MyClass
        def __init__(paramX):
           paramX: Xes out things'

where as described the brackets <..> include a link to the documentation and the documentation itself appears after the 'and', referenced in the rst file by :ref:`here` and :ref:`there` , respectively.

Tried that already, but id only displays the name of the method, not the documentation and it also does not provide a link of any kind. — gilgamash, Mar 09 '21 at 11:38
I have provided an example but edited so that thins hopefully get clearer. If this is not enough, I can find some time tomorrow to set up a complete working example with all files needed. I hoped it would be clear without all that and ask for pardon if that is not the case. — gilgamash, Mar 09 '21 at 12:37
I think you might be looking for autosummary or autodoc to generate a page with information about your class: https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html. To reference it, use `:py:class:` to cross reference (note that you can usually set it up so that `py` is implicit and you just use `:class:` https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects — dwhswenson, Mar 09 '21 at 12:44
That was what I was looking for, thanks! Now that I know it, I rather quickly found it in the sphinx documentation. No idea why I could not before. Thanks a lot. If you rework it into a reply I can mark it as "solved". I also know now why the above link did not work out into a reference. — gilgamash, Mar 09 '21 at 12:46

score 2 · Accepted Answer · answered Mar 09 '21 at 15:42

From the example in the question the module ref_constructor.py

class MyClass:
    """Class Introduction."""
    def __init__(paramX):
        """The docstring of constructor.

        :param paramX: Xes out things.
        :type paramX: str
        """

Using the reST file ref_constructor.rst take care to choose the adequate roles, in this case :class: and :meth:

Reference to class constructor
------------------------------

.. automodule:: ref_constructor


.. here begins de documentation.

Some text where :class:`ref_constructor.MyClass` is my reference to "Class Introduction"
and :meth:`ref_constructor.MyClass.__init__` follows my reference to the __init__ method documentation.


Some text where :class:`MyClass` is my reference to "Class Introduction"
and :meth:`MyClass.__init__` follows my reference to the __init__ method documentation.

You can write the cross-references using fully qualified names or a shortened forms depending on context

Cross-referencing Python objects

The name enclosed in this markup can include a module name and/or a class name. For example, :py:func:`filter` could refer to a function named filter in the current module, or the built-in function of that name. In contrast, :py:func:`foo.filter` clearly refers to the filter function in the foo module.

The result

Cross reference documentation of function or class in Sphinx for Python

1 Answers1