epydoc-devel — Discussions about epydoc development

Re: [Epydoc-devel] abstract functions

[Daniele V. <dan...@gm...>]

> > How would you call such tag? "notimplemented"?
>
> Maybe `abstract' or what you suggest.  Maybe `unimplemented'.

abstract could be confused with "an article abstract" and probably
would conflict with the matching reST tag.

[...]

> > I'd also try to parse for methods only composed by a "raise
> > NotImplementedError" statement and automatically set them as
> > "notimplemented".
>
> Then also watch for methods with only
>
>     raise NotImplementedError (any-expression-here)
>
> or
>
>     raise NotImplementedError, any-string

Nice: the exception argument would be used as field description.

Re: [Epydoc-devel] abstract functions

[Paul P. <pog...@gm...>]

Daniele Varrazzo wrote:
> Paul Pogonyshev ha scritto:
>  > Hi,
>  >
>  > How could I document such code?
>  >
>  > class AbstractFoo (object):
>  >     def bar (self):
>  >         # Not implemented.
>  >         raise NotImplementedError
>  >
>  > I would like something as standing out as "class method" in bar()
>  > documentation, so that users really know they _must_ implement it
>  > in a subclass for it to work.
> 
> AFAIK there is nothing like what you ask for. Anyway it is something i 
> already thought it could be useful. I can try to work a patch to add 
> visual feedback for abstract methods.
> 
> It may be a new tag for docstrings, which may warn the users that a 
> function should be implemented by subclasses: i'd try to implement a tag 
>   like "@note" or "@attention", i.e. a tag taking a description as argument.
> 
> How would you call such tag? "notimplemented"?

Maybe `abstract' or what you suggest.  Maybe `unimplemented'.

> Differently from other tags, this one should not propagate down the 
> inheritance tree: if bar() gets implemented but its documentation is not 
> changed, the "notimplemented" tag should be dropped.

It should also probably put some notice into the method list, so that
information is available not only in longer method description.  I think
it is not less important than information about method being static.

Probably should also put notice right below method name, e.g.:

    foo (_class)
    Class Method, Abstract

but it is not that important.

> I'd also try to parse for methods only composed by a "raise 
> NotImplementedError" statement and automatically set them as 
> "notimplemented".

Then also watch for methods with only

    raise NotImplementedError (any-expression-here)

or

    raise NotImplementedError, any-string

> Meanwhile i'd say to use the @newfield tag:

If you will add support for it into epydoc, I'll wait.  I'm not in
hurry :)

> I'll try to create a new tag with the described characteristics. I'll 
> make you know something in the next days.

Great, thanks.  I'm subscribed here, so will notice if you post
anything to this list.

Paul

Re: [Epydoc-devel] abstract functions

[Daniele V. <dan...@gm...>]

Paul Pogonyshev ha scritto:
 > Hi,
 >
 > How could I document such code?
 >
 > class AbstractFoo (object):
 >     def bar (self):
 >         # Not implemented.
 >         raise NotImplementedError
 >
 > I would like something as standing out as "class method" in bar()
 > documentation, so that users really know they _must_ implement it
 > in a subclass for it to work.

AFAIK there is nothing like what you ask for. Anyway it is something i 
already thought it could be useful. I can try to work a patch to add 
visual feedback for abstract methods.

It may be a new tag for docstrings, which may warn the users that a 
function should be implemented by subclasses: i'd try to implement a tag 
  like "@note" or "@attention", i.e. a tag taking a description as argument.

How would you call such tag? "notimplemented"?

Differently from other tags, this one should not propagate down the 
inheritance tree: if bar() gets implemented but its documentation is not 
changed, the "notimplemented" tag should be dropped.

I'd also try to parse for methods only composed by a "raise 
NotImplementedError" statement and automatically set them as 
"notimplemented".

Meanwhile i'd say to use the @newfield tag:

     class AbstractFoo (object):
         """Testing not implemented

         @newfield notimplemented: Not implemented
         """
         def bar (self):
             """Wicket the wocket

             @notimplemented: Subclasses must know how to bar
             """
             raise NotImplementedError

     class Foo(AbstractFoo):
         def bar(self):
             return 10

which yields a message explicit enough, though not shown in the class 
summary but only in the method details.

