How would I cross-reference a function generated by autodoc in Sphinx? - python

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.

Related

Sphinx Documentation - Exclude class variables for all the modules in the hierarchy

I'm trying to remove all the class variables from my Sphinx documentation (because I haven't documented them and it doesn't look good if there's only a list of them) for all the classes of my project including the modules in the folders.
Is there an easy way to do it without having to exclude each one of them?
P.S.: I'm a beginner at this, so the answer could be something easy. Also, this could already be answered, but I couldn't find anything.
You can use :no-undoc-members: to tell sphinx to ignore the undocumented (in your case the class) variables.
:undoc-members: (no value)
If set, autodoc will also generate document for the members not having docstrings:
Here is the documentation - https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-option-automodule-undoc-members

Sphinx creates links in variable list to classes with the same names

I'm using Sphinx's apidoc extension to produce documentation for a Python project. It's somewhat quirkier than I had expected, but I've gotten most things to work. However, one quirk has me stumped.
I've got a couple of classes with docstrings that include something like this:
"""
:ivar normal_attr1: This is a normal attribute.
:ivar doppleganger: This is an attribute with the same name as a class in
another module.
""""
Sphinx is automatically adding a link from "doppleganger" to the class whose name it shares--and I can't find a way to stop it. In ordinary circumstances, I'd just change one of the names, but unfortunately, both names are are from code autogenerated from an XSD specification that I'm not at liberty to change.
Is there any easy way to stop these links from being inserted?

How to link to a function read in with automodule in Sphinx [duplicate]

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.

Can sphinx-apidoc include explicit docs for superclass methods?

I'm considering Sphinx for documenting Python projects. I'd like the api docs for a class to contain docs for all of the methods that can be called from the class. The default behavior seems to be to provide a links to superclasses. Thus to see all callable methods I have to click back through the inheritance tree. Docs I've seen produced by (I think) javadoc or doxygen show at least the names of all methods that can be called.
Is it possible in sphinx to display docs for local methods, and at least the names of methods defined in superclasses? To me this is desirable. Is there some reason that what I want is not such a good idea? Is there some alternative approach from within Sphinx?
Plan B will be to explore Pydoctor. Any suggestions for a Plan C, D, ... ?

Python, Sphinx: display superclasses

I've given RTFM a shot, but Sphinx is a big package, and I have a specific question.
I'm looking at docs for an open source project that were generated by Sphinx. The one thing that would be useful for me right now is to see for each class the list of parent classes up to the top level. I'm used to seeing this in java docs. The current docs show only the parent one generation higher. I've notice that Sphinx has automodule and show_inheritance, but it's not clear that this is what I want, nor is it clear how to mod the existing source to use it.
How can I display the parent class hierarchy? Is there some other means to walk an entire python module and display the entire class hierarchy?

Categories

Resources