How can I generate documentation for a Python property setter using Sphinx?

Question

I have a Python class something like the following, with docstrings intended to be converted into documentation by Sphinx:

class Direction(object):
    """
    A direction in which movement can be made.
    """
    def __init__(self):
        self._name = None

    @property
    def name(self):
        """
        The unique name of the direction.

        :return: The direction name
        :rtype: string
        """
        return self._name

    @name.setter
    def name(self, value):
        """
        Sets the direction name.

        :param string value: The direction name
        """
        self._name = value

The Sphinx output looks something like this:

class Direction(name) A direction in which movement can be made.

name The unique name of the direction.

Returns: The direction name

Return type: string

which is fine as far as it goes, but note the complete absence of any information about the name setter.

Is there any way to get Sphinx to generate documentation for the property setter?

It seems like it'd make more sense to document any special get/set behavior in the getter documentation if that's where Sphinx looks for it. Your documentation for the setter here is basically superfluous: it's a property, so it obviously sets the value, and documenting the parameter is also needless because every setter requires the same argument, and the setter won't actually be called explicitly. Special get/set behavior is really a characteristic of the property as a whole. The point of properties is they're accessed via a single attribute name, not separate get/set function calls. — BrenBarn, Jul 04 '13 at 21:04
@BrenBarn I can certainly do that if that's what Sphinx is expecting. However, the generated documentation doesn't actually indicate that it's a property and I'm not sure how I can use the `:param:`, `:return:` and `:rtype:` tags to make this clear? — Matthew Murdoch, Jul 04 '13 at 21:12
@MatthewMurdoch, Sphinx documents the getter without using `()`. This, along with your combined docstring, should help the user understand that it's a property. — Asclepius, Jul 05 '13 at 21:49

score 26 · Accepted Answer · answered Jul 08 '13 at 08:28

Sphinx ignores docstrings on property setters so all documentation for a property must be on the @property method.

Whilst Sphinx understands certain specific tags (e.g. :param ...:) it will accept any custom tags and will render them as labels for the text which follows them.

Therefore something like the following will render the documentation in a reasonable way (getter, setter and type can be changed to any other text if required).

@property
def name(self):
    """
    The unique name of the direction.

    :getter: Returns this direction's name
    :setter: Sets this direction's name
    :type: string
    """
    return self._name

The generated documentation looks something like this:

class Direction(name) A direction in which movement can be made.

name The unique name of the direction.

Getter: Returns this direction's name

Setter: Sets this direction's name

Type: string

Thanks to @BrenBarm and @A-B-B for pointing me in the direction of this solution.

How can I generate documentation for a Python property setter using Sphinx?

1 Answers1