Ok. First. Thank you for giving this message some of your attention. I really do appreciate the discussion.
On Thu, Jan 31, 2008 at 09:19:52PM +0100, "Martin v. Löwis" wrote: >> 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. ugh, Yes.... > Why? Shouldn't you have some separate home page for the package, then? Considering that I'm suggesting a place to publish the pydoc output of the modules within the package, no, not really. I'll get into why. See the example below describing the mysterious "inter-package references". > 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?... > 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... >> 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. Sure. I think it would be most illuminating to give an example of what I would *like* to see. Perhaps reST + <some code> can do this to a certain degree already. In this example we have two packages A and B. B depends on package A for a class. A has a module m1 and B has a module m2. Module m1 has the class c1, and module m2 has class c2. c2 is a subclass of c1. (class `c1` is an example of a "specific object"). Now, rather than running epydoc or pydoc and publishing the pydoc of my modules and all their dependencies for completeness on my project's host. I run an imaginary "dist_doc" distutils command that extracts the doc-strings and the module structure/hierarchy from my package. I then run "upload" to upload the XML'ified doc-strings produced by "dist_doc" to PyPI in addition to my sdist'd or bdist_egg'd package data. 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. >> 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. 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! =) > 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. I wasn't suggesting any of the material that would be uploaded would be unchecked. As a matter of fact, I was envisioning a single XML document that would be checked against a DTD. Oh, and reST could still be used. =) reST in doc-strings can be made perty just like it is in the long_description. - 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. _______________________________________________ Catalog-SIG mailing list Catalog-SIG@python.org http://mail.python.org/mailman/listinfo/catalog-sig