Curiously, the "Not implemented" message doesn't appear in the "Foo" 
documentation! It should be a newfield bug, i don't think my laptop is 
getting smarter than me. Anyway i am running epydoc 3 from a svn trunk 
checkout of some week ago, so i don't know what the current behavior 
really is.

I'll try to create a new tag with the described characteristics. I'll 
make you know something in the next days.

Cheers,

Daniele

[Epydoc-devel] abstract functions

[Paul P. <pog...@gm...>]

Hi,

How could I document such code?

class AbstractFoo (object):
    def bar (self):
        # Not implemented.
        raise NotImplementedError

I would like something as standing out as "class method" in bar()
documentation, so that users really know they _must_ implement it
in a subclass for it to work.

Paul

Re: [Epydoc-devel] __init__ params for extension type?

[Barry W. <ba...@py...>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Sep 27, 2006, at 3:42 PM, Daniele Varrazzo wrote:

> a few days ago i patched Epydoc adding the functionality we talked
> about. The feature has been merged in the svn trunk in r1396.

Thanks very much Daniele.  I'll try to pull down this version and run  
it over our code.

Cheers,
- -Barry

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Darwin)

iQCVAwUBRSLEWHEjvBPtnXfVAQKHjAP/UzjP4WTLrL2OzQUm88aI1RyrS+hzp3xt
0GRqmCVcvidCQNu57e07pMoEgfoCJeO+Cm4OLy6U9ioAR+Kr1o2cSSFDed+EUmi4
CFI1SP8v2t+D+PSbY3hAYiWYiKD2YX5QavivJAwvU31EbUitD3PFctkpJbDdjsvb
JyJWaSzbAW8=
=10nj
-----END PGP SIGNATURE-----

[Epydoc-devel] New release: 3.0 alpha 3

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

The third alpha of epydoc 3.0 adds a large number of bug fixes, along 
with several minor improvements.   For those who haven't tried epydoc 
3.0, it includes a large number of improvements over epydoc 2.1, 
including support for both source parsing & introspection; docstrings 
for variables; graphs & diagram generation; and syntax highlighted 
source code.  See <http://epydoc.sourceforge.net/whatsnew.html> for more 
information.

<http://epydoc.sourceforge.net/>

* Download epydoc 3.0a3..... http://tinyurl.com/m7x9d
* 3.0 alpha change log...... http://tinyurl.com/rh2zj
* Report bugs............... http://tinyurl.com/odvfw
* Request features.......... http://tinyurl.com/p2rl8

-Edward

Re: [Epydoc-devel] Source code listing problems

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

Kent Tenney wrote:
> Howdy,
> 
> I'm using 3.0alpha2 and am seeing issues
> with source code listings.
> 
> With the release version there's some problem
> with the html or css, with svn the source processing
> fails with a unicode error.
> 
> Are these known issues or should I supply more details?
> 
> Should I be using 2.1 instead of 3.0a ?

I believe these problems should be fixed in the most recent subversion 
revision.  I just recently got some time to go through the list of bug 
reports on source forge and squash most of the bugs there.  I'm planning 
to do a new alpha release in the near future.

-Edward

[Epydoc-devel] Source code listing problems

[Kent T. <kt...@gm...>]

Howdy,

I'm using 3.0alpha2 and am seeing issues
with source code listings.

With the release version there's some problem
with the html or css, with svn the source processing
fails with a unicode error.

Are these known issues or should I supply more details?

Should I be using 2.1 instead of 3.0a ?

Thanks,
Kent

[Epydoc-devel] Source file formatting problem

[Kent T. <kt...@gm...>]

Howdy,

I'm finding intermittant errors in formatting of
source code listings.

Look around line 422 in;
http://longrun.zwiki.org/pstats-pysrc.html

Thanks,
Kent

[Epydoc-devel] epydoc-3.0alpha2 comments

[Kent T. <kt...@gm...>]

Howdy,

This is great stuff, extremely useful.

if "dotpath: ..." is in the config file I get the error

    from epydoc import dotgraph
ImportError: cannot import name dotgraph

Do I need to install something else, or is this unfinished?

Thanks,
Kent

Re: [Epydoc-devel] __init__ params for extension type?

