[Catalog-sig] [Distutils] pypi/packages/docs.python.org
sienkiew at stsci.edu
Mon Mar 7 22:06:38 CET 2011
Richard Jones wrote:
> On Mon, Mar 7, 2011 at 9:18 AM, M.-A. Lemburg <mal at 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).
- 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_.)
More information about the Catalog-SIG