classification
Title: pydoc: don’t display raw reST in keyword help
Type: enhancement Stage:
Components: Demos and Tools Versions: Python 3.3
process
Status: closed Resolution: works for me
Dependencies: Superseder:
Assigned To: Nosy List: eric.araujo, georg.brandl, r.david.murray
Priority: normal Keywords:

Created on 2010-12-17 12:17 by eric.araujo, last changed 2010-12-17 15:27 by georg.brandl. This issue is now closed.

Messages (6)
msg124196 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-12-17 12:17
When one runs “pydoc with”, the output is a block of text marked up with reST.  It would be more helpful to render it as text or HTML thanks to a minimal reST parser and transformer.

In http://mail.python.org/pipermail/python-dev/2010-July/101563.html, Martin Geisler (Mercurial dev) said:

“We're using light-weight ReST markup in the Mercurial help texts and
transform it into straight text upon display in the terminal.

We want no external dependencies for Mercurial, so I wrote a "mini ReST"
parser in about 400 lines of code. It cheats a lot and can only handle
simple constructs...” [A few messages later] “I would be happy to relicense it under the Python license.”

So, proposed battle plan:
1) Agree this feature request is desirable.

2) Agree on the inclusion of mg’s minirst, which provides an reST parser and a plain text formatter.

3) Add an HTML formatter.

4) Wire minirst into pydoc.
msg124201 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-12-17 13:07
I'm not necessarily opposed to this, but an alternative is to modify pyspecific.py so that it generates text output from the ReST when it builds the pydoc topic index.
msg124205 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-12-17 14:50
No need for any of that -- the output you see already is the text output from Sphinx.
msg124207 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-12-17 15:14
Well, in that case, can we change the text style for code and related markup to be something prettier?  Normal single quotes, perhaps?
msg124208 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-12-17 15:15
s/prettier/more readable/
msg124210 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-12-17 15:27
Sure, I can do that for the next version.
History
Date User Action Args
2010-12-17 15:27:55georg.brandlsetnosy: georg.brandl, eric.araujo, r.david.murray
messages: + msg124210
2010-12-17 15:15:14r.david.murraysetnosy: georg.brandl, eric.araujo, r.david.murray
messages: + msg124208
2010-12-17 15:14:57r.david.murraysetnosy: georg.brandl, eric.araujo, r.david.murray
messages: + msg124207
2010-12-17 14:50:14georg.brandlsetstatus: open -> closed
nosy: georg.brandl, eric.araujo, r.david.murray
resolution: works for me
2010-12-17 14:50:06georg.brandlsetnosy: georg.brandl, eric.araujo, r.david.murray
messages: + msg124205
2010-12-17 13:07:33r.david.murraysetnosy: + georg.brandl, r.david.murray
messages: + msg124201
components: + Demos and Tools
2010-12-17 12:17:20eric.araujocreate