[Zope3-dev] Re: Windows eggs

[Jim Fulton]

On Jul 13, 2007, at 1:14 PM, Stephan Richter wrote:

> On Friday 13 July 2007 12:14, Jim Fulton wrote:
>> IMO, a could release should have:
>>
>> - a good overview, and preferably
>>
>> - on-line documentation
>
> Right, I think this is well-served for packages that have doctests.  
> I think
> that your example of including the dotest files into the long  
> description is
> a good thing.

I need to get better though on making sure it is truly documentation  
and not just test.  For example, I think it would be better if the  
online buildout documentation was easier to use.

> However, I have noticed some problems with regard to PyPI:
>
> 1. It does not support unicode. I had some problems with characters  
> before,
> but I cannot remember the details.
>
> 2. The PyPI website does not encode the long description, causing  
> text with
> HTML to not display correctly. I have avoided this problem by  
> escaping the
> long description myself, but then you loose the REST conversion. (See
> z3c.form.)

What I've doe with PyPI is a nice hack -- no more. It would be nice  
if some tool made it easy to maintain project home pages. I might  
like something better, but I can live with the hack for now. :)

>> Of course, the standard meta data should be filed in to a reasonable
>> degree.
>
> Okay, I think most of the packages provide a lot of the info with  
> exception of
> the Trove classifiers. They are very important for marketing  
> reasons, because
> the PyPI Package browser (http://cheeseshop.python.org/pypi?% 
> 3Aaction=browse)
> recognizes them and uses them to organize the packages. I think it  
> would be
> awesome, if it would say: "Zope 3 (300 [packages])".

Yup

> OT: Did you notice that 17 out of 20 package updates today where
> Zope-related? :-)

:)

And Zope dependent. :/

>> Mainly what I'm looking for is a good faith effort.
>
> I think in the long term it will be most beneficial, if we convert  
> all tests
> to doctests; then a reasonable on-line documentation is not that  
> hard to
> provide.

Of course, I'm a big fan of doctest.  Not all tests are documentation  
though, even if they are written as doctest.  I'm happy with what  
we've done. We're making good incremental progress.  I think though  
that many of our doctests that aspire to be documentation are  
actually not good documentation.  IMO, we need to separate tests into  
2 classes: executable documentation and tests.  The executable  
documentation needs to be **much more readable than it is now**.  I  
need to start using the footnote feature that Benji and Gary added. I  
suspect that that would help.

Jim

--
Jim Fulton			mailto:jim at zope.com		Python Powered!
CTO 				(540) 361-1714			http://www.python.org
Zope Corporation	http://www.zope.com		http://www.zope.org