Let's say we have the following module testmodule.py
with a TestClass
definition:
"""This is a test module"""
class TestClass:
"""
This is a simple description.
Attributes
----------
egg : int
An egg. Should be from a chiken.
animal : str
The animal that laid the egg.
"""
def __init__(self, egg, animal):
self.animal = animal
if self.is_chicken(animal):
self.egg = egg
else:
self.egg = 0
def is_chicken(self, animal):
"""Checks if the animal is a chicken.
Returns True if it is, False otherwise
Parameters
----------
animal : str
An animal that lays eggs
Returns
-------
bool
True if `animal` is chicken. False otherwise.
"""
if animal == 'chicken':
return True
else:
return False
Using Sphinx 3.5.4 with autodoc
and napoleon
extensions, and pydata_sphinx_theme
as the theme in conf.py
, I get the doc for the class shown below.
I used .. automodule:: testmodule
in a test.rst file, that index.rst references, with :member:
and :show-inheritance:
.
But I would actually like something more like Scipy has for the attributes.
The closest I can get is by setting napoleon_use_ivar = True
in conf.py
, which outputs something close, except that we get "Variables" instead of "Attributes" and the definition is inlined with the attribute name and type.
To get the desired output, instead of using
sphinx.ext.napoleon
, usenumpydoc
. It has to be loaded aftersphinx.ext.autodoc
, according to the Matplotlib conf.py file.Additionally, since no summary table of the methods is desired, simply set
numpydoc_show_class_members
toFalse
.I was having another issue where multiple descriptions for parameters and attributes appeared. Turns out, it's because I was documenting them by hand in the class docstring but also using type-hints (for static type checking with
pyright
) andautodoc_typehints
was set todocument
. This wasn't an issue when using sphinx napoleon, because it is implemented according to this sphinx napoleon RTD. But there is an open issue innumpydoc
since 2019 to allow for type annotations. So the workaround is to setautodoc_typehints
either tonone
or tosignature
.In summary, in the
conf.py
file set:And we get:
Now I just have to figure out how to keep the new lines between the attribute type and its description in pdf documents...