[Barry W. <ba...@py...>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Jul 12, 2006, at 11:25 PM, Edward Loper wrote:

> Ah, I hadn't realized that there was no way to give the class & the  
> constructor separate docstrings for extension classes.  In that  
> case, this definitely should be supported.  I.e., epydoc should  
> check the class docstring to see if it starts with a signature-like  
> line, and if so, derive the constructor signature from it, and  
> create a new documentation entry for the constructor.  This should  
> probably only be done for builtin/extension classes, not pure  
> python classes.
>
> Unfortunately, I won't have time to work on this for a little  
> while.  But if anyone wants to put together a patch to do this (for  
> epydoc 3, or 2, or both), that would be great! :)

I may indeed work on this and will definitely provide any patches I  
come up with.

Cheers
- -Barry

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (Darwin)

iQCVAwUBRLa8SnEjvBPtnXfVAQJETwP/XXUvlkErGfQ4n6QejLtbvL9ETuce2SLe
pTGIj4EH3/6xm2EMTCAKri5KxC5TFqh9B1IMbzzH4PBihijbhcZDRPVGNEk0vhLM
FgIME5/o9b+mdWpHlNRBSh8oRd2nKvH2YBuohYFsmz18p1eMyCnJhtDqOE3gVATp
r7LkpTajj6Q=
=DPoT
-----END PGP SIGNATURE-----

Re: [Epydoc-devel] epydoc 2.1 can't handle PyGetSetDefs?

[Barry W. <ba...@py...>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Jul 12, 2006, at 11:16 PM, Edward Loper wrote:

> On Jul 10, 2006, at 3:12 PM, Barry Warsaw wrote:
>> It appears that epydoc cannot handle class attributes
>> defined in extension modules with PyGetSetDef.  We define almost all
>> of our attributes this way and all I get are things like
>>
>> getset_descriptor | alias_limit = <attribute 'alias_limit' of '...'
>>
>> This even though alias_limit's PyGetSetDef structure contains a
>> docstring and in fact you can get the __doc__ of that descriptor just
>> fine.
>
> Thanks to Daniele for providing a quick patch to address this.  One
> question that came up in that patch, though, is what the best way is
> to get at the getset_descriptor type.  I suggested the following
> (which I found via google):
>
>>>> print type(types.FunctionType.__dict__.get('__dict__'))
> <type 'getset_descriptor'>
>
> But this seems to be an implementation detail of FunctionType, that's
> subject to change in the future.  It doesn't look like the
> getset_descriptor type is accessible via the types module.  So any
> suggestions on what the best way to get at this type is?

See

http://mail.python.org/pipermail/python-dev/2006-July/067219.html

for a similar thread I've started on python-dev.  While I ended up  
using type(types.FrameType.f_locals) I think again, that's an  
implementation detail that's subject to change.  Worse, there are  
also member descriptors (see my previous post) and for that, there  
really is no good candidate (the situation is worse for Python's  
types module but could probably work for epydoc).

So my pre-coffee thought this morning is the same as yours: Python  
really needs a _types module that provides those C types in a way  
that's guaranteed not to change.  I plan on throwing something  
together for Python 2.5, but it's becoming less likely that I'd be  
allowed to backport that to Python 2.4 (or earlier, I don't know what  
the minimum Python version epydoc will support).

Still, I see no reason why we couldn't collaborate on such a built-in  
module.  OTOH, if you want a pure-Python solution, for member  
descriptors, use type(datetime.timedelta.days)

- -Barry

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (Darwin)

iQCVAwUBRLY+BXEjvBPtnXfVAQKmSwP+MzmLiXaf4yAipJeQRAgTugSIUsIHbXCL
nON/1v5m8wCOUr+CnNn63s/L+CarYO2NXqpsqQxkP/nTJRBJTOUH9sArcCdqPymH
cJgNP7CXGYPAEyqEYgYW4ZuncwQeo6GGZw67ia5N7HZ/CSZh1IGJhlhGEJP45dwa
rLqKagJp2Xk=
=Jeft
-----END PGP SIGNATURE-----

Re: [Epydoc-devel] epydoc 2.1 can't handle PyGetSetDefs?

[Daniele V. <dan...@gm...>]

On 7/13/06, Edward Loper <ed...@gr...> wrote:
> On Jul 10, 2006, at 3:12 PM, Barry Warsaw wrote:
> > It appears that epydoc cannot handle class attributes
> > defined in extension modules with PyGetSetDef.  We define almost all
> > of our attributes this way and all I get are things like
> >
> > getset_descriptor | alias_limit = <attribute 'alias_limit' of '...'
> >
> > This even though alias_limit's PyGetSetDef structure contains a
> > docstring and in fact you can get the __doc__ of that descriptor just
> > fine.
>
> Thanks to Daniele for providing a quick patch to address this.  One
> question that came up in that patch, though, is what the best way is
> to get at the getset_descriptor type.  I suggested the following
> (which I found via google):
>
>  >>> print type(types.FunctionType.__dict__.get('__dict__'))
> <type 'getset_descriptor'>
>
> But this seems to be an implementation detail of FunctionType, that's
> subject to change in the future.  It doesn't look like the
> getset_descriptor type is accessible via the types module.  So any
> suggestions on what the best way to get at this type is?

What about creating an extension module of our own (probably it should
be called "epyzoo.so" :D) with a specimen (two in case of Flood) of
the different extension types availablein from the C API?  It could be
used as an addendum to the types module.

That woud have the drawback of requiring a binary distribution on
Windows platforms but i'm about used at that (even if i'm not a w32
user anymore - i moved to Gentoo a few months ago - however i have
some winbox handy to build them)

