Documenting class attributes with type annotations

Question

I want to autogenerate documentation to my code from docstrings. I have some basic class meant to store some data:

class DataHolder:
    """
    Class to hold some data

    Attributes:
        batch: Run without GUI
        debug (bool): Show debug messages
    """
    batch: bool = False
    debug: bool = False
    name: str = 'default'
    """Object name"""
    version: int = 0
    """int: Object version"""

My rst file:

DataHolder
==========

.. autoclass:: data_holder.DataHolder
   :members:

I have documented each attribute in a different way to show the difference, here is the output:

It seems like Sphinx cannot connect the Attributes section with the real attributes, that's why it cannot display their default value.

The final output I would like to achieve is the outcome as for the version field with the docstring defined as for batch. I want to display the attribute name with default value and type, but taken from type annotations. Looks like Sphinx is ignoring the type annotations in this case.

My sphinx extensions:

extensions = [
    'sphinx.ext.viewcode',
    'sphinx.ext.autodoc',
    'sphinxcontrib.napoleon',
]

What can I do to achieve such behavior? I can't find any good examples for such use case.

What version of Sphinx do you use? As of version 1.3, Napoleon is packaged with Sphinx as `sphinx.ext.napoleon`. See https://pypi.org/project/sphinxcontrib-napoleon/ — mzjn, May 30 '18 at 16:59
I'm using the 1.7, the sphinx.ext.napoleon doesn't change anything. — Djent, May 30 '18 at 19:31
Sorry to be the bearer of bad news but looking at the [source of the napoleon extension](https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/napoleon/docstring.py#L587), it seems like this is not possible. — Jacques Gaudin, Jun 04 '18 at 14:52
You can try `.. autoattribute::`? Look at [this answer](https://stackoverflow.com/a/22768779/2934048) for example. — DalyaG, Jun 23 '18 at 19:51
`:vartype:` seems like a good stopgap for you within the docstring until the type annotations are supported. — Matthew Story, Jun 30 '18 at 06:24

score 2 · Answer 1 · edited Aug 31 '21 at 00:13

I do not think you can put an Attribute section inside of your docstring to get your desired results.

I tried giving each attribute a doc comment and specified the type and desired comment.

class DataHolder:
"""
Class to hold some data

Each attribute needs its own doc comment with its type
"""

#: bool: Run without Gui
batch = False

#: bool: Show debug messages
debug = False

#: str: Object Name
name = 'default'

#: int: Object Version
version = 0

This gives the following output and a nice Type description of each output.

Take a look here:

Please take a look here!

score -2 · Answer 2 · edited Jul 14 '21 at 15:55

-2

class DataHolder:
    """
    Class to hold some data

    Attributes:
        batch: Run without GUI
        debug (bool): Show debug messages
        name: Object name
        version: Object version
    """
    batch: bool = False
    debug: bool = False
    name: str = 'default'
    version: int = 0
    # INLINE COMMENT for ONE line
    """
    DocString as inline-comment I havent seen that yet.
    """

edited Jul 14 '21 at 15:55

deponovo

1,114
7
23

answered Apr 04 '21 at 19:36

Alexander Brockmeier

100
5

12

It's always much better if you can explain your answer, rather than just posting code. It's more helpful to people in the future and more likely to be upvoted. – David Buck Apr 04 '21 at 20:49

Documenting class attributes with type annotations

2 Answers2