Richard Jones wrote:
On Mon, Mar 7, 2011 at 9:18 AM, M.-A. Lemburg <m...@egenix.com> wrote:
"Martin v. Löwis" wrote:
if anybody would *not* want to have a "Documentation" link automatically
generated that points to packages.python.org/<project>, please speak up.
That would only make sense if there's something uploaded to
the PyPI docs dir.
If PyPI can detect that, +1. Otherwise, I think it's better not
adding such an automatic link, since no link is better than one
going nowhere.
Absolutely - it only generates the link if there's something to link
to (that is, there's been a documentation upload with an index.html
file at the root, or in a top-level "html" directory).
I suggest:
- Generate a link if there is documentation
- Generate the text "No documentation" in the place where the link would
be if there is no documentation.
I have two reasons for suggesting this:
1. I'm thinking explicit is better than implicit here. The link for the
documentation should always be in the same place on the page, so having
a placeholder stating "there's nothing here" will make the page easier
to read. You don't wonder if you missed it, or if something is wrong
that the link disappeared -- it says right there what you want to know.
2. It might remind developers that it is possible to upload
documentation with their package. Currently, a lot of stuff on pypi has
poor or nonexistent documentation; the resource as a whole would be far
more valuable if every package had at least a minimal summary of what it
does and how to use it. (Even if someone has no need for your package,
you still help them if they can determine that _quickly_.)
_______________________________________________
Catalog-SIG mailing list
Catalog-SIG@python.org
http://mail.python.org/mailman/listinfo/catalog-sig