Daniele

Re: [Epydoc-devel] __init__ params for extension type?

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

On Jul 12, 2006, at 10:53 AM, Barry Warsaw wrote:
>> @Edward:
>> In any case, allowing the constructor signature to be expressed in  
>> the
>> class docstring seems reasonable. I saw the same convention used
>> somewhere, just as the object __init__ docstring suggests.
>
> I think this /is/ a problem for extension types.  The constructor for
> an extension type is defined in the tp_init slot of the type struct
> and the struct's tp_doc slot is the only place that you can hang
> documentation.  AFAICT this slot really serves dual purposes as both
> the type's (a.k.a. class's) documentation and the documentation for
> the constructor.

Ah, I hadn't realized that there was no way to give the class & the  
constructor separate docstrings for extension classes.  In that case,  
this definitely should be supported.  I.e., epydoc should check the  
class docstring to see if it starts with a signature-like line, and  
if so, derive the constructor signature from it, and create a new  
documentation entry for the constructor.  This should probably only  
be done for builtin/extension classes, not pure python classes.

Unfortunately, I won't have time to work on this for a little while.   
But if anyone wants to put together a patch to do this (for epydoc 3,  
or 2, or both), that would be great! :)

> BTW, I tried Edward's suggestion in my tp_doc docstring and it
> doesn't really work.  The class documentation stops at the first
> @param and AFAICT just gets thrown away.

I was assuming that the constructor had its own docstring, just like  
other methods.  If that's not the case, then this won't work. :)

-Edward

Re: [Epydoc-devel] epydoc 2.1 can't handle PyGetSetDefs?

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

On Jul 10, 2006, at 3:12 PM, Barry Warsaw wrote:
> It appears that epydoc cannot handle class attributes
> defined in extension modules with PyGetSetDef.  We define almost all
> of our attributes this way and all I get are things like
>
> getset_descriptor | alias_limit = <attribute 'alias_limit' of '...'
>
> This even though alias_limit's PyGetSetDef structure contains a
> docstring and in fact you can get the __doc__ of that descriptor just
> fine.

Thanks to Daniele for providing a quick patch to address this.  One  
question that came up in that patch, though, is what the best way is  
to get at the getset_descriptor type.  I suggested the following  
(which I found via google):

 >>> print type(types.FunctionType.__dict__.get('__dict__'))
<type 'getset_descriptor'>

But this seems to be an implementation detail of FunctionType, that's  
subject to change in the future.  It doesn't look like the  
getset_descriptor type is accessible via the types module.  So any  
suggestions on what the best way to get at this type is?

-Edward

Re: [Epydoc-devel] epydoc 2.1 can't handle PyGetSetDefs?

[Barry W. <ba...@py...>]

On Jul 11, 2006, at 8:16 AM, Daniele Varrazzo wrote:

>> I've had a few minor problems along the way, and some ideas that I'll
>> share later, but I wanted to ask a quick question for my current
>> blocker.  It appears that epydoc cannot handle class attributes
>> defined in extension modules with PyGetSetDef.
>
> i hammered together a patch: with it getset_descriptors appear like  
> properties.

