Sphinx values for attributes reported as None

Question

When I use Sphinx autodoc to document a class, the values for the attributes are always reported, (as it says it should here, under #437) but always as "= None"

Attribute = None
    Some Documentation

I include it like

.. autoclass:: core.SomeClass
   :members:

And my code looks like

class SomeClass(object):
    def __init__(self):
        self.attribute = "value" #: Some Documentation

Is there a way to either make the "= None" report the real value, or make it disappear?

Here, for example: http://readthedocs.org/docs/domination-game/en/latest/games.html#domination.core.GameStats. It occurs everywhere where I'm using `self.attribute = ...` in combination with `autoclass:: .. :members:` — noio, Feb 14 '12 at 09:46

JonnyJD · Answer 1 · 2013-09-16T09:05:17.143

10

There will be an :annotation: option (see pull-request) in the upcoming version 1.2 of sphinx (and in the second beta).

For autodata/autoattribute you can then force a specific value or suppress it. So in order to print no value for the attribute you would put:

.. autoclass:: core.SomeClass

   .. autoattribute:: attribute
      :annotation:

Currently it only works with autodata/autoattribute directly and not recursively with automodule/autoclass.

edited Sep 16 '13 at 09:05

answered Jan 24 '13 at 13:56

JonnyJD

2,593
1
28
44

1

This appears to only work with class attributes. Tested using Sphinx 1.5.1 – Mike Haboustak Jan 05 '17 at 15:50

score 6 · Accepted Answer · answered Feb 16 '12 at 20:09

6

I am pretty sure this has to do with the fact that your attribute is an instance attribute. It does not get a value until the class is instantiated. Sphinx imports modules in order to inspect them, but it does not instantiate any classes.

So the "real value" is not known by Sphinx, and None is output. I don't think you can make it go away easily (but I suppose anything is possible if you are prepared to patch the Sphinx source code...). If you don't like this, you could document attributes in the docstring of the class instead.

Class attributes that are documented using the same markup scheme (described here) do get their values displayed in the rendered output. But there is no clear indication that makes it easy for the reader to distinguish between class and instance attributes. Maybe Sphinx could be a little more helpful here.

answered Feb 16 '12 at 20:09

mzjn

48,958
13
128
248

I don't think the working hypothesis of this answer is correct. I'm experiencing the problem (i.e. - " = None" showing up in the generated documentation) for class attributes defined and initialized outside of the __init__() function. These are documented, using the "#: ..." comment variant placed after the attribute on the same line. – dbanas Dec 20 '17 at 18:14
Interesting. Do you have a GitHub project or similar where we can look at this? – mzjn Dec 20 '17 at 18:38
Yes: https://github.com/capn-freako/PyBERT/blob/8c63d28220edc000e9503082e05c6257cd9cee7c/pybert/pybert.py#L315 – dbanas Dec 20 '17 at 18:45
Check out the attributes of the PyBERT class like bit_rate, for instance. Note that the comments in this version are not, yet, correct. (They're missing the colon after the pound sign.) I'm working with corrected comments, in my own sandbox, which haven't been pushed, yet. – dbanas Dec 20 '17 at 18:46
Is the rendered PyBERT documentation available online somewhere? Can you provide a [mcve] that does not require me to clone your entire project and install a lot of dependencies? – mzjn Dec 21 '17 at 06:14
HEAD exhibits the problem, while HEAD^ does not. The differences between the two are: HasTraits vs. object as the superclass, and Int vs int as the type of cAtt. – dbanas Dec 21 '17 at 20:27
I can reproduce the problem (cAtt = None in the documentation). I suggest that you post a new question. – mzjn Dec 21 '17 at 20:43
1

Okay, will do. Thanks for your time! Happy holidays. :) – dbanas Dec 21 '17 at 20:50
https://stackoverflow.com/questions/47932680/sphinx-autodoc-incorrectly-assigning-value-none-to-class-attributes-when-trai – dbanas Dec 21 '17 at 21:11

score 2 · Answer 3 · answered Mar 11 '17 at 18:19

For the current version of Sphinx, you can put a monkeypatch in the conf.py of your project that fixes this problem:

from sphinx.ext.autodoc import (
    ClassLevelDocumenter, InstanceAttributeDocumenter)

def iad_add_directive_header(self, sig):
    ClassLevelDocumenter.add_directive_header(self, sig)

InstanceAttributeDocumenter.add_directive_header = iad_add_directive_header

This is discussed in Sphinx issue #2044

score 0 · Answer 4 · answered Sep 01 '16 at 16:16

This still seems to be an issue. I worked around it with:

class ValueDoc:

    def __init__(self, text):
        self.text = text

    def __repr__(self):
        return self.text

And then define the attribute at the class level like:

#: documentation for foo
foo = ValueDoc('text to show up after =')

score 0 · Answer 5 · answered Jan 05 '17 at 15:59

0

I wasn't able to get annotations working for instance attributes. I chose to just hide the attribute values in my theme.

Example html

<dl class="attribute">
  <dt>
    <code class="descName">Attribute</code>
    <em class="property"> = None</em>
  </dt>
</dl>

Theme CSS to hide = None

dd dl.attribute em.property { display: none }

answered Jan 05 '17 at 15:59

Mike Haboustak

2,266
1
18
18

1

There is an undocumented directive called `autoinstanceattribute` that you can try. It is unclear if this directive just needs to be documented or if `autoattribute` really is supposed to also handle instance attributes. See https://github.com/sphinx-doc/sphinx/issues/904#issuecomment-68577602. – mzjn Jan 05 '17 at 16:46
So the `.. autoinstanceattribute` directive with a blank `:annotation:` option does successfully take away the value! It seems this implementation is kind of a mess through 1.5. – Mike Haboustak Jan 05 '17 at 19:51

Sphinx values for attributes reported as None

5 Answers5

Linked