twisted.words.xish.yappsrt.Scanner.__init__ is not proper epytext

[therve]

It broke the documentation builbot. Following patch correct this:

Index: twisted/words/xish/yappsrt.py
===================================================================
--- twisted/words/xish/yappsrt.py       (révision 20510)
+++ twisted/words/xish/yappsrt.py       (copie de travail)
@@ -80,10 +80,10 @@
                        file=None,filename=None,stacked=False):
                """Initialize the scanner.

-               Parameters:
-                 patterns : [(terminal, uncompiled regex), ...] or None
-                 ignore : {terminal:None, ...}
-                 input : string
+               Parameters::
+                - patterns : [(terminal, uncompiled regex), ...] or None
+                - ignore : {terminal:None, ...}
+                - input : string

                If patterns is None, we assume that the subclass has
                defined self.patterns : [(terminal, compiled regex), ...].

[ralphm]

Please don't try to 'fix' this. This file is the yapps runtime and is by a third party.

The file xpathparser.g used to have this functionality embedded, but people were subsequently trying to blindly 'fix' the API documentation in the generated xpathparser.py file, making it a nightmare to maintain. So that is why we now include the official yapps runtime.

Could we maybe exclude yappsrt.py from pydoctor API generation and leave the file as-is?

I intend to mark this as wontfix.

[Jean-Paul Calderone]

You can't mark it as wontfix: ​http://twistedmatrix.com/buildbot-supported/

[ralphm]

Yeah, I didn't notice we had that up until after I posted that response. Seeing you agreed with me on the duplicate #2702, I think it would be nice to add exclusion support to pydoctor.

[Michael Hudson-Doyle]

So pydoctor now (in SVN head) avoids that module, but the offending docstring still turns up as the docstring of twisted.words.xish.xpathparser.XPathParser.init, so this alone won't fix the buildbot, so there's still a code change needed for this (adding a docstring to the previously mentioned method). Or I guess pydoctor could not consider docstrings of objects that are excluded but I'm not that keen on that idea.

[Jean-Paul Calderone]

Hmmmmmm.

Tricky. :/

[Glyph]

Maybe I've missed something obvious, but:

Why are we including the yapps runtime rather than just depending on it? Is it not packaged?

If we are going to bundle it with Twisted, perhaps it could live outside the Twisted package, which should hopefully not get picked up by pydoctor.

[Jean-Paul Calderone]

Hrm. It _is_ packaged. I don't know why it's also in Twisted.

[ralphm]

Seeing that #2502 has been reversed because of this, I'm not sure if packaging the Yapps runtime seperately resolves the issue. The generated twisted.words.xish.xpathparser module would still have an XPathParser.__init__ that inherits from the Yapps runtime and generate non-epydoc docstrings.

Maybe we need a script that calls the yapps compiler and applies the needed local fixes (import and the docstring) for generating xpathparser.py to resolve the issue.

I understand the suggestion of depending on a yapps runtime package, but I notice that there are platforms (e.g. FreeBSD) that don't provide yapps or the yapps runtime as a package (yet).

[Jean-Paul Calderone]

Distributing it with Twisted but outside twisted should address the issue of platforms which don't package it. If pydoctor still has a problem because the generated subclass inherits the non-parsing docstring, I'm not sure what to do about that (buildbot suggests it doesn't, though)

[Jean-Paul Calderone]

Okay, buildbot behavior is explained to my satisfaction, so it is actually working w/ yappsrt outside of the twisted namespace.

[Jean-Paul Calderone]

I guess we'll resolve this #2502 since the branch for that ended up being reverted.