Omitting constructor signature from class header using autoclass

[stefanseefeld]

I'm a bit surprised to see that (in the Python domain)

.. autoclass:: Foo
   ...

will create a heading like class Foo(*args) which seems quite unintuitive to me, as it mixes two concepts: the declaration of "class Foo", with a constructor call "Foo(*args)". How can I suppress the (automatic) addition of the constructor signature to the generated heading ?

I actually want to document the constructor with an additional nested .. automethod:: directive, and I also have an overloaded __call__ method, making the above all the more confusing.

Am I missing or misunderstanding something ?

[tk0miya]

Unfortunately, there are no way to do that. The autoclass directive always shows its signature automatically.

+1: I agree that it is valuable if we can show explanations both of the class and __init__() method independently.

[earshinov]

Can this issue be renamed to smth. like "Omitting constructor signature from class header" ? I had a hard time finding it.

[earshinov]

My use case is documenting a serializer, a class derived from rest_framework.serializers.ModelSerializer.

class OrderSerializer(serializers.ModelSerializer):
  ...

This class is only constructed by the framework, and never constructed by the user, but in my docs I get

class OrderSerializer(instance=None, data=<class 'rest_framework.fields.empty'>, **kwargs)
  ...

There is no way to remove the constructor signature, which is long, ugly, and totally irrelevant for people reading the docs.

[J-M0]

For people coming from Google, I found a workaround that works on Sphinx 1.8 (the default Sphinx on Read the Docs):

.. autoclass:: Foo()

This will override the automatic constructor and not render anything, not even the parenthesis. It's still a little ugly and confusing, but works for now.

[fjarri]

I don't think it works in Sphinx 2+

[shimizukawa]

As a naming suggestion for this option, how about the following name?

autoclass_signature = "mixed"  # default
autoclass_signature = "separated"  # new

or

autodoc_default_options = {
    "class-signature": "mixed",  # default
    "class-signature": "separated",  # new
}

It would be nice to have the ability to override it with autoclass if needed.

.. autoclass:: OrderSerializer
  :class-signature: separated

I don't think the autodoc_default_options or overrides by autoclass are necessary, so I think autoclass_signature is fine.