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?
Related
I am using sphinx-autodoc for documenting a class. I want the methods of the class to correspond to individual entries in the Sphinx TOC, so that they each spawn a link in the 'local TOC' sidebar.
How can I achieve this?
AFAICT, the autoclass directive does not support this. I tried to use autosummary, but I can't get that one to work either: it wants the individual methods in separate .rst files. I would rather have them all on the same page.
I guess I could manually create a section for each member like so:
Foo.bar()
---------
.. automethod:: Foo.bar
But that feels weird and unnecessarily complicated.
I wrote a sphinx plugin called autoclasstoc that does something similar to what you want. The plugin provides a directive that creates a table of links to the documentation for each method of a particular class. The links don't end up in the TOC sidebar, but they still make the class documentation much easier to navigate. It's also worth mentioning that these links can be organized into groups (e.g. public methods, private methods, etc.) and that links to inherited methods are grouped by superclass and collapsed by default.
Even though this doesn't exactly answer your question, it's a good way to achive a similar effect.
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
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?
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.
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.