1

I want to include the docstrings for __init__() in my sphinx-generated documentation.

I was following the accepted answer to this stackoverflow question to add a handler for autodoc-skip-member and was still unable to see my __init__() documentation. Trace code inside the if name == "__init__": block shows I am hitting that code.

On a hunch I removed 'sphinx.ext.napoleon' from my extensions definition, leaving

extensions = [
    'sphinx.ext.autodoc',
    # 'sphinx.ext.napoleon',
]

and then I can see the __init__() documentation.

The only thing I see in the napoleon documentation that seems relevant is napoleon_include_special_with_doc, which it says defaults to True. Explicitly setting it to True in conf.py doesn't seem to change anything.

ETA: If I add the following method:

def __blah__(self):
    '''blah blah blah'''
    print self.__class__

I see __blah__() in my generated documentation.

  • If I change the name of __blah__ to __repr__ or __str__, I see them in the generated documentation.
  • If I comment out the existing __init__ and change __blah__ to __init__ I don't see it.

So it seems specific to __init__().

Is this a known issue, and is there another way to control this when using napoleon?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Scott
  • 1,247
  • 3
  • 10
  • 21

2 Answers2

0

Napoleon defers to your autodoc configuration for how you want to handle the __init__ method.

Check your autodoc settings in conf.py. In particular, make sure autoclass_content is set to either init or both.

Rob Ruana
  • 21
  • 4
  • Thanks for the quick reply, Rob. I'm pretty sure autoclass_content isn't the difference. What I was trying to do is put the class documentation under the class, and then have __init__() appear as a method just like __repr__() or __str__() or any other method, with its own documentation. autoclass_content = 'both' just adds the __init__() documentation to the class documentation without calling out __init__() as a separate function. autoclass_content = 'init' uses the __init__() documentation as the entirety of the class documentation, and also omits __init__() as a separate function. – Scott Mar 28 '16 at 21:52
0

Per Rob's followon at https://github.com/sphinx-doc/sphinx/issues/2374, if you're using any extension that also sets a handler for the "autodoc-skip-member" event only one of the handlers will be used. This would seem to be the issue at hand. Thanks Rob!

Scott
  • 1,247
  • 3
  • 10
  • 21