autosummary -- does not understand module level datas/attributes #344

shimizukawa · 2015-01-02T17:17:22Z

Let's take following code:

#!python

"""Submodule"""
class SomeOther(object):
    """Some other class"""
    pass

ATTRIBUTE_OF_SUBMODULE = True
"""This is attribute of submodule, of type boolean"""

OTHER_ATTRIBUTE_OF_SUBMODULE = SomeOther()
"""This is *other* attribute of type :class:`SomeClass`"""

Now if I do autosummary for the module like this:

.. automodule:: submodule

.. autosummary::

    ATTRIBUTE_OF_SUBMODULE
    OTHER_ATTRIBUTE_OF_SUBMODULE
    SomeOther

Autosummary table contains incorrect entries for attributes/datas of module:

ATTRIBUTE_OF_SUBMODULE  bool(x) -> bool 
OTHER_ATTRIBUTE_OF_SUBMODULE    Some other class

Underlying autodocumentor in other hand works correctly, since directive autodata gets the documentation string from attributes/datas of module correctly.

Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/344
Originally reported by: ciantic
Originally created at: 2010-02-27T11:13:31.144

The text was updated successfully, but these errors were encountered:

shimizukawa · 2015-01-02T17:17:24Z

From Fergus Noble on 2012-11-15 07:32:10+00:00

Can confirm this issue in version 1.1.3 and would also be interested in seeing a resolution.

shimizukawa · 2015-01-02T17:17:24Z

From Georg Brandl on 2013-03-31 13:57:37+00:00

Removing version: 0.6.3 (automated comment)

shimizukawa · 2015-01-02T17:17:25Z

From Marcel Stimberg on 2013-05-16 11:58:23+00:00

Everyone interested in this issue may have a look at pull request #142 where I tried to address it. Comments welcome!

mstimberg · 2015-08-14T12:52:34Z

I think this issue is obsolete now, it has been fixed with the fix for issue #1444 and can therefore be closed.

KelSolaar · 2018-02-02T07:57:01Z

#1444 might fix the issue for classes but I unfortunately still have the issue for module attributes, :automodule: gives correct output for reference.

A mediocre workaround I found is to forcibly set the __doc__ field, e.g.:

CHROMATIC_ADAPTATION_TRANSFORMS = CaseInsensitiveMapping({
    'XYZ Scaling': XYZ_SCALING_CAT,
    'Von Kries': VON_KRIES_CAT,
    'Bradford': BRADFORD_CAT,
    'Sharp': SHARP_CAT,
    'Fairchild': FAIRCHILD_CAT,
    'CMCCAT97': CMCCAT97_CAT,
    'CMCCAT2000': CMCCAT2000_CAT,
    'CAT02': CAT02_CAT,
    'CAT02_BRILL_CAT': CAT02_BRILL_CAT,
    'Bianco': BS_CAT,
    'Bianco PC': BS_PC_CAT
})
CHROMATIC_ADAPTATION_TRANSFORMS.__doc__ = """
Supported chromatic adaptation transforms.

CHROMATIC_ADAPTATION_TRANSFORMS : CaseInsensitiveMapping
    **{'CAT02', 'XYZ Scaling', 'Von Kries', 'Bradford', 'Sharp', 'Fairchild,
    'CMCCAT97', 'CMCCAT2000', 'CAT02_BRILL_CAT', 'Bianco', 'Bianco PC'}**
"""

This is very limited because quite a lot of Python objects have read-only __doc__ attribute and it will then break :automodule:.

Here is a playground zip file to test all that: https://drive.google.com/file/d/1469JtgHLunCYud8DHWvgBofFYQ1qwpG6/view?usp=sharing

tk0miya · 2018-02-02T16:03:31Z

@KelSolaar what version of sphinx do you use? Latest Sphinx considers the string after assignment is a docstring of the variable.

KelSolaar · 2018-02-02T19:33:20Z

I was using 1.5.7, upgraded to 1.6.6 and it breaks:

(colour-2.7) Kali:autosummary kelsolaar$ rm -rf _build/ generated && make html
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.6.6
making output directory...
loading pickled environment... not yet created
[autosummary] generating autosummary for: doe.rst, index.rst
[autosummary] generating autosummary for: /Users/kelsolaar/Downloads/autosummary/generated/doe.rst, /Users/kelsolaar/Downloads/autosummary/generated/john.bar.rst, /Users/kelsolaar/Downloads/autosummary/generated/john.foo.rst
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 2 source files that are out of date
updating environment: 5 added, 0 changed, 0 removed
reading sources... [100%] index
/Users/kelsolaar/Downloads/autosummary/doe.rst:4: WARNING: autodoc: failed to import data u'foo' from module u'doe'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 666, in import_object
    logger.debug('[autodoc] => %r', obj)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1440, in debug
    self.logger.debug(msg, *args, **kwargs)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1155, in debug
    self._log(DEBUG, msg, args, **kwargs)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1285, in _log
    record = self.makeRecord(self.name, level, fn, lno, msg, args, exc_info, func, extra)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1259, in makeRecord
    rv = LogRecord(name, level, fn, lno, msg, args, exc_info, func)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 264, in __init__
    and args[0]):
