New submission from Chris Jerdonek:

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.

assignee: docs@python
components: Documentation
messages: 176524
nosy: chris.jerdonek, docs@python, ezio.melotti, ncoghlan
priority: normal
severity: normal
status: open
title: allow constructors to be documented separately from class
type: enhancement

Python tracker <>
Python-bugs-list mailing list

Reply via email to