#243 Warnings about external modules

closed-fixed
nobody
None
5
2008-01-29
2008-01-25
No

I get a lot of warnings about "Improper paragraph indentation" in optparse and in NumPy. These modules are imported by my code, but they don't need to be examined at all (i.e., Epydoc doesn't generate pages for them)

This seems like a bug; if it isn't, is there a way for me to suppress these warnings?

Thanks

--
Gidi Avrahami
avrahami@deshaw.com

Discussion

  • Gidi_Avrahami

    Gidi_Avrahami - 2008-01-25

    Warnings about the optparse module

     
    Attachments
  • Gidi_Avrahami

    Gidi_Avrahami - 2008-01-25

    Logged In: YES
    user_id=1935074
    Originator: YES

    I should note that the errors appear only when the external module (e.g. optparse) is used for a subclass, i.e., this produces warnings:
    -----------------------------------------------------------------------------
    import optparse

    class Foo:
    def parse(self, *args):
    return optparse.parse_args(args)

    class Bar(optparse.OptionParser):
    def parse(self, *args):
    return self.parse_args(args)
    -----------------------------------------------------------------------------
    But if I only have Foo and not Bar, then there are no warnings.

     
  • Edward Loper

    Edward Loper - 2008-01-28
    • status: open --> closed-wont-fix
     
  • Edward Loper

    Edward Loper - 2008-01-28

    Logged In: YES
    user_id=195958
    Originator: NO

    This occurs because epydoc is inheriting docstrings from those base classes, and using them as part of your generated documentation. In other words, epydoc *does* generate pages using these docstrings, so epydoc's ability to parse them does matter.

    One option would be to use the "--docformat" argument to set the default __docformat__ to "plaintext". This means that all docstrings from modules that don't explicitly set __docformat__ will be treated as plaintext, and rendered using a monotype font, preserving any newlines from the original docstring. If you want to use epytext as the markup for your own modules, then you can mark that by using the __docformat__ variable. [1]

    Another option would be to ignore these warnings, but they do have a place -- they're telling you that epytext recognizes that it can't parse the docstrings in question, and so it's treating those docstrings as plaintext.

    [1] http://www.python.org/dev/peps/pep-0258/#choice-of-docstring-format

    -Edward

     
  • Nobody/Anonymous

    Logged In: NO

    Actually, epydoc does *not* generate any pages for these inherited modules.

     
  • Edward Loper

    Edward Loper - 2008-01-29
    • status: closed-wont-fix --> open
     
  • Edward Loper

    Edward Loper - 2008-01-29

    Logged In: YES
    user_id=195958
    Originator: NO

    Ok, let me be more specific. If you define a method that overrides a base class method, and that base class is defined outside your project, and your method has no docstring, then the docstring will be inherited. E.g., for:

    class Bar(optparse.OptionParser):
    def parse_args(self, *args):
    return something_else

    The generated docs for Bar.parse_args will inherit the docstring from optparse.OptionParser.parse_args. Thus, in *this* case, epydoc does need to parse the docstring. I agree that there are currently some cases where epydoc parses docstrings that it doesn't need to -- because it turns out that there are no user-defined methods that override them.

    I'll look into how difficult it will be to disable docstring parsing for those cases.

     
  • Edward Loper

    Edward Loper - 2008-01-29

    Logged In: YES
    user_id=195958
    Originator: NO

    Ok, the appropriate set of warnings should now be suppressed in svn revision 1677. (Epydoc still parses the docstrings, just in case, but suppress any warnings generated by them.) With "-vvv", it will print an "Info:" log statement letting you know that the warnings were suppressed. Warnings will not be suppressed for docstrings that are inherited by user-defined methods (e.g. my example with Bar.parse_args).

     
  • Edward Loper

    Edward Loper - 2008-01-29
    • status: open --> closed-fixed
     

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks