This issue is to settle on and provide a way to document the constructor of a class separately from the overall summary/description of a class.

This is something that Ezio, Nick, and I discussed briefly on IRC a few hours ago.  We all see the value in it.

Currently, Sphinx's "class" directive is used in many places to document the constructor of a class.  One drawback of this approach is that linking to the class using the :class: role links to the constructor as opposed to the class summary.  As a result, in many cases the class description needs to be added before the class directive, and a second link needs to be created and used for the overall description.

One way to address this would be to create a new "constructor" directive similar to directives like method, classmethod, and staticmethod.  The constructor documentation could then be hyperlinked to using a new :constructor: role (or perhaps :ctor: to go with the pattern of 4-letter roles).  The class summary could then go immediately after the class directive, with the constructor directive following, as follows:

.. class:: Foo

   Description of Foo.

   .. constructor:: Foo(bar=1)
   
      Return a Foo.

This could render as--

class **Foo**

   Description of Foo.
   
   *constructor* **Foo**(bar=1)

      Return a Foo.

It is possible that something similar could be achieved by abusing the method directive for constructors and linking to them using :meth:`~Foo.Foo`, but that wouldn't be ideal in a few respects.

Nick also raised a related issue for base classes, etc.  I will let him speak to that issue, which might be best as part of another new issue.

I was wondering if this should be called initializer instead of constructor.  Another idea is to keep using the "method" directive and use :initializer: to differentiate it from the others.  This might be easier to implement, but OTOH is not consistent with the staticmethod and classmethod directives though.

I’m interested in an explanation of the value of doing this.

In the threading docs for example, the classes (i.e. initializers) are documented in one section, with awkward links to “Thread objects”, “Lock objects”, etc.  This felt much more cumbersome to me than more modern class/attribute/method combos.  Isn’t it the simplest thing to document one class, usage, constructors and all attributes, in one place?

On the other hand, I don’t have the view of an outsider anymore, so I can’t say what makes sense / reads better for the doc’s audience (as opposed to doc editors).

This came up while documenting the str type in datamodel.rst (IIRC), and linking to it from functions.rst.

On one hand you want to say what the str type is, on the other hand you want to document the constructor and explain how can you use str() to obtain str objects.
Putting both under the constructor doesn't work too well, especially when there's a lot of text.  Putting the str type description in a plain paragraph before the "class" directive doesn't work too well either, because :class:`str` will link to the constructor documentation.

The idea is to keep the two separate but still provide an easy way to link to the class without missing the general description.

For all the built-in types, I see the value now.

Thinking aloud: Separating the namespaces used by the str and func roles would probably require too many changes in Sphinx.

The current way is to use the function directive to document the class/constructor usage in one place, and use ref to link to the section describing the class.  You can also have the cool class/method combo if you configure the class directive with the noindex option.  Is that not good enough?

> For all the built-in types, I see the value now.

The same applies for non built-in types too though (e.g. http://docs.python.org/3.4/library/collections.html).  The only difference is that the built-in ones have entries in functions.rst and use more links.

> Is that not good enough?

Not really, and creating additional links and suppressing others with :noindex: feels wrong.  The idea is that :class:`str` should just work and link to the right place.