[Distutils] Python people want CPAN and how the latter came about

[Lennart Regebro]

On Tue, Dec 22, 2009 at 10:14, Steffen Mueller <smueller at cpan.org> wrote:
> Hi Lennart,
>
> Lennart Regebro <regebro <at> gmail.com> writes:
>> Interesting. I generally don't find automatically generated
>> documentation useful, but if it works for PERL I guess that's a
>> personal taste.
>
> Let me add two nits here:
> It's Perl, not PERL. The name of the language is *not* an acronym. Some people
> are really picky about that.

In a language where you can spell any functionality in millions of
ways, you are not allowed to spell the language however you want!? ;-)
Ok, Pörl. I mean Perl. :-)

> More importantly, it's not "auto-generated" documentation per se. Not something
> like using doxygen to generate an API reference purely from the function/method
> name and signature. Instead, search.cpan.org (and kobesearch) extract the
> inlined documentation from the Perl modules. This documentation was written by
> the authors. It was *not* generated from the code itself. Here's what that looks
> like for a random one of my modules:
> http://search.cpan.org/~smueller/PAR-Repository-Client/lib/PAR/Repository/
> Client.pm

OK, so that would be docstrings and stuff then. It's true, if we had
something like that it would work as an incentive for making more such
documentation.

> You could get the same page via
> http://search.cpan.org/perldoc?PAR::Repository::Client. This is an example of
> how CPAN works on namespace and distribution level. After a new file is
> uploaded, its contained namespaces (packages/class names) are added to the
> index if they're not already there.

How does it handle if two modules implement the same namespace?

> The index always contains a reference to
> the distribution that contains the newest *authorized* version of any
> namespace.

Who authorizes it?

> We have a band of PAUSE admins with super cow powers to save the day. It's not
> like there's a lot of us, but so far, we've been able to handle authorization
> requests reasonably. Our policy in case an author goes missing who has
> permissions for a certain namespace are documented here:
> http://search.cpan.org/CPAN/modules/04pause.html#takeover

I have to say that I vastly prefer not to have any authorization and
allow anyone to release anything in any namespace. But then I am
getting fanatically anarchical in these issues. You can not organize
freedom.

>> So far we have identified a "show all versions" link, and
>> automatically generated documentation. Thanks! Finally something
>> concrete!
>
> In a very concrete context: I really like how search.cpan.org will show you the
> latest stable version by default and provide drop-downs to select any developer
> (alpha) or old releases. It also has nice, consistent URLs as demonstrated
> above. ...~author will get me to author's overview page, .../dist/XXX will get
> me to the XXX distribution's overview, etc. Accessing any files within each
> distribution is possible via similar URLs.

The only thing I can see there that's missing is the "drop down", or
link to a list of all versions or similar. That would also make it
easier to make alpha versions, they would be easily viewable, but not
shown and listed by default.
We should suggest that to Martin v Löwis.

> Another point that I really like about the service is that the distribution
> pages provide links to many other related services that are run by other
> volunteers. Take for example http://search.cpan.org/dist/PAR-Repository-Client/
> There is a link to cpanforum, specifically the relevant discussion forum for the
> module at hand. It shows a link to the bug/request tracker with the number of
> open bugs, the one next to it will display a nice hierarchical (recursive) list
> of dependencies.

Right, those third-party services doesn't exist for PyPI.

-- 
Lennart Regebro: Python, Zope, Plone, Grok
http://regebro.wordpress.com/
+33 661 58 14 64