sphinx naming special-members

Question

This is my first time using Sphinx and I have figured out a lot so far but there is one particular Warning I am getting that I can't figure out what it is telling me.

According to the documentation on http://www.sphinx-doc.org/en/stable/ext/autodoc.html, Python “special” members (that is, those named like special) will be included if the special-members flag option is given:

.. autoclass:: my.Class
    :members:
    :private-members:
    :special-members:

would document both “private” and “special” members of the class. New in version 1.1. Changed in version 1.2: The option can now take arguments, i.e. the special members to document.

I am trying to list the __init__ of a class in my documentation but no other special members so my .rst file is this:

**myClass Class**
==================

.. automodule:: python_module.submodule.series.myClass
    :members:

    .. autoclass:: myClass
        :members:
        :special-members: __init__

I am getting the error ".rst:7: WARNING: missing attribute :special-members: init in object python_module.submodule.series.myClass.myClass

I am using sphinx version 1.5.1 so shouldn't this work as I've passed it the name of the special member I want to document? The error makes it seem like I am missing something from my .py file I am pulling docstrings from. Is that the case? I can't find any mention of anything special needing to be present in the method if I want to do this.

Answer 1

Be aware that if you are talking about a Class, you should use:

.. autoclass:: MyClass
   :members:

   .. automethod:: __init__

If you are talking about a module that contains your class and other stuff, use:

.. automodule:: mymodule
   :members:
   :special-members: __init__

Note that this will document all init methods found on the module.

If you use both, then your MyClass.init method will be documented twice:

.. automodule:: mymodule
       :members:
       :special-members: __init__

.. autoclass:: MyClass
   :members:

   .. automethod:: __init__

Answer 2

I did found out that the class docstring being repeated twice was because of the ..automodule section. I took it out and it still includes the whole class definition, so that makes me happy.

I still can't get the __init__ definition to be documented using the :special-members: option but this is a negligible problem as the class is documented adequately enough. So I guess I'm just going to allow this warning to stump me... for now.