#18 Merge Twisted's monkeypatches

v3.0
closed
None
5
2007-03-01
2004-12-22
Andrew Bennetts
No

Twisted currently does a range of really vile monkey
patches to epydoc to make it work somewhat nicely with
Twisted's various needs. You can see the evil in
action here:

http://svn.twistedmatrix.com/cvs/trunk/admin/epyrun?view=auto&rev=12681&root=Twisted

Twisted generates its API docs by running
"admin/epyrun" in a SVN checkout.

If nothing else, you might get some feature ideas from
what's been done here.

Discussion

    • milestone: --> v3.0
    • assigned_to: nobody --> dvarrazzo
     
  • Logged In: YES
    user_id=1053920
    Originator: NO

    Thank you for the many ideas. Many of theme have already been added to the 3.0 trunk.

    Scanning the epyrun internals:

    # HACK: Don't import stuff that we don't like

    Epydoc shouldn't import other stuff except the one specified on the command line. There is some remaining issue, which i want to analyze carefully: i opened SF bug #1653486 as a memo.

    ## HACK: This is a nasty one! Replace TypeType with (TypeType,
    ## InterfaceClass) so Epydoc will try to document Interfaces.

    nasty! :) I don't use Zope, but i'll check where you use it and try to have Epydoc generate good docs for it. Anyway i notices that TypeType is only used in two places (which can be refactored into a single one), i.e. the function docintrospecter.isclass():

    def isclass(object):
    return isinstance(object, (TypeType, ClassType))

    i may add InterfaceClass to the test tuple: i think it will obtain exactly the same effect of your hack.

    # HACK: Force everything to be public.

    The rules to define public/private objects changed in Epydoc 3.0. You can specify a function with a leading underscore to be public by listing it in the __all__ variable.

    Fore a more radical approach, replace the checkCookie() function in the generated epydoc.js file with a function that does nothing:

    function checkCookie() { return; }

    this way the pages will open with the private items shown.

    # HACK: Don't append -module and -class to the filenames, and generate
    # redirecty-files for all methods.

    Probably in your project you are sure about what you did, but generally it is possible for a class and a module to have the same name, so i think Edward decided to stay on the safe side choosing file names.

    What is a concrete use of the slightly shorter URLs generated with this hack?

    # HACK: Only document stuff that we _tell_ you to document, you stupid
    # &#@&!#@

    Epydoc 3.0 is more conservative in crawling over the imported modules, and as i said i want to study the remaining issues.

    # HACK: Another "only doc what we tell you". We don't want epydoc to
    # automatically recurse into subdirectories: "twisted"'s presence was
    # causing "twisted/test" to be docced, even thought we explicitly
    # didn't put any twisted/test in our modnames.

    I preferred instead to keep recursing the packages but added command line options to skip patterns. For example, twisted (2.5.0, without additional package which i still have to install) can be currently inspected running::

    epydoc twisted \ --exclude-introspect="\.test|\.internet\.reactor" \ --exclude-parse="\.test"

    (about internet.reactor... you are not going to make many friends in the introspection party if you do stuff like:

    import sys
    del sys.modules['twisted.internet.reactor']

    this is basically playing hide and seek! :) )

    I hope to make Epydoc an useful tool for the twisted project. I shall set up a regression test on Epydoc results and include twisted in such test.

    Regards,

    Daniele

     
  • Edward Loper
    Edward Loper
    2007-02-14

    Logged In: YES
    user_id=195958
    Originator: NO

    dvarrazzo:
    > What is a concrete use of the slightly shorter URLs generated
    > with this hack?

    My guess is that they want them so they can link in to the API docs from other documentation sources, where they might not be able to tell from their documentation markup what type of object something is. E.g., if they had rst docs that said things like "the `foo.bar` class", then automatically translating that to a pointer into the api docs would be much easier if it could just be pointed to "http://some/ur/foo.bar.html".

    Andrew, if this is something you're interested in seeing implemented, could you please add it as a separate feature request, perhaps expanding on exactly what behavior you'd like. Would it suffice to instead have epydoc generate as one of its output files a mapping from dotted name to URL?

     
  • Edward Loper
    Edward Loper
    2007-02-14

    • status: open --> pending
     
  • Edward Loper
    Edward Loper
    2007-02-14

    Logged In: YES
    user_id=195958
    Originator: NO

    Most of the features in twisted's script have been added to epydoc. If there are any remaining features you'd like to see added, please add them as individual feature requests. I am setting this feature request's status to "pending" -- it will change to closed in two weeks.

     
  • Logged In: YES
    user_id=1312539
    Originator: NO

    This Tracker item was closed automatically by the system. It was
    previously set to a Pending status, and the original submitter
    did not respond within 14 days (the time period specified by
    the administrator of this Tracker).

     
    • status: pending --> closed