Opened 15 years ago

Closed 15 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, Ralph Meijer, 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 15 years ago by Ralph Meijer

Cc: therve Ralph Meijer Jean-Paul Calderone added
Component: corewords
Owner: changed from Glyph to Ralph Meijer

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 15 years ago by Jean-Paul Calderone

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

comment:3 Changed 15 years ago by Ralph Meijer

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 15 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 15 years ago by Jean-Paul Calderone

Hmmmmmm.

Tricky. :/

comment:6 Changed 15 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 15 years ago by Jean-Paul Calderone

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

comment:8 Changed 15 years ago by Ralph Meijer

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 15 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 15 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 15 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 11 years ago by <automation>

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