Re: [Epydoc-devel] Planning for 3.0

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

Daniele Varrazzo wrote:
> what about setting a laundry list of things we want to be fixed to roll
> out a beta version of Epydoc 3.0?

Sounds good.  One item is to go through the bug list & respond to all 
the bug reports -- it looks like you've already been making some good 
progress on that front.

Unfortunately, I probably won't have much time to work on epydoc until 
the end of February, since I'm trying to finish up my phd proposal.  But 
I'm happy letting you take the lead in putting together the beta and/or 
3.0 release, if you're up for it.

> Here is a laundry list of things i'd like to discuss [...]

All of these sound like good features.  I don't see any of them as being 
necessary for the 3.0 release, but I'd be happy to see any of them added.

>   - exclusion list (SF #1209634) would help big project to adopt Epydoc
>     (just committed in the trunk a first version)

This definitely seems like a good thing.

>   - pretty printing (see also SF #1628044). How to represent an object
>     value?
>     - repr() is fine only for int and for classes that specifically
>       return a parsable representation, such as datetime. Even floats
>       (such as 0.1) often have an ugly representation.

Yeah -- people are very inconsistent about how they use repr/str.

>     - fall back on the parsed version if available and the repr() result
>       matches an  ugly pattern looks like "<something>"?

Sometimes the parsed version isn't very trustworthy.. E.g., if they 
create a variable with a list, and then append to it, etc.  But you may 
be right that this may be the best way to go when you get "<something>". 
  It's almost certainly the best way if you get "<xyz instance at 0xaddr>".

>     - fall back on str()ingification?

Yeah, it might be good to use str() for some values.

>     - prettyprinting of lists, dicts etc? More clever truncation of long
>       representations?

Seems like good ideas.

>     - if a variable value fits on a single row, omit the detail box?

Sure.

>     - ???

One issue/question is that right now a good amount of this is handled in 
specific docwriter modules..  E.g., the docwriter.html code to colorize 
regexps.  Should this be abstracted away somehow and handled more 
centrally?  E.g., the centralized code could generate an abstract 
structure saying how to color the regexp, and the individual writers 
would just translate that to the appropriate markup?

>   - parsing some "#:" comments into functions body as they were part of
>     the function docstring. It would keep some additional information
>     close to the code implementing it, making the task to keep the API
>     consistent with the code easier. Es.

This is a little bit problematic, because it would be hard to tell the 
difference between "#:" comments that are supposed to describe the 
enclosing object vs "#:" comments that are supposed to describe a 
variable assignment.  E.g., I think people would do things like:

      def __init__(self, foo):
          """This is a constructor of some sort."""
          ...there may be other code

          #: :warning: the current implementation only allows
          #:           positive numbers
          val = floor(log(num) / log(10)) + 1

          ...

or:

     class A:
         "..."
         ... other code

         #: :warning: ...
         x = 123

Where it's unclear whether whether that warning applies to the 
constructor function or to the 'val' variable.

>     Some tags (note, bug, warning, todo) are really best placed next the
>     code to be documented; precondition and postcondition would be nice
>     close to an assert etc.

True, but I'm not sure how to reconcile this with the ability to use 
"#:" comments to describe variables.

>   - using some module __variable__ as a tag (only the ones widely used:
>     __version__ above all, but we may be friendly with __author__ etc;
>     people has already been warned not to abuse of such variables, though
>     i couldn't find a reference)

This would be fine.  It would be nice if this could be customized, sort 
of how @field names can currently be added with @deffield.

>   - docutils :python: directive to allow examples to appear as colored
>     Python code

That would be fine.  Is there a reason not to use doctest block?  They 
already get colored.

>   - :api: role to allow docutils documents to refer to Epydoc generated
>     API. See for example
> http://www.initd.org/tracker/psycopg/browser/psycopg2/trunk/scripts/ext2html.py

This would need some sort of configuration to tell epydoc where that 
:api: role should point to.  Would this be done in the config 
file/command line?

>   - more compact html code, for which the exp-compact-html branch is
>     open. In some personal audits i had, somebody complained about the
>     signal/noise ratio in HTML output.

Can you point me at an example page that demonstrates the changes made 
by the branch?

> Together with setting a goal in terms of features, i'd love to QA Epydoc
> against the most prominent OS projects, such TurboGears (i just read
> they are having documentation issues - cfr.
> http://groups.google.it/group/turbogears/browse_thread/thread/ae0e52ff3f9fde60?hl=en 
> for example).

This would be excellent, and *very* much appreciated.  In fact, I think 
it might be a good idea to set up some scripts on a server somewhere to 
automatically run epydoc on various projects, to at least make sure that 
it doesn't crash.  I have a server I could probably put this on (I don't 
think there'd be enough space on the sourceforge server -- there's a 
100mb quota).  This would be something like the python buildbot, but 
simpler of course. :)

> I was very sad when i read (just a couple of weeks ago, but the issues
> were older) how Twisted guys were disappointed by Epydoc no more
> fulfilling their needs, up to decide to write their own API
> generator (http://codespeak.net/~mwh/pydoctor/).

That's too bad. :-/  Hopefully once 3.0 comes back, we can win back some 
of the projects that moved on to other tools.

> I'd like to check Epydoc against a list of packages, including some not 
> specifically thought to be inspected by Epydoc. The goal is:
>   - Epydoc must not crash (modulo the most magic corners, which now can
>     be removed from the list of modules to be introspected)
>   - The generation result shall be presented to the packages developers,
>     both to gather feedback about Epydoc output and to advertise Epydoc
>     to the community. Eventually making people happy to write
>     documentation...
> 
> A list of beasts to test against may include:
> 
>   - WxPython
>   - Django
>   - Turbogears
>   - Twisted
>   - SqlAlchemy
>   - docutils

Sounds great.  Of course the python stdlib should be included too. :) 
Once we do the beta release, we should make a point of encouraging 
people to try it out on their project & get back to us about what they 
think of the results.

-Edward