[Catalog-sig] Adding package pydoc to PyPI

[James William Pye]

Ok. First. Thank you for giving this message some of your attention. I really do
appreciate the discussion.

On Thu, Jan 31, 2008 at 09:19:52PM +0100, "Martin v. Löwis" wrote:
>> However, it seems poor to pack all the information onto one page. Not to
>> mention, I don't think distutils/setuptools has a command to render the
>> long_description to contain the pydoc of the package--granted this is
>> something for distutils/setuptools, not PyPI.
> 
> Ah, so you want multiple pages per package.

ugh, Yes....

> Why? Shouldn't you have some separate home page for the package, then?

Considering that I'm suggesting a place to publish the pydoc output of the
modules within the package, no, not really. I'll get into why. See the example
below describing the mysterious "inter-package references".

> PyPI is just the package *index*, not a general project hosting service.

But it's okay for a maintainer to use the long_description as a place to publish
documentation?...

> As for generating a long_description - that's something that setup.py
> could do; no need to integrate this into distutils (unless there is
> a strong demand that a certain algorithm to include long_description
> gets included).

The parenthesized portion is kinda getting warmer. =)
The pydoc of all modules in the package...


>>  1. Can I make inter-package references to specific objects in others packages
>>     that won't break if PyPI were to change in some way using reST alone?
> 
> I don't understand the question. What's an "inter-package reference"?
> What's a "specific object"? Give examples.

Sure. I think it would be most illuminating to give an example of what I would
*like* to see. Perhaps reST + <some code> can do this to a certain degree
already.

In this example we have two packages A and B. B depends on package A for a
class. A has a module m1 and B has a module m2. Module m1 has the class c1, and
module m2 has class c2. c2 is a subclass of c1. (class `c1` is an example of a
"specific object").

Now, rather than running epydoc or pydoc and publishing the pydoc of my modules
and all their dependencies for completeness on my project's host. I run an
imaginary "dist_doc" distutils command that extracts the doc-strings and the module
structure/hierarchy from my package. I then run "upload" to upload the XML'ified
doc-strings produced by "dist_doc" to PyPI in addition to my sdist'd or bdist_egg'd
package data.

The XML will describe the package's content and attribute the doc-strings to the
appropriate objects. Now, the difference. When class c2 is described, it will
reference c1, c2 being a subclass of c1. However, it will not include c1's
doc-strings. No sir. It will reference c1 by c1's package and path, "A:m1.c1" or
whatever. So, this allows PyPI to dynamically construct links to the
pydoc documentation of other packages' objects so long as they remembered to
upload the dist_doc(perhaps making it a requirement would be a better solution).
And most importantly, this will provide consistency and convenience for module
authors and users to enjoy as they *know* where to *quickly* find a package's
pydocs.


>>  3. It would simply be nice to have a dedicated part of the package's place on
>>     PyPI specifically designed for displaying the package's module hierarchy and
>>     contents with the associated doc-strings.
> 
> Ok, so you do want a project hosting service.

No. That's not what I'm asking for. I want an extension to PyPI to provide a
place for module developers to publish the *pydocs* of their package in a
structured fashion(ie, not the long_description). Nothing more. I don't want
an SCM. I don't want *arbitrary* webspace. I don't want shell access. I just
want a user-friendly, standard place to publish the pydocs of my package's
modules. (Oh, and I want to read other package's pydocs as well! =)

> I don't think PyPI should 
> provide that, or else people soon find out what a nice file sharing
> platform it is, and start uploading adult content, integrate it into
> link farms, and so on.

I wasn't suggesting any of the material that would be uploaded would be
unchecked. As a matter of fact, I was envisioning a single XML document that
would be checked against a DTD. Oh, and reST could still be used. =) reST in
doc-strings can be made perty just like it is in the long_description.

-

I do understand the perspective that this is beyond the scope of PyPI, and I
respect it. However, as a user of PyPI(almost ten modules, I think), this is
something that would be useful to me and, I believe, others, something that I
would be willing to implement, and something that seems like a very natural
extension for it(PyPI) and distutils.