[Python-Dev] The docs, reloaded (original) (raw)

Nick Craig-Wood nick at craig-wood.com
Fri May 25 15:15:05 CEST 2007

On Thu, May 24, 2007 at 12:43:18PM -0500, Ron Adam wrote:

And for console text output, is the unmodified reST suitable, or would it be desired to modify it in some way?

Currently pydoc output looks like a man page under Unix. if it could look like that then that would be great. Otherwise raw reST is fine!

Should a subset of the main documents be included with pydoc to avoid the documents not available messages if they are not installed?

Or should the topics retrieval code be moved from pydoc to the main document tools so it's installed with the documents. Then that can be maintianed with the documents instead of being maintained with pydoc. Then pydoc will just looks for it, instead of looking for the html pages.

I think the latter proposal sounds like the correct one. In debian for instance, the python docs are a seperate package, and it would seem reasonable that you'd have to have that package installed to get the long docs.

> I think that if reST was an acceptable form for the documentation, and > it could be auto included in the main docs from docstrings then you > would find more modules completely documented in doc.

That would be fine for third party modules if they want to do that or if there is not much difference between the two.

If you look at the documentation for subprocess for instance, you'll see that the docstring is pretty much the same as the library reference documentation which seems like needless duplication and opportunity for code/doc skew. Maybe one is auto generated from the other - I don't know!

> Actually if it gave both sets of docs quick, then long, one after the > other that would suit me fine.

That may work well for the full documentation, but the quick reference wouldn't be a short quick reference any more.

Well you could stop after reading the short bit!

I'm attempting to have a pydoc api call that gets a single item or sub-item and format it to a desired output so it can be included in other content. That's makes it possible for the full docs (not necessarily pythons) to embed pydoc output in it if it's desirable. This will need pydoc formatters for the target document type. I hope to include a reST output formatter for pydoc.

The help() function is imported from pydoc by site.py when you start python. It may not be difficult to have it as a function that first tries pydoc to get a request, and if the original request is returned unchanged, tries to get information from the full documentation. There could be a way to select one or the other, (or both). But this feature doesn't need to be built into pydoc, or the full documentation. They just need to be able to work together so things like this are possible in an easy to write 4 or 5 line function. (give or take a few lines) So it looks like most of these issues are more a matter of how to organize the interfaces. It turns out that what I've done with pydoc, and what Georg is doing with the main documentation should work together quite nicely.

Sounds good!

Nick

Nick Craig-Wood <nick at craig-wood.com> -- http://www.craig-wood.com/nick

More information about the Python-Dev mailing list