TypeError: __len__() takes exactly 2 arguments (1 given)
/Users/kelsolaar/Downloads/autosummary/doe.rst:4: WARNING: autodoc: failed to import data u'bar' from module u'doe'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 666, in import_object
    logger.debug('[autodoc] => %r', obj)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1440, in debug
    self.logger.debug(msg, *args, **kwargs)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1155, in debug
    self._log(DEBUG, msg, args, **kwargs)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1285, in _log
    record = self.makeRecord(self.name, level, fn, lno, msg, args, exc_info, func, extra)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1259, in makeRecord
    rv = LogRecord(name, level, fn, lno, msg, args, exc_info, func)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 264, in __init__
    and args[0]):
TypeError: __len__() takes exactly 2 arguments (1 given)
/Users/kelsolaar/Downloads/autosummary/generated/john.bar.rst:6: WARNING: autodoc: failed to import data u'bar' from module u'john'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 666, in import_object
    logger.debug('[autodoc] => %r', obj)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1440, in debug
    self.logger.debug(msg, *args, **kwargs)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1155, in debug
    self._log(DEBUG, msg, args, **kwargs)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1285, in _log
    record = self.makeRecord(self.name, level, fn, lno, msg, args, exc_info, func, extra)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1259, in makeRecord
    rv = LogRecord(name, level, fn, lno, msg, args, exc_info, func)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 264, in __init__
    and args[0]):
TypeError: __len__() takes exactly 2 arguments (1 given)
/Users/kelsolaar/Downloads/autosummary/generated/john.foo.rst:6: WARNING: autodoc: failed to import data u'foo' from module u'john'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 666, in import_object
    logger.debug('[autodoc] => %r', obj)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1440, in debug
    self.logger.debug(msg, *args, **kwargs)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1155, in debug
    self._log(DEBUG, msg, args, **kwargs)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1285, in _log
    record = self.makeRecord(self.name, level, fn, lno, msg, args, exc_info, func, extra)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1259, in makeRecord
    rv = LogRecord(name, level, fn, lno, msg, args, exc_info, func)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 264, in __init__
    and args[0]):
TypeError: __len__() takes exactly 2 arguments (1 given)
/Users/kelsolaar/Downloads/autosummary/index.rst:12: WARNING: autodoc: failed to import data u'foo' from module u'john'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 666, in import_object
    logger.debug('[autodoc] => %r', obj)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1440, in debug
    self.logger.debug(msg, *args, **kwargs)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1155, in debug
    self._log(DEBUG, msg, args, **kwargs)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1285, in _log
    record = self.makeRecord(self.name, level, fn, lno, msg, args, exc_info, func, extra)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1259, in makeRecord
    rv = LogRecord(name, level, fn, lno, msg, args, exc_info, func)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 264, in __init__
    and args[0]):
TypeError: __len__() takes exactly 2 arguments (1 given)
/Users/kelsolaar/Downloads/autosummary/index.rst:12: WARNING: failed to import object john.foo
/Users/kelsolaar/Downloads/autosummary/index.rst:12: WARNING: autodoc: failed to import data u'bar' from module u'john'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 666, in import_object
    logger.debug('[autodoc] => %r', obj)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1440, in debug
    self.logger.debug(msg, *args, **kwargs)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1155, in debug
    self._log(DEBUG, msg, args, **kwargs)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1285, in _log
    record = self.makeRecord(self.name, level, fn, lno, msg, args, exc_info, func, extra)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 1259, in makeRecord
    rv = LogRecord(name, level, fn, lno, msg, args, exc_info, func)
  File "/usr/local/anaconda3/envs/colour-2.7/lib/python2.7/logging/__init__.py", line 264, in __init__
    and args[0]):
TypeError: __len__() takes exactly 2 arguments (1 given)
/Users/kelsolaar/Downloads/autosummary/index.rst:12: WARNING: failed to import object john.bar
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex py-modindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 8 warnings.

KelSolaar · 2018-02-02T19:52:38Z

I quickly commented the conditional block in python2.7/logging/__init__.py to have the build passing and still same output :autosummary: does not use the docstrings:

Autosummary

Automodule

KelSolaar · 2018-02-02T20:01:03Z

The same exception is raised by 1.7.0b2, performing the build by commenting the conditional block in python2.7/logging/__init__.py unfortunately yields same output:

Autosummary

tk0miya · 2018-02-03T12:19:49Z

It seems data.Data.__len__() is invalid. why does it requires an argument? And why not returns length?

    def __len__(self, item):

        pass

tk0miya · 2018-02-03T12:27:20Z

I quickly commented the conditional block in python2.7/logging/init.py to have the build passing and still same output :autosummary: does not use the docstrings:

Oh, sorry. I'd confused with autodoc. certainly autosummary does not refer the docstring.

KelSolaar · 2018-02-03T20:56:03Z

@tk0miya : Ah good catch, it is when I created the example, I copy-pasted the __contains__ method to generate the missing methods. I have updated my example, __iter__ was also broken.

