Opened 11 years ago

Closed 10 years ago

#2701 defect closed duplicate (duplicate)

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

Reported by: therve Owned by:
Priority: highest Milestone:
Component: words Keywords:
Cc: therve, ralphm, Jean-Paul Calderone, Glyph Branch:
Author:

Description

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), ...].

Change History (12)

comment:1 Changed 11 years ago by ralphm

Cc: therve ralphm Jean-Paul Calderone added
Component: corewords
Owner: changed from Glyph to 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.

comment:2 Changed 11 years ago by Jean-Paul Calderone

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

comment:3 Changed 11 years ago by 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.

comment:4 Changed 11 years ago by 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.

comment:5 Changed 11 years ago by Jean-Paul Calderone

Hmmmmmm.

Tricky. :/

comment:6 Changed 11 years ago by 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.

comment:7 Changed 11 years ago by Jean-Paul Calderone

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

comment:8 Changed 11 years ago by ralphm

Cc: Glyph added

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).

comment:9 Changed 11 years ago by 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)

comment:10 Changed 11 years ago by Jean-Paul Calderone

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

comment:11 Changed 10 years ago by Jean-Paul Calderone

Keywords: review removed
Resolution: duplicate
Status: newclosed

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

comment:12 Changed 7 years ago by <automation>

Owner: ralphm deleted
Note: See TracTickets for help on using tickets.