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. _______________________________________________ Distutils-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/distutils-sig