Turns out there's another type of built-in objects that need to be  
supported like properties: member descriptors.  An example is  
datetime.timedelta.days.

Here's a patch cargo culted from your previous patch.  It seems to do  
the trick for me.

Cheers,
-Barry

Re: [Epydoc-devel] __init__ params for extension type?

[Barry W. <ba...@py...>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Jul 12, 2006, at 12:43 PM, Daniele Varrazzo wrote:

> The string
>
>    x.__init__(...) initializes x; see x.__class__.__doc__ for  
> signature
>
> is just "object.__init__" docstring. Actually this is in contrast with
> PEP 257, which informs:
>
>   The class constructor should be documented in the docstring for its
> __init__ method.
>
> Epydoc treats __init__ as a normal method (at least from this PoV):
> the ctor parameters should be added to the __init__ docstring.
> Example:
>
>    class Foo(object):
>        """This is the object signature"""
>        def __init__(self, a, b):
>            """The ctor.
>
>            @param a: The first letter
>            @type a: int
>            @param b: The letter after the first
>            @type b: str
>            """
>            pass
>
> Is this a problem for extension types? I guess the __init__.__doc__
> can be customized.
>
> @Edward:
> In any case, allowing the constructor signature to be expressed in the
> class docstring seems reasonable. I saw the same convention used
> somewhere, just as the object __init__ docstring suggests.

I think this /is/ a problem for extension types.  The constructor for  
an extension type is defined in the tp_init slot of the type struct  
and the struct's tp_doc slot is the only place that you can hang  
documentation.  AFAICT this slot really serves dual purposes as both  
the type's (a.k.a. class's) documentation and the documentation for  
the constructor.  There is really no other place to tie documentation  
to an extension type's __init__(), unlike for other methods which are  
defined in a PyMethodDef containing slots for both the function and  
docstring.

So it seems like parsing constructor signatures out of a class  
docstring for extension types is the only option.

BTW, I tried Edward's suggestion in my tp_doc docstring and it  
doesn't really work.  The class documentation stops at the first  
@param and AFAICT just gets thrown away.

- -Barry

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (Darwin)

iQCVAwUBRLUo7HEjvBPtnXfVAQIudgQAkm6piVS/81fYStQyST9AqTWr+UCPg/EN
jq7g0SbNOjqHM4ZztfS9iRH9FBgb/B2WDHPexgRmvVSowgBhBdADBHWS529A0voq
8mW/u9QCYf4PrHoU0GyF3hn9iBfe/egXIt7xdF+Kb9t1su/WCPqM9Aoxk1qzLR7h
NxGBaxR1NpE=
=BTOB
-----END PGP SIGNATURE-----

Re: [Epydoc-devel] __init__ params for extension type?

[Daniele V. <dan...@gm...>]

> Where would I document the parameters for extension types?  I thought
> I could add @param and @type fields to the docstring for the tp_doc
> slot, but when I generate the documentation I just get warnings like:
>
> In foo.Bar docstring:
>      - Warning: Invalid context for field tag 'param'
>
> In the generated documentation for the class's __init__() you see:
>
> x.__init__(...) initializes x; see x.__class__.__doc__ for signature
>
> but there appears to be no way to document that signature.  Or have I
> just screwed up somewhere? ;)

The string

    x.__init__(...) initializes x; see x.__class__.__doc__ for signature

is just "object.__init__" docstring. Actually this is in contrast with
PEP 257, which informs:

   The class constructor should be documented in the docstring for its
__init__ method.

Epydoc treats __init__ as a normal method (at least from this PoV):
the ctor parameters should be added to the __init__ docstring.
Example:

    class Foo(object):
        """This is the object signature"""
        def __init__(self, a, b):
            """The ctor.

            @param a: The first letter
            @type a: int
            @param b: The letter after the first
            @type b: str
            """
            pass

Is this a problem for extension types? I guess the __init__.__doc__
can be customized.

@Edward:
In any case, allowing the constructor signature to be expressed in the
class docstring seems reasonable. I saw the same convention used
somewhere, just as the object __init__ docstring suggests.

Re: [Epydoc-devel] __init__ params for extension type?

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

