[Epydoc-devel] Epydoc 3.0 alpha release

[Edward L. <ed...@gr...>]

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: <http://sourceforge.net/tracker/?group_id=32455&atid=405618>
Features: <http://sourceforge.net/tracker/?group_id=32455&atid=405621>

-Edward

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

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