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 <rep...@bugs.python.org>
<http://bugs.python.org/issue16568>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
