[Python-Dev] The docs, reloaded

[Georg Brandl]

Ron Adam schrieb:
> 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?

A text writer for docutils should not be hard to write. You'd get something that
looks like the reST, but stripped of markup that makes no sense when viewed on
a terminal, such as :class:`xyz`.

Georg

-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.