82

I am using the Sphinx autodoc feature to generate documentation based on the docstrings of my Python library.

The syntax for cross referencing is found here

A label must precede the section in order to allow that section to be referenced from other areas of the documentation.

What I have is a .rst (ReStructeredText) file for one of my classes. It uses

.. autoclass:: classname
    :members:

To generate documentation for the class.

My question is, how would I reference the auto-generated methods of the class from another .rst document in the documentation? If I try to place a label within the method's docstring, Sphinx complains. If I try to place a label before the method heading, Sphinx doesn't recognize it.

Is there a simple way to do this, or will I have to explicitly write in my class file the method name and precede that with a label?

Here is an example a reference within the [Python documentation2 doing what I need (I am assuming it used the autodoc feature, though I don't know for sure)

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Matthew Stamy
  • 1,114
  • 1
  • 7
  • 9
  • 2
    The title asks about *functions*, yet the body and answer about *methods*. I'd hoped there would be an answer for referencing an `.. autofunction::` but alas it's not here. – JFlo Feb 13 '19 at 16:51

2 Answers2

124

You don't need to add labels. In order to refer to a Python class, method, or other documented object, use the markup provided by the Python domain.

For example, the following defines a cross-reference to the mymethod method: 

:py:meth:`mymodule.MyClass.mymethod`

Or even simpler (since the Python domain is the default):

:meth:`mymodule.MyClass.mymethod`

The documentation of TextWrapper.wrap that you link to in the question includes two cross-references of this kind (click on "Show Source" to see the reST markup).

mzjn
  • 48,958
  • 13
  • 128
  • 248
  • 7
    And `:mod:…` for modules. – Gringo Suave Aug 18 '18 at 18:02
  • 38
    And `:func:…` for functions. A complete list of how to cross-reference Python roles is [here](http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects). – JFlo Feb 13 '19 at 17:02
  • 1
    This will only work by accident, if the other module is hosted on readthedocs. If it's hosted elsewhere (which is very likely to happen for anything that has native code dependencies, as those are impossible to host on readthedocs), that's not a solution. – wvxvw Aug 03 '21 at 14:29
  • @wvxvw. What are you talking about? Use intersphinx and if you need to set the domain to something other than `py`, do so. But the basic method works fine. – Mad Physicist Dec 18 '21 at 07:01
  • @MadPhysicist If "by accident" is fine for you, then go ahead and use it... what's the problem? – wvxvw Dec 18 '21 at 12:52
  • @wvxvw. It's not ok. I'm trying to figure out why you're saying it's an accident. It doesn't look like one to me. I've successfully linked to python, numpy and matplotlib, which aren't hosted on rtd... – Mad Physicist Dec 18 '21 at 17:46
  • In order for intersphinx to work the party that's hosting the documentation needs to make provisions for that. Some do. Some don't. In my experience, this method is unreliable (and there isn't, in principle, a reliable way, at least not using Sphinx to do this). – wvxvw Dec 19 '21 at 21:49
  • note that when reference is inside the same class, no need for the `mymodule.myclass` prefix – OrenIshShalom Apr 10 '22 at 12:40
10

In addition to the excellent answer already provided:

To add an alias to the referenced module (method, function, attribute, etc.), the following syntax is used:

:mod:`Alias Name <package.module>`

This will appear as a reference to Alias Name in the docs, and link to the module provided.

S3DEV
  • 8,768
  • 3
  • 31
  • 42