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:[EMAIL PROTECTED] Python
Powered!
CTO (540) 361-1714
http://www.python.org
Zope Corporation http://www.zope.com http://www.zope.org
_______________________________________________
Zope3-dev mailing list
Zope3-dev@zope.org
Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com
