Re: [Epydoc-devel] Planning for 3.0

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

Edward Loper ha scritto:
> 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.

I also thought that saying "i want the features x and y" and "i want 3.0
rolled out" means going nowhere :) so, many "bright ideas" are probably
perfect... for the release 3.1. Getting back to 3.0:

>>   - pretty printing (see also SF #1628044). How to represent an object
>>     value?

I don't expect this being a showstopper for 3.0, and best result can be
achieved incrementally.

>>   - parsing some "#:" comments into functions body as they were part of
>>     the function docstring. [...]
> 
> This is a little bit problematic, because it would be hard to tell [...]

3.1 :)

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

3.1!

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

I'll start with a map variable name -> tag, then think about its 
customization.

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

I thought doctest blocks require >>> and ... things in front of the 
lines. I already wanted to leverage markup.doctest: i'll check if there 
is some refactoring to perform in order to add the directive.

>>   - :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?

Probably a command line switch for a wrapper around rst2html

>>   - 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?

Mmm.. i sent you a couple of mail that got unnoticed back on september 
2006. Anyway...

Quoting such message:

 > I fiddled with the HTML output and the default Epydoc css trying to
 > optimize the vertical space. A result can be seen at
 > http://www.develer.com/~piro/api-compact/epydoc.apidoc.APIDoc-class.html
 >
 > I'd like your opinion about the supposed problem and the proposed layout.
 >
 > Notice that i had to update not only the css, but also some html code.
 > Actually it looks to me kinda "old", with many alignment tricks that
 > nowadays can be better accomplished using CSS. For example, there are
 > many definitions list with empty definitions, i guess only used to
 > increase the left margin. I cleaned up them, minimizing the number of
 > warnings issued by Tidy, and using CSS to reposition them.
 >
 > For example i replaced
 >
 >   <dl><dt></dt><dd>
 >       <p><strong>Warning:</strong>
 >         This method uses undocumented data structures inside of
 >         <code>profile_stats</code>.
 >       </p>
 >   </dd></dl>
 >
 > with
 >
 >   <div class="fields">
 >       <p><strong>Warning:</strong>
 >         This method uses undocumented data structures inside of
 >         <code>profile_stats</code>.
 >       </p>
 >   </div>
 >
 > (attached, the full patch up to now)
 >
 > If you prefer to keep the pages appearance as is (wide), then we could
 > provide an optional "compact" CSS. Anyway, to allow wider CSS
 > positioning freedom, some html cleanup may be required (using more
 > divs and spans instead of p's and tables, for example)

The API i generated then are available at:

http://www.develer.com/~piro/api/epydoc.apidoc.APIDoc-class.html
http://www.develer.com/~piro/api-compact/epydoc.apidoc.APIDoc-class.html

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

The society i'm currently working for is an enthusiast sustainer of open 
source software and will be glad to offer web space to host such results.

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

Of course, the Python lib and Epydoc itself are in the list :)

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

My plan is now:

  - attack the remaining bugs. I'll put the older ones in pending state 
asking the reporters to check out the trunk and verify if they magically 
disappeared: if not, the bug will be fixed.

- Open a 3.1 group in the feature request tracker and move there what 
doesn't stop us to release a good 3.0. In the tracker i will add items from:

  - the TODO list in epydoc.__init__.py
  - my laundry list items (together with the comments you did about them)

and categorize them and the currently open requests splitting between 
3.0 and 3.1.

- Close the 3.0 requests and declare "beta"

- Spend some time parsing other open source projects and publishing the 
results, contributing back a cfg file to let them generate the docs by 
themselves

- If no big issue raises from such phase, go 3.0

- Enjoy

- Attacking the request list for 3.1...

Regards,

Daniele