[Catalog-sig] Adding package pydoc to PyPI

[James William Pye]

On Thu, Jan 31, 2008 at 06:48:12PM +0100, "Martin v. Löwis" wrote:
> PyPI already supports reStructuredText. Why is that not good enough?

Because reST *alone* does not provide a *standard*, if not required, way to publish
and view the pydoc and hierarchy of *all* packages..

[And the long answer... ;]

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

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.

So, here is my list of questions/reasons:

 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?

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

 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.

 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.


Finally, I understand that reST alone can be used to tackle a lot of this, but
it does seem to put a substantial load on each developer to do so. Is something
like this seen to be something that *should* be layered on top of PyPI using
long_descriptions and reST as opposed to something that is integrated and simply
expected or required?

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