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.
Related
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'm using autodoc to document some classes and so far, :members:, :private-members:, and :special-members: get me exactly what I want. However, I would also like to see members that are inherited.
There is an additional option, :inherited-members:, which gives me all those things I want... And a bunch of other crap I don't want, because it shows members inherited from Object.
Is there a way to get it to ignore members inherited from certain parents, or to only follow the inheritance chain as far up as my own defined classes, not ones that are built-in?
It'll be possible in Sphinx 3: https://github.com/sphinx-doc/sphinx/issues/5923
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, ... ?
I have found much use of using setattr() to make dynamically generated class methods and attributes. I have also been using sphinx to create documentation, which is fantastic.
The problem is that i cannot use the autosummary feature of sphinx if the attributes and methods are dynamic. Is there a clever way to do this? The dynamic methods and attributes are created upon initialization.
Try this (it's a little wacky):
Create an instance of your class in your conf.py file.
Use the autodoc-process-docstring event to fire a handler (which you will need to write) to copy the __doc__ elements for the various dynamic methods from the instance you created in 1) into the output for the class.
It's not a simple solution, nor easy, and heck, maybe not even possible, but it Just Might Work if you can figure out how to get things to happen at thw right time.