2

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.

boymeetscode
  • 805
  • 1
  • 9
  • 26
  • `python_module.submodule.series.myClass` is not a module, it is a class. I think that you want `.. automodule:: python_module.submodule.series`. – mzjn Feb 14 '17 at 11:03
  • My apologies. myClass is a module, actually. I have a myClass.py file inside of a myClass module. I should have named those things better. The tree structure of modules is the following: python_module->submodule->series->myClass->myClass.py myClass.py contains the class definition and methods used by that class. This is where the __init__ is that is giving me issues with Sphinx. – boymeetscode Feb 14 '17 at 13:31
  • Also, possibly unrelated problem? but my class docstring is being repeated twice right after each other. – boymeetscode Feb 14 '17 at 15:48

2 Answers2

2

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__
Carlos Borau
  • 1,433
  • 1
  • 24
  • 34
0

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.

boymeetscode
  • 805
  • 1
  • 9
  • 26
  • I cannot explain why it does not work for you with `:special-members:`. You might want to try the other options described here: http://stackoverflow.com/a/5599712/407651 – mzjn Feb 14 '17 at 16:58