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. 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 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. The index always contains a reference to the distribution that contains the newest *authorized* version of any namespace. Thus, you can access the distribution directly like in the first URL or have search.cpan.org go from package name to the most recent authorized version automatically (via the perldoc link). > > 4. Namespaces and some way of reserving them. There are likely many > > modules named postgresql on PyPI, but there's only one DBD::Pg (although > > there are other PostgreSQL modules that implement the perl DBI driver > > interface). This also helps with specifying dependencies. > > There is no reserving in the Python world, that's true. I'm skeptical. > There's enough problems with packages not being updated, we don't want > that for namespaces too, that would be terrible. 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 > > It definitely appears to have the framework, but lacks some finishing > > touches that would enormously enhance usability. > > 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. 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. Again. Run by another volunteer. The line below is dedicated to CPAN testers results. It shows the number of FAIL/PASS/UNKNOWN results followed by a link to the page with the raw reports and -- this is extremely useful as an author -- a colourful matrix that shows the test results depending on perl version and operating system. My example in this mail is not a very widely used module. Thus, the matrix is somewhat sparse, too: http://matrix.cpantesters.org/?dist=PAR-Repository-Client+0.25. But it clearly shows my module isn't compatible to really old versions of Perl (5.6). In some other cases, I might learn that it isn't working well on some operating system because its column is red or yellow. Here's an example of a more widely used and installed distribution: http://matrix.cpantesters.org/?dist=Data-Dumper+2.125. As an author, these tools help me identify weak points or portability problems in my software. As a user, this can help me understand whether I really want to rely on this piece of software for my business. Everyone wins. Please don't take any of this the wrong way. I'm not trying to say "look what we can do and you don't" at all. Not only do I have no idea what the python tools look like, but in the previous two paragraphs, I am really just trying to point out a few technical strong points of various CPAN-related services that are very valuable to me as a user, developer and contributor. Best regards, Steffen _______________________________________________ Distutils-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/distutils-sig
