documenting instance attributes

[Joshua Bronson]

I'd like to be able to associate a docstring with an instance
attribute in such a way that autodoc will discover it along with the
rest of the documentation for the class's properties, methods, and
class attributes. I went out on a limb and tried the following:

class Foo:
def __init__(self):
#: i can haz instance attribute docstring?
self.bar = 1

but as I expected, it didn't work. I could make properties out of my
attributes just for this purpose, but of course I'd rather not have
to.

Is there some way to do this? If not, would it be possible to add this
feature?

Thanks,
Josh

[Georg Brandl]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Joshua Bronson schrieb:

I think I will add it, since adding attributes in __init__ is a very
common pattern. I've added http://bitbucket.org/birkenfeld/sphinx/issue/280/
so that I don't forget about it. :)

cheers,
Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.13 (GNU/Linux)

iEYEARECAAYFAkr5JPsACgkQN9GcIYhpnLABmgCfe5dVtarG3QS9yX6S3HspUAeU
qvIAoIJsP9b5gOMR1THWom3xMm4TSarK
=c2pN
-----END PGP SIGNATURE-----

[Edward Z. Yang]

Excerpts from Joshua Bronson's message of Mon Nov 09 17:31:47 -0500 2009:

> class Foo:
> def __init__(self):
> #: i can haz instance attribute docstring?
> self.bar = 1

The way I currently work around this is as follows:

class Foo:
#: yes can haz instance attribute docstring
bar = None
def __init__(self):
self.bar = 1

Cheers,
Edward

[Christophe de VIENNE]

Another simple way is to document explicitely the attribute in the class docstring :

class Foo:
    """.. attribute bar::
           A nice doc

    """"
    def __init__(self):
        self.bar = 1

My 2 cents

Christophe

2009/11/10 Edward Z. Yang <edwar...@thewritingpot.com>

[Joshua Bronson]

Thanks for the replies. I'll be following http://bitbucket.org/birkenfeld/sphinx/issue/280/
:)

I'd prefer Christophe's method to Edward's because it doesn't require
changing (obscuring?) your code to add your documentation, but I
couldn't get Christophe's method to work. No warnings generated or
anything, just nothing rendered for that attribute. Can anyone else
confirm whether .. attribute bar:: works?

[Guenter Milde]

On 2009-11-09, Joshua Bronson wrote:

> I'd like to be able to associate a docstring with an instance
> attribute in such a way that autodoc will discover it along with the
> rest of the documentation for the class's properties, methods, and
> class attributes.

The following is the convention used in the Docutils sources. I don't know
whether it currently works, but it might be worth considering::

class Foo:
parrot = "dead"
"""class attribute docstring"""

def __init__(self):
self.bar = 1

"""instance attribute docstring"""

Proper working would require to reassign the instance attribute docstring from
Foo.__init__ to Foo...

Günter

[Georg Brandl]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Guenter Milde schrieb:

> On 2009-11-09, Joshua Bronson wrote:
>
>> I'd like to be able to associate a docstring with an instance
>> attribute in such a way that autodoc will discover it along with the
>> rest of the documentation for the class's properties, methods, and
>> class attributes.
>
> The following is the convention used in the Docutils sources. I don't know
> whether it currently works, but it might be worth considering::
>
> class Foo:
> parrot = "dead"
> """class attribute docstring"""
>
> def __init__(self):
> self.bar = 1
> """instance attribute docstring"""

For class attributes it already does, for instance attributes it will work
together with the comment-based approach as soon as I implement issue #280.

Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.13 (GNU/Linux)

iEYEARECAAYFAkr6ficACgkQN9GcIYhpnLDcLACfc8d4lvp80Y+2aTuTtalRaZIB
dpsAnRQIDIg+tbKXfvRRDw/UkQyTopWy
=VXMl
-----END PGP SIGNATURE-----

[Christophe de VIENNE]

My mistake, it's :

.. attribute:: bar
    your doc

2009/11/11 Joshua Bronson <jabr...@gmail.com>

[Joshua Bronson]

Of course, I should have figured that out! Works now, thanks :)

[Edward Z. Yang]

Excerpts from Joshua Bronson's message of Tue Nov 10 19:34:32 -0500 2009:

> I'd prefer Christophe's method to Edward's because it doesn't require
> changing (obscuring?) your code to add your documentation, but I
> couldn't get Christophe's method to work. No warnings generated or
> anything, just nothing rendered for that attribute. Can anyone else
> confirm whether .. attribute bar:: works?

I'd like to point out one small thing, which is that if you set
defaults in the class definition, it's much easier to introspectively
determine what props a class will have without having to instantiate it.

That said, I'm all in favor more options.

Cheers,
Edward

[George Sakkis]

On Nov 12, 7:28 pm, Joshua Bronson <jabron...@gmail.com> wrote:

> Of course, I should have figured that out! Works now, thanks :)
>
> On Wed, Nov 11, 2009 at 4:35 AM, Christophe de VIENNE

> <cdevie...@gmail.com>wrote:

>
> > My mistake, it's :
>
> > .. attribute:: bar
> >     your doc
>

> > 2009/11/11 Joshua Bronson <jabron...@gmail.com>

>
> >> Thanks for the replies. I'll be following
> >>http://bitbucket.org/birkenfeld/sphinx/issue/280/
> >> :)
>
> >> I'd prefer Christophe's method to Edward's because it doesn't require
> >> changing (obscuring?) your code to add your documentation, but I
> >> couldn't get Christophe's method to work. No warnings generated or
> >> anything, just nothing rendered for that attribute. Can anyone else
> >> confirm whether .. attribute bar:: works?

