[Python-Dev] The docs, reloaded [PEP?]

[Michael Foord]

This subject is generating a lot of discussion and [almost entirely] 
positive feedback. It would be a great shame to run out of steam.

Does it need a PEP to see a chance of it getting accepted as the formal 
documentation system? (or a pronouncement that it will never happen...)

Michael Foord


Georg Brandl wrote:
> 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
>
>