[Zope3-dev] Re: Windows eggs
Wichert Akkerman
wichert at wiggy.net
Fri Jul 13 17:09:30 EDT 2007
Previously Tres Seaver wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> 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. 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.)
> >
> >> 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])".
> >
> > OT: Did you notice that 17 out of 20 package updates today where
> > Zope-related? :-)
> >
> >> 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.
>
> - -1. "Good tests" don't always make "good documentation"; I prefer the
> isolation of traditional unittests for anything other than "main line"
> use cases, for which doctests are best suited.
Amen. I find failing doctests to be much harder to debug as well. I use
doctests as a method to make sure examples in my documentation are
correct, which is very useful.
Wichert.
--
Wichert Akkerman <wichert at wiggy.net> It is simple to make things.
http://www.wiggy.net/ It is hard to make things simple.
More information about the Zope3-dev
mailing list