[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[GNUe-dev] [Fwd: [Epydoc-devel] Epydoc 3.0 alpha release]

From: Reinhard Mueller
Subject: [GNUe-dev] [Fwd: [Epydoc-devel] Epydoc 3.0 alpha release]
Date: Sat, 11 Mar 2006 13:27:41 +0100

What would others think about switching to Epydoc 3.0 for GNUe? Given
our project size, we might make up good beta testers.

--- Begin Message --- Subject: [Epydoc-devel] Epydoc 3.0 alpha release Date: Sat, 11 Mar 2006 04:55:43 -0500 User-agent: Thunderbird 1.5 (Windows/20051201) I just uploaded an alpha release for epydoc 3.0 to sourceforge. Epydoc 3.0 still has a ways to go until it's ready for release, but I wanted to give people a chance to play with its new features, and to point out any bugs that they find.

Significant portions of epydoc were rewritten from scratch for this
version.  This has allowed me to increase epydoc's functionality in
several significant ways; but in this alpha release, some features
from epydoc 2.1 are not yet available, including LaTeX/ps/pdf output,
and completeness checking.  If you need those features, then you
should keep using epydoc 2.1.  If you find any bugs, or have
suggestions for improving it, please report them on sourceforge:

Bugs: <>
Features: <>


Summary of Changes:

The most significant change has to do with the way that epydoc
extracts documentation information about python modules.  In previous
versions, epydoc extracted information about each module by importing
it, and using introspection to examine its contents.  The new version
of epydoc still supports introspection, but is also capable of
extracting information about python modules by parsing their source
code.  Furthermore, the new version of epydoc can combine these two
sources of information (introspection & parsing).  This is important
because each source has its own advantages and disadvantages with
respect to the other.  In particular:

  - Introspection gives epydoc an accurate picture of what modules
    will look like programmatically.  In particular, some modules
    actively modify the namespace they define, or use various "magic"
    techniques to alter their public interface.  Using introspection
    gives epydoc an accurate picture of what these modified interfaces
    look like.

  - If a module has dependencies that are not met on the current system,
    then it may not be possible to import and introspect it; but the
    parser can still examine its contents.

  - If importing a module has significant side effects, then
    introspecting it might not be desirable; but the parser can
    still examine its contents.

  - If a module is not trusted, then it might not be desirable to
    import it; but the parser can still examine its contents.

  - By parsing a module, we can find "pseudo-docstrings" and
    "docstring comments," which are unavailable via introspection.
    In particular, this makes it possible to associate API
    documentation with variables.

  - Introspection can give information about builtin and extension
    modules, which would be unavailable to a python source code
    parser.  This includes builtin or extension bases for pure Python

  - By parsing a module, we can easily determine which values were
    imported, and where they were imported from.  This information
    is not available via introspection.

Other improvements include:

  - Support for "pseudo-docstrings".  If a variable assignment
    statement is immediately followed by a bare string literal, then
    that assignment is treated as a docstring for that variable.  In
    classes, variable assignments at the class definition level are
    considered class variables; and assignments to instance variables
    in the constructor (__init__) are considered instance variables:

        >>> class A:
        ...     x = 22
        ...     """Docstring for class variable A.x"""
        ...     def __init__(self, a):
        ...         self.a = a
        ...         """Docstring for instance variable A.a"""

  - Support for "comment docstrings".  If a variable assignment
    is immediately preceeded by a comment whose lines begin with
    "#:", or is followed on the same line by such a comment, then
    it is treated as a docstring for that variable:

        >>> #: docstring for x
        ... x = 22

        >>> y = 33 #: docstring for y

  - Increased robustness in the face of a variety of "magic"
    manipulations of namespaces.

  - Support for nested classes

  - Full unicode support, including support for the 'encoding
    directive' (PEP 263).

  - The HTML output now includes pointers to colorized source
    code listings; and these source code listings contain
    pointers back into the documentation.

  - Methods that are inherited from "external" base classes are
    listed, but no longer described in detail.  E.g., if "object"
    is used as a base class, then the methods inherited from
    "object" will be listed at the bottom of the method summary
    table, but not described in detail.

  - The HTML output no longer contains separate pages for
    including and excluding private variables.  Instead, it uses
    CSS to dynamically hide or display private variables.  A
    cookie is used to record the user's preference.  (By default,
    private variables are hidden.)

This SF.Net email is sponsored by xPML, a groundbreaking scripting language
that extends applications into web and mobile media. Attend the live webcast
and join the prime developer group breaking into this new coding territory!
Epydoc-devel mailing list

--- End Message ---

Attachment: signature.asc
Description: Dies ist ein digital signierter Nachrichtenteil

reply via email to

[Prev in Thread] Current Thread [Next in Thread]