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

Ron Adam rrr at ronadam.com
Thu May 24 19:43:18 CEST 2007

Nick Craig-Wood wrote:

On Wed, May 23, 2007 at 12:46:50PM -0500, Ron Adam wrote:

Nick Craig-Wood wrote:

So I'll be able to read the main docs for a module in a terminal without reaching for the web browser (or info)? That would be great!

How would pydoc decide which bit of docs it is going to show? Pydoc currently gets topic info for some items by scraping the text from document 'local' web pages. This is kind of messy for a couple of reasons.

  • The documents may not be installed locally.
  • It can be problematic locating the docs even if they are installed.
  • They are not formatted well after they are retrieved.

I think this is an area for improvement.

And it would be improved by converting the docs to reST I imagine.

Yes, this will need a reST to html converter for displaying in the html browser. DocUtils provides that, but it's not part of the library. (?)

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

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.

This feature is also limited to a small list where the word being searched for is a keyword, or a very common topic reference, and they are not likely to clash with other module, class, or function names.

The introspection help parts of pydoc are completely separate from topic help parts. So replacing this part can be done without much trouble. What the best behavior is and how it should work would need to be discussed.

Keep in mind doc strings are meant to be more of a quick reference to an item, and Pydoc is the interface for that.

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 I type "pydoc re" is it going to give me the rather sparse doc from the re module or the nice reST docs? Or maybe both, one after the other? Or will I have to use a flag to dis-ambiguate? If retrieval from the full docs is desired, then it will probably need to be disambiguated in some way or be a separate interface.

help('re') # Quick reference on 're'. helpdocs('re') # Full documentation for 're'.

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.

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.

Cheers, Ron

More information about the Python-Dev mailing list