On Jul 12, 2006, at 9:58 AM, Barry Warsaw wrote:
> FTR: still currently using epydoc 2.1
>
> Where would I document the parameters for extension types?  I thought
> I could add @param and @type fields to the docstring for the tp_doc
> slot, but when I generate the documentation I just get warnings like:
>
> In foo.Bar docstring:
>      - Warning: Invalid context for field tag 'param'
>
> In the generated documentation for the class's __init__() you see:
>
> x.__init__(...) initializes x; see x.__class__.__doc__ for signature

Try something like this as your docstring:

"x.__init__(a, b, c) -- initializes x, using parameters a, b, and c."

This is the convention that's used by most builtin functions, and  
epydoc understands it.  (I.e., epydoc will detect the signature in  
the docstring, parse it, and extract the variable names.)  Epydoc  
also understands a bunch of variants -- for the details, search for  
"SIGNATURE_RE" in epydoc/objdoc.py.

Once you've provided the signature in the first line of the  
docstring, you can then use @param, @type, etc., if you want to  
provide more info about some of the parameters.  E.g.:

"""foo(x,y) -> z -- performs a foo action.

@param y: The y parameter for the foo action.  Should be positive.
@param z: The z parameter for the foo action.  Should be negative."""

-Edward

[Epydoc-devel] __init__ params for extension type?

[Barry W. <ba...@py...>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

FTR: still currently using epydoc 2.1

Where would I document the parameters for extension types?  I thought  
I could add @param and @type fields to the docstring for the tp_doc  
slot, but when I generate the documentation I just get warnings like:

In foo.Bar docstring:
     - Warning: Invalid context for field tag 'param'

In the generated documentation for the class's __init__() you see:

x.__init__(...) initializes x; see x.__class__.__doc__ for signature

but there appears to be no way to document that signature.  Or have I  
just screwed up somewhere? ;)

Thanks,
- -Barry

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (Darwin)

iQCVAwUBRLUcL3EjvBPtnXfVAQLDYwP/T2znjaNLKAeN+uG4nQWZ5S9JZ3iAnjmo
RoB1RuuzdcgZJF4qIcSxNDwDCT1izsA1ml2YLByxEO+OREbNZ8SqJhXEbUPJ5P3u
2gbIUrii+sFcd+4DnoB4hi62tskDNvmAd47HwauzuNKuWHyRKxIW7ZzsR5Nezzq5
G4SKyq48F3g=
=sRlD
-----END PGP SIGNATURE-----

Re: [Epydoc-devel] epydoc 2.1 can't handle PyGetSetDefs?

[Barry W. <ba...@py...>]

On Jul 11, 2006, at 8:16 AM, Daniele Varrazzo wrote:

>> I've had a few minor problems along the way, and some ideas that I'll
>> share later, but I wanted to ask a quick question for my current
>> blocker.  It appears that epydoc cannot handle class attributes
>> defined in extension modules with PyGetSetDef.
>
> Hello Barry,
>
> i hammered together a patch: with it getset_descriptors appear like  
> properties.
>
> The patch id is 1520501 and it can be downloaded from
> http://sourceforge.net/tracker/index.php? 
> func=detail&aid=1520501&group_id=32455&atid=405620
>
> Epydoc 3.0  HEAD behaves nicer with getset_descriptors, but it
> erroneously files it as a class variable (the same thing happened in
> the making of the 2.1 patch). I will fix it too.

Thanks Daniele,

I tested the patch and it appears to work well.

I had to make one other small change to objdoc.py for what I think is  
an unrelated problem (although I'm not sure because I didn't see the  
bug before).  Without this, I'd get a traceback from add_one()  
because one of my getset descriptors did not have its parent ID in  
self.data.  I don't quite understand why that might be though, except  
that perhaps it's because the parent is a base class defined in the  
extension module.

In any event, with this patch, I can generate all my docs and even  
the traceback'ing getset descriptor gets documented correctly.

Cheers,
-Barry

Re: [Epydoc-devel] epydoc 2.1 can't handle PyGetSetDefs?

[Daniele V. <dan...@gm...>]

> I've had a few minor problems along the way, and some ideas that I'll
> share later, but I wanted to ask a quick question for my current
> blocker.  It appears that epydoc cannot handle class attributes
> defined in extension modules with PyGetSetDef.

Hello Barry,

i hammered together a patch: with it getset_descriptors appear like properties.