Is the ".. attribute:: foo" directive supposed to work within
docstrings ? It doesn't work for me. For now I'm using ":ivar foo:".

By the way, is there a difference among var, ivar, cvar ? In Epydoc
they're different but in Sphinx they all show up as "Variable".

George

[Georg Brandl]

Am 21.12.2009 10:59, schrieb George Sakkis:
> On Nov 12, 7:28 pm, Joshua Bronson <jabron...@gmail.com> wrote:
>
>> Of course, I should have figured that out! Works now, thanks :)
>>
>> On Wed, Nov 11, 2009 at 4:35 AM, Christophe de VIENNE
>> <cdevie...@gmail.com>wrote:
>>
>> > My mistake, it's :
>>
>> > .. attribute:: bar
>> > your doc
>>
>> > 2009/11/11 Joshua Bronson <jabron...@gmail.com>
>>
>> >> Thanks for the replies. I'll be following
>> >>http://bitbucket.org/birkenfeld/sphinx/issue/280/
>> >> :)
>>
>> >> I'd prefer Christophe's method to Edward's because it doesn't require
>> >> changing (obscuring?) your code to add your documentation, but I
>> >> couldn't get Christophe's method to work. No warnings generated or
>> >> anything, just nothing rendered for that attribute. Can anyone else
>> >> confirm whether .. attribute bar:: works?
>
> Is the ".. attribute:: foo" directive supposed to work within
> docstrings ? It doesn't work for me. For now I'm using ":ivar foo:".

It should work in docstrings of classes. How exactly does your
markup look and what do you get?

> By the way, is there a difference among var, ivar, cvar ? In Epydoc
> they're different but in Sphinx they all show up as "Variable".

Sphinx does treat them equally, yes.

Georg

[Fernando Perez]

Howdy,

On Tue, Nov 10, 2009 at 7:57 AM, Edward Z. Yang
<edwar...@thewritingpot.com> wrote:
> The way I currently work around this is as follows:
>
> class Foo:
>  #: yes can haz instance attribute docstring
>  bar = None

Sorry to be dense: does this require something special to be toggled
in sphinx, conf.py or somewhere else? I just tried adding such '#:'
comment markers to ipython's sources, but I'm still not seeing any
special info in the generated API docs. Is it supposed to work 'out
of the box'?

For reference, I'm using sphinx from hg (just rebuilt now).

Thanks

f

[Fernando Perez]

Hi,

On Mon, Jan 4, 2010 at 2:32 PM, Edward Z. Yang <ezy...@mit.edu> wrote:
>
>
> My impression is that this should happen by default. You are using the
> autodoc sphinx extension, correct?

no, we have in ipython our own little script that auto-generates reST
files for all the IPython tree (I've posted it here before since some
people have wanted to have full API doc generation). The snippet it
produces looks like this:

.. AUTO-GENERATED FILE -- DO NOT EDIT!

core.application
================

Module: :mod:`core.application`
-------------------------------
Inheritance diagram for ``IPython.core.application``:

.. inheritance-diagram:: IPython.core.application
:parts: 3

.. automodule:: IPython.core.application

.. currentmodule:: IPython.core.application

Classes
-------

:class:`Application`
~~~~~~~~~~~~~~~~~~~~

.. autoclass:: Application
:members:
:undoc-members:
:show-inheritance:
:inherited-members:

.. automethod:: __init__

### ETC...

That 'Application' class is the one where I tried using #: comments
and failed. Since I control that script, I can make it generate
anything I want; is there something I can add to that so #: works?

Thanks for any help,

f

[Fernando Perez]

On Mon, Jan 4, 2010 at 3:45 PM, Edward Z. Yang <ezy...@mit.edu> wrote:
>
>
> What version of Sphinx are you using?

hg from just right now (I updated from trunk before posting to make
sure I had the latest)

Cheers,

f

[Edward Z. Yang]

Excerpts from Fernando Perez's message of Mon Jan 04 17:23:16 -0500 2010:

> Howdy,
>
> On Tue, Nov 10, 2009 at 7:57 AM, Edward Z. Yang
> <edwar...@thewritingpot.com> wrote:
> > The way I currently work around this is as follows:
> >
> > class Foo:
> >  #: yes can haz instance attribute docstring
> >  bar = None
>
> Sorry to be dense: does this require something special to be toggled
> in sphinx, conf.py or somewhere else? I just tried adding such '#:'
> comment markers to ipython's sources, but I'm still not seeing any
> special info in the generated API docs. Is it supposed to work 'out
> of the box'?

My impression is that this should happen by default. You are using the
autodoc sphinx extension, correct?

Cheers,
Edward

[Edward Z. Yang]

Excerpts from Fernando Perez's message of Mon Jan 04 18:28:49 -0500 2010:

> On Mon, Jan 4, 2010 at 2:32 PM, Edward Z. Yang <ezy...@mit.edu> wrote:
> > My impression is that this should happen by default. You are using the
> > autodoc sphinx extension, correct?
>
> no, we have in ipython our own little script that auto-generates reST
> files for all the IPython tree (I've posted it here before since some
> people have wanted to have full API doc generation). The snippet it
> produces looks like this:

What version of Sphinx are you using?

Cheers,
Edward