[Catalog-sig] Adding package pydoc to PyPI

["Martin v. Löwis"]

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

The full documentation? That's probably abuse, but we have no resources
to screen the packages for that, so that use is tolerated (for now,
until people start complaining).

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

A warning, though: a request by a single user can never be strong
demand.

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

Ok. See above - I would now think that's abuse of PyPI; you should find 
a different place for the package documentation on the net (whether 
single-paged or multi-paged), and then use standard HTML linking for
these cross-references.

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

See, that's already asking too much, IMO. To me, that's clearly out of 
scope for PyPI.

> 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! =)

If you think there is demand for such a service (publishing pydoc only), 
feel free to offer it to the community. I don't see the need for such
a service to be centralized, and you might actually be able to implement
it even for packages that don't actively use it, by extracting such
pydoc pages from any new package that gets uploaded.

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

See above. If you implement the service, I would consider it feasible
to provide a link to a package's pydoc documentation in PyPI
(similar to homepage and download_url; say documentation_url), although
support for that in distutils probably requires a PEP.

Regards,
Martin