The patch id is 1520501 and it can be downloaded from
http://sourceforge.net/tracker/index.php?func=detail&aid=1520501&group_id=32455&atid=405620

Epydoc 3.0  HEAD behaves nicer with getset_descriptors, but it
erroneously files it as a class variable (the same thing happened in
the making of the 2.1 patch). I will fix it too.

Bye!

Daniele

[Epydoc-devel] epydoc 2.1 can't handle PyGetSetDefs?

[Barry W. <ba...@py...>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi all,

I've just started to use epydoc 2.1 to document the API for a tool  
that has a lot of Python code but is also extended/embedded.  In  
general, it seems like a great tool and is producing nice output with  
the Epytext markup.  Nice job!

I've had a few minor problems along the way, and some ideas that I'll  
share later, but I wanted to ask a quick question for my current  
blocker.  It appears that epydoc cannot handle class attributes  
defined in extension modules with PyGetSetDef.  We define almost all  
of our attributes this way and all I get are things like

getset_descriptor | alias_limit = <attribute 'alias_limit' of '...'

This even though alias_limit's PyGetSetDef structure contains a  
docstring and in fact you can get the __doc__ of that descriptor just  
fine.

I think you can prove this to yourself with standard Python 2.4 with  
the following:

 >>> from epydoc.html import HTMLFormatter
 >>> import array
 >>> HTMLFormatter.format(array.array.typecode)

Now, at this point you'll get an exception because the TypeError uses  
a local variable before its assignment.  Okay, that's easily fixed  
(use type(object) instead of type(link) on line 3381 of epydoc/ 
html.py).  But that just means you'll get the TypeError that was  
intended:

TypeError: You must use a Link or UID object to specify a  
getset_descriptor

which I think indicates that epydoc 2.1 doesn't know how to handle  
PyGetSetDefs.

I haven't dug into epydoc enough to figure out what needs to be  
changed in order to handle these built-in Python objects.  If you  
have any hints, I'd love to hear them!  I wonder if the problem isn't  
in inspect or pydoc since the interactive prompt's help() doesn't  
much like these objects either.  Try

 >>> import array
 >>> help(array.array.typecode)

to see the docstring ignoring help output.

Thoughts? Clues?  Thanks!
- -Barry




-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (Darwin)

iQCVAwUBRLLCw3EjvBPtnXfVAQK/ewP/Y2RwHBvFBbtLkxs1NhGhPI6OFLITJeFN
1c710JRjaRW1vdFXJDFoxpvuF3JRZ3vUcikVu5i6MzMD9wEBVzjpS5UPNA1z0TMt
5ZGFjvEv3kwNj7GHHnREBG4FhVLyIDgWvY3lXWpkryBtQV8ZUDxEcG3m5vI94SeP
jAsx1XysQ0M=
=Wv4W
-----END PGP SIGNATURE-----

[Epydoc-devel] crossreference targets

[Eric H. <e-...@ne...>]

In 2.1, if you had a link (L{something}), and the target could not be
found, epydoc would generate a warning "Failed identifier crossreference
targets".  3.0 does not seem to do this (it silently ignores it).  I can't
seem to figure out a way to get it to warn about these link errors.  The
man page for 3.0 has a similar error message ("Could not find a UID for")
but that does not appear in the souce code.  Is this a feature that just
isn't finished, yet?

-Eric

[Epydoc-devel] problem linking to variables

[David H. <dmh...@ma...>]

Hello,

The following doesn't seem to work:

============ snip

""" This module has a variable called L{x}. """

#: My favourite variable.
x = 5

def func():
     """ Where is L{x}? """
     pass

============ snip

The variable x correctly gets its own entry in the HTML output, so  
epydoc has definitely found it, but neither of the links to x appear;  
the x just gets placed as ordinary text.

What am I doing wrong?

I'm running epydoc 3.0 alpha 2 on python 2.4.1 on mac os x 10.4.6.

I also poked around the epydoc documentation to see if there were any  
examples of this usage, and indeed it looks broken there too. For  
example, the documentation for the docstringparser module (http:// 
epydoc.sourceforge.net/api/toc-epydoc.docstringparser-module.html)  
has a link to the variable STANDARD_FIELDS in the second paragraph,  
but it doesn't show up as a link to the variable info that appears  
later on the page.

Thanks

David