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 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:
:ivar foo: though, just :var foo will do.
ivar = instance variable, cvar = class variable, var = work it out yourself. While Sphinx doesn't care it informs a human reader.#: doc comments: you can also put doc comments right above variables
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:
Upsides:
Both could be better:
class_var is a class variable? TODO link to feature reuqestclass 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.
