[Catalog-sig] [Distutils] pypi/packages/docs.python.org

[Mark Sienkiewicz]

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).
>   


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_.)