[Distutils] Publishing Documentation

[James William Pye]

I use PyPI to publish my Python modules, and it is great. I love just running
'upload' and being more or less done with distribution.

However, the current pain point I have with releasing is the associated
documentation.  It's not that I can't publish the information somewhere,
it's just that it's inconvenient at best. (yes, I know, "my problem")

My question is what thoughts have people had about extending PyPI and
distutils/setuptools to manage the publication of package documentation
in addition to package releases?


I see some fantastic advantages to having the publication of documentation being
handled by distutils/setuptools and PyPI:

Covenience. A `publish` command pushing the documentation into the
repository and being done with it would be a bit of a dream to me. Most of my
documentation is targeted at developers so a doc-string based mechanism similar
to pydoc--but on PyPI--would suite my and most developers needs. This also
encourages the production of better modules by removing mundane hurdles involved
in providing quality Python modules.

Cross-package integration. A painful aspect of serving documentation is that it
is desireable to have complete references to superclasses and other
referenced objects. With a setuptools based `publish` command, I imagine that
documentation could be extracted in a way that allows class references to be
associated with the packages that they come from, opening the door for
PyPI package based external-reference resolution:

 Package A and B providing module m1 and m2 with classes c1 and c2:

  B.m2.c2 inherits from A.m1.c1
  Package B depends on package A. [ultimately for class c1]

  `publish` realizes this link while walking package B's modules and denotes
  that the link should be created to package A.m1.c1 for describing B.m1.c2.

Easy cross-references. With PyPI managing the documentation, cross-references
to Python object documentation should be easy to implement. A stylesheet PI
could probably render the appropriate XML.


Okay, so epydoc and others can make documentation, and you're one rsync away
from having it published. It's still not convenient and it creates an
interface inconsistency across packages that makes "taking in" multiple
projects more difficult than an integrated solution.


I think I should also mention that I've seen some packages basically publish
their documentation in the package's long_description... Seems like it would be
a good idea to provide a more appropriate place for this information.