[Catalog-sig] Adding package pydoc to PyPI

["Martin v. Löwis"]

> I imagine you are suggesting that I pack everything into the long_description as
> some packages do. Ben Finney responded to my message on distutils-sig saying
> that this was entirely appropriate, and I do believe him. It's the only
> field/resource on PyPI available for doing so...

I also don't see a problem with that.

> 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. Why? Shouldn't you have some
separate home page for the package, then? PyPI is just the package
*index*, not a general project hosting service.

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

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

>     That is, consider the case where your package has a dependency that you have
>     no control over, and you want the pydoc that is generated to link to this
>     package when a class in your package references a class in the
>     dependency(superclass links, for instance).

Again, please give an example. What is your package, what is the package
you depend on, and how would you like the reference to look like?

>  2. I want to use the long_description more as quick marketing material than
>     documentation.
>     "In ~2000 words or less, this is why my package suites your needs..."
>     ie, I want to use the description to *describe* my package as opposed to
>     *documenting* it.

Right. You should put the description on the package's home page.

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

> That is, a standard, if not required, way to publish and view the pydoc of a
> package.

Have you considered using SourceForge? They give you a project home page
on which you can put arbitrary HTML (as long as it follows their usage
restrictions).

Regards,
Martin