7

Let's say I have a class like this:

class MyClass(object):
    """ Summary docs for my class.

    Extended documentation for my class.
    """

    def __init__(self, *args):
        self.values = np.asarray(args)

If I use Sphinx with the autodoc extension to document this class like so:

.. automodule:: mymodule
   :members:

...the constructor signature appears as MyClass(*args). I would rather override this and document it as, say, MyClass(first, second, third).

If this were a function, I could override the signature in the first line of the docstring. But that trick doesn't seem to work on a class docstring. So how can I override the constructor signature?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
detly
  • 29,332
  • 18
  • 93
  • 152
  • Hiding the real call signature from the users sounds like a bad idea to me. – Lev Levitsky Dec 09 '12 at 09:07
  • 1
    @LevLevitsky - the constructor is always called with a certain number of arguments. Whether it's `*args` or `arg1, arg2, ...` is an implementation detail, and could change at any time. There is no "real" call signature — the user should pass in what is documented as acceptable parameters. – detly Dec 09 '12 at 10:55
  • There is a difference in behavior (towards excessive arguments, for example). – Lev Levitsky Dec 09 '12 at 11:02
  • @LevLevitsky - if someone is using the API in undefined ways (eg. passing in excessive arguments), I don't really care. I certainly don't think it's worth having indirect and confusing documentation. – detly Dec 09 '12 at 11:05

1 Answers1

12

I think that the best option for you is to do something like this:

.. automodule:: mymodule
    :members:
    :exclude-members: MyClass

    .. autoclass:: MyClass(first, second, third)

MyClass will have params overwritten and other members of mymodule will be autodocumented. You need to exclude MyClass using :exclude-members: because it will be included twice. I think it's the simplest solution at the moment.

prmtl
  • 421
  • 5
  • 10