--- 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: <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.)
-------------------------------------------------------
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!
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=110944&bid=241720&dat=121642
_______________________________________________
Epydoc-devel mailing list
address@hidden
https://lists.sourceforge.net/lists/listinfo/epydoc-devel
--- End Message ---
signature.asc