I'm having issues trying to document attributes that are directly defined from dict:

Kali:autosummary kelsolaar$ make html
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.5.6
making output directory...
loading pickled environment... not yet created
[autosummary] generating autosummary for: doe.rst, generated/doe.rst, generated/john.bar.rst, generated/john.foo.rst, generated/john.the_dict.rst, index.rst
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 6 source files that are out of date
updating environment: 6 added, 0 changed, 0 removed
reading sources... [100%] index
/Users/kelsolaar/Downloads/autosummary/john.py:docstring of john.the_dict:3: ERROR: Unexpected indentation.
/Users/kelsolaar/Downloads/autosummary/john.py:docstring of john.the_dict:4: WARNING: Block quote ends without a blank line; unexpected unindent.
/Users/kelsolaar/Downloads/autosummary/john.py:docstring of john.the_dict:7: ERROR: Unexpected indentation.
/Users/kelsolaar/Downloads/autosummary/john.py:docstring of john.the_dict:8: WARNING: Inline strong start-string without end-string.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex py-modindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 4 warnings.

Build finished. The HTML pages are in _build/html.

I have started to pepper my code with explicit assignments to __doc__ but cases like above or even documenting float/numeric constants make this really painful if possible at all.

Is autosummary support for docstring something you are planning to implement?

tk0miya · 2018-02-04T16:54:27Z

Not planned. I just realized this problem at your comment. So I tagged this as a task for 1.8. But I'm beginner of autosummary, so I can't say it will be fixed in 1.8.

KelSolaar · 2018-02-05T06:39:20Z

Thanks @tk0miya! I found a related problem that I will document in another issue.

tk0miya · 2018-07-21T16:53:28Z

Sorry for very late. I just made a PR #5204 for this.
If you still have interested, please try it :-)

Note: It supports docstring of module attributes. But it can't handle imported one. So doe.foo is okay, but john.foo is not in above case.

…tring_of_modattrs Fix #344: autosummary does not understand docstring of module level attributes

tk0miya · 2018-07-23T15:11:40Z

Merged. It will be released as 1.8.
Thanks,

shimizukawa added this to the some future version milestone Jan 2, 2015

shimizukawa added type:enhancement extensions:autodoc labels Jan 2, 2015

chadwhitacre mentioned this issue Aug 17, 2015

No settings for displaying field attribute documentation readthedocs/readthedocs.org#632

Closed

tk0miya modified the milestones: some future version, 1.6.7 Feb 2, 2018

tk0miya modified the milestones: 1.6.7, 1.8, 1.7.1 Feb 3, 2018

tk0miya mentioned this issue Jul 21, 2018

Fix #344: autosummary does not understand docstring of module level attributes #5204

Merged

tk0miya closed this as completed in cfc5632 Jul 23, 2018

tk0miya added a commit that referenced this issue Jul 23, 2018

Merge pull request #5204 from tk0miya/344_autosummary_recognizes_docs…

6b4a4a9

…tring_of_modattrs Fix #344: autosummary does not understand docstring of module level attributes

github-actions bot locked as resolved and limited conversation to collaborators Aug 13, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

autosummary -- does not understand module level datas/attributes #344

autosummary -- does not understand module level datas/attributes #344

shimizukawa commented Jan 2, 2015

shimizukawa commented Jan 2, 2015

shimizukawa commented Jan 2, 2015

shimizukawa commented Jan 2, 2015

mstimberg commented Aug 14, 2015

KelSolaar commented Feb 2, 2018 •

edited

Loading

tk0miya commented Feb 2, 2018

KelSolaar commented Feb 2, 2018

KelSolaar commented Feb 2, 2018

KelSolaar commented Feb 2, 2018

tk0miya commented Feb 3, 2018

tk0miya commented Feb 3, 2018

KelSolaar commented Feb 3, 2018

tk0miya commented Feb 4, 2018

KelSolaar commented Feb 5, 2018

tk0miya commented Jul 21, 2018

tk0miya commented Jul 23, 2018

autosummary -- does not understand module level datas/attributes #344

autosummary -- does not understand module level datas/attributes #344

Comments

shimizukawa commented Jan 2, 2015

shimizukawa commented Jan 2, 2015

shimizukawa commented Jan 2, 2015

shimizukawa commented Jan 2, 2015

mstimberg commented Aug 14, 2015

KelSolaar commented Feb 2, 2018 • edited Loading

tk0miya commented Feb 2, 2018

KelSolaar commented Feb 2, 2018

KelSolaar commented Feb 2, 2018

Autosummary

Automodule

KelSolaar commented Feb 2, 2018

Autosummary

tk0miya commented Feb 3, 2018

tk0miya commented Feb 3, 2018

KelSolaar commented Feb 3, 2018

tk0miya commented Feb 4, 2018

KelSolaar commented Feb 5, 2018

tk0miya commented Jul 21, 2018

tk0miya commented Jul 23, 2018

KelSolaar commented Feb 2, 2018 •

edited

Loading