How would I cross-reference a function generated by autodoc in Sphinx?
Question:
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)
Answers:
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).
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.
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)
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).
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.