How to show instance attributes in sphinx doc?

Question

Is there any way to automatically show variables var1 and var2 and their init-values in sphinx documentation?

class MyClass:
    """    
    Description for class
    """

    def __init__(self, par1, par2):
       self.var1 = par1 * 2
       self.var2 = par2 * 2

    def method(self):
       pass

Asked By: Meloun

||

Source

Answer 1

Your variables are instance variables, not class variables.

Without attaching a docstring (or a #: “doc comment”) to the variables, they won’t be documented. You could do as follows:

class MyClass(object):
    """    
    Description for class 

    """

    def __init__(self, par1, par2):
        self.var1 = par1 #: initial value: par1
        self.var2 = par2 #: initial value: par2

    def method(self):
        pass

But I would prefer to include variable documentation by using info fields:

class MyClass(object):
    """    
    Description for class

    :ivar var1: initial value: par1
    :ivar var2: initial value: par2
    """

    def __init__(self, par1, par2):
        self.var1 = par1 
        self.var2 = par2 

    def method(self):
        pass

See also:

Answered By: mzjn

Answer 2

For Python 3.9+ dataclass style classes you can do

@dataclass
class MyClass:

    #: Nice vars!
    var1: int = 0

    #: Life is beautiful, remember to buy flowers for your wife
    var2: int = 0

Here is an link to example Sphinx documentation using dataclass.

Answered By: Mikko Ohtamaa

Answer 3

Doc comments: you can also put doc comments above

Besides the self.var1 = par1 # Doc for var1 syntax you can also:

main.py

class MyOtherClass:
    """
    This class does that.
    """
    pass

class MyClass:
    """
    Description for class.
    """

    #: Syntax also works for class variables.
    class_var: int = 1

    def __init__(self, par1: int, par2: MyOtherClass):
        #: Doc for var1
        self.var1: int = par1

        #: Doc for var2.
        #: Another line!
        self.var2: MyOtherClass = par2

    def method(self):
        """
        My favorite method.
        """
        pass

    @classmethod
    def cmethod():
        """
        My favorite class method.
        """
        pass

build.sh

sphinx-build . out

conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('.'))
extensions = [ 'sphinx.ext.autodoc' ]
autodoc_default_options = {
    'members': True,
}
autodoc_typehints = "description"

index.rst

.. automodule:: main

requirements.txt

Sphinx==6.1.3

After ./build.sh the output under out/index.html looks like:

The #: syntax is documented at: https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directive-autoproperty

Using :ivar: and :cvar: instead

There are currently tradeoffs between both methods, it is a shame that there isn’t one clearly superior method.

Downsides:

you have to type the attribute names again
types are gone, TODO link to feature request

Upsides:

the "Variables:` grouping looks cleaner, TODO link to feature request

Both could be better:

clearly show that class_var is a class variable? TODO link to feature reuqest

class MyClass:
    """
    Description for class.

    :ivar var1: Doc for var1
    :ivar var2: Doc for var2.
      Another line!
    :cvar class_var: Syntax also works for class variables.
    """

    class_var: int

    def __init__(self, par1: int, par2: MyOtherClass):
        self.var1: int = par1

        self.var2: MyOtherClass = par2

    def method(self):
        """
        My favorite method.
        """
        pass

    @classmethod
    def cmethod():
        """
        My favorite class method.
        """
        pass

produces:

Related: What is the difference between var, cvar and ivar in python's sphinx?

Tested on Python 3.10, Ubuntu 22.10.

Answered By: Ciro Santilli OurBigBook.com

How to show instance attributes in sphinx doc?

Question:

Answers: