[Python-Dev] The docs, reloaded [PEP?]
fuzzyman at voidspace.org.uk
Thu May 24 21:28:50 CEST 2007
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...)
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`.
More information about the Python-Dev