scons doc fails with: AttributeError: 'Text' object has no attribute 'data'

[cirosantilli]

scons 4d2f1e1 , Ubuntu 17.10, Epydoc 3.0.1,
run scons doc, outcome:

Warning: No information available for
         SCons.Variables.ListVariable._ListVariable's base
         collections.UserList
  [....................Traceback (most recent call last):
  File "/home/ciro/.local/bin/epydoc", line 13, in <module>
    cli()
  File "/home/ciro/.local/lib/python2.7/site-packages/epydoc/cli.py",
line 965, in cli
    main(options, names)
  File "/home/ciro/.local/lib/python2.7/site-packages/epydoc/cli.py",
line 757, in main
    exclude_parse=exclude_parse)
  File "/home/ciro/.local/lib/python2.7/site-packages/epydoc/docbuilder.py",
line 275, in build_doc_index
    parse_docstring(val_doc, docindex, suppress_warnings)
  File "/home/ciro/.local/lib/python2.7/site-packages/epydoc/docstringparser.py",
line 265, in parse_docstring
    api_doc.summary, api_doc.other_docs = api_doc.descr.summary()
  File "/home/ciro/.local/lib/python2.7/site-packages/epydoc/markup/restructuredtext.py",
line 179, in summary
    try: self._document.walk(visitor)
  File "/usr/lib/python2.7/dist-packages/docutils/nodes.py", line 138, in walk
    if child.walk(visitor):
  File "/usr/lib/python2.7/dist-packages/docutils/nodes.py", line 130, in walk
    visitor.dispatch_visit(self)
  File "/usr/lib/python2.7/dist-packages/docutils/nodes.py", line
1882, in dispatch_visit
    return method(node)
  File "/home/ciro/.local/lib/python2.7/site-packages/epydoc/markup/restructuredtext.py",
line 307, in visit_paragraph
    m = self._SUMMARY_RE.match(child.data)
AttributeError: 'Text' object has no attribute 'data'
scons: *** [build/doc/HTML/scons-api/index.html] Error 1
scons: building terminated because of errors.

Same for:

./bootstrap.py doc

[mwichmann]

Looks like epydoc is probably at fault. See https://stackoverflow.com/questions/6704770/epydoc-attributeerror-text-object-has-no-attribute-data - particularly unfortunately that epydoc itself seems to be dead (there have been a few distro patches, but upstream doesn't seem to have had anything happen for a decade)

[bdbaddog]

Indeed. I'm spending a little time playing with sphinx and sphinx-apidoc Yielding many warnings. Anyone have experience using such for API docs?

…

-Bill

On Sun, Apr 29, 2018 at 4:44 PM, Mats Wichmann ***@***.***> wrote: Looks like epydoc is probably at fault. See https://stackoverflow.com/ questions/6704770/epydoc-attributeerror-text-object-has-no-attribute-data - particularly unfortunately that epydoc itself seems to be dead (there have been a few distro patches, but upstream doesn't seem to have had anything happen for a decade) — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#3121 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAFBNKX6I98RdgCaCKVuGfnhNUVWoUTWks5ttiYdgaJpZM4Tr5nD> .

[bdbaddog]

Progress.. Take a look at: http://scons.org/sphinx_wip/ On Sun, Apr 29, 2018 at 6:05 PM, Bill Deegan <bill@baddogconsulting.com> wrote:

…

Indeed. I'm spending a little time playing with sphinx and sphinx-apidoc Yielding many warnings. Anyone have experience using such for API docs? -Bill On Sun, Apr 29, 2018 at 4:44 PM, Mats Wichmann ***@***.***> wrote: > Looks like epydoc is probably at fault. See > https://stackoverflow.com/questions/6704770/epydoc-attribute > error-text-object-has-no-attribute-data - particularly unfortunately > that epydoc itself seems to be dead (there have been a few distro patches, > but upstream doesn't seem to have had anything happen for a decade) > > — > You are receiving this because you are subscribed to this thread. > Reply to this email directly, view it on GitHub > <#3121 (comment)>, or mute > the thread > <https://github.com/notifications/unsubscribe-auth/AAFBNKX6I98RdgCaCKVuGfnhNUVWoUTWks5ttiYdgaJpZM4Tr5nD> > . >

[mwichmann]

yeah, looks to have promise.

[mwichmann]

I've made some progress getting this to look reasonable. Sphinx has complaints about a very few places using reStructuredText markup it doesn't like. One set of those can be calmed by using the "napoleon" extension which accepts both the "Numpy style" and the "Google style" markup extensions - the complaints are on lines in the Numpy style. The API markup uses the :tag: format so those are never a complaint for it, but they're not as human-readable (in the code) as the other two. However, scons' Null class manages to break napoleon! ticket filed upstream sphinx-doc/sphinx#4931 - fix could be there, or we could hack the null class. Meanwhile, reasonable results being produced but with lots of investigation needed to prove the generation is complete, etc.

[mwichmann]

For the sake of amusement, this "fixes" the null class to meet the expectations of the sphinx plugin. It's not really in line with the intent of the pattern it implements, but they may not want to fix things for our unusual class either.

https://gist.github.com/mwichmann/9f3e6c692ee9ed435fd331706278ce17

[ptomulik]

https://github.com/nltk/epydoc seems to be current "official" repo for epydoc. It was updated few days ago to make it functioning under python 2.7 and 3.x. There is no new release (yet?). Not sure there will be.

Anyway, this specific issue is also fixed in the PR mentioned.

[mwichmann]

Nice. "resurrection", eh? I see Fedora is using something quite old: epydoc-3.0.1.20090203svn-9. That was part of what made me assume it was effectively abandoned (2009 is a long time ago!)

[ptomulik]

Nice. "resurrection", eh? I see Fedora is using something quite old: epydoc-3.0.1.20090203svn-9. That was part of what made me assume it was effectively abandoned (2009 is a long time ago!)

Well, because it probably was abandoned. And perhaps still remains in this state. The original author seems to be quite inactive. But what can prevent others from making it alive for next few months? It's OSS. :)

[mwichmann]

Just so it's recorded somewhere, epydoc has been flushed from Debian and Ubuntu. The most relevant trail of info on that is in the Debian bug: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=932574. There seemed to be no appetite for keeping it alive.

[mwichmann]

Swinging back to this, I ran into a hiccup with Sphinx' autodoc (from our viewpoint) that is made a lot worse by SCons allowing so much to be modifiable where it probably doesn't need to be. In this case, there are a bunch of functions/methods which would call a function to do something, but the user might want to change that function so it's passed as a kwarg with default. sphinx.ext.autodoc imports and executes what it's generating docs for, which includes expanding "constants". Thus this signature in the code:

def flatten(obj, isinstance=isinstance, StringTypes=StringTypes,
            SequenceTypes=SequenceTypes, do_flatten=do_flatten):

is rendered by autodoc like this (line breaks mine for readability here):

SCons.Util.flatten(obj, isinstance=<built-in function isinstance>,
                   StringTypes=(<class 'str'>, <class 'collections.UserString'>),
                   SequenceTypes=(<class 'list'>, <class 'tuple'>,
                                  <class 'collections.UserList'>, 
                                  <class 'collections.abc.MappingView'>), 
                   do_flatten=<function do_flatten>)

which is frankly pretty horrid...

See sphinx-doc/sphinx#759

[bdbaddog]

@mwichmann - rather API docs with a TODO, than no APIDOCS.. If you have a PR push it, we'll merge and add another Issue to track resolving the above?

[bdbaddog]

I'm going to close this and add a new issue to switch API docs to Sphinx and reference this Issue.