pydoc: don’t display raw reST in keyword help

[merwok]

BPO	10726
Nosy	@birkenfeld, @merwok, @bitdancer

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2010-12-17.14:50:14.268>
created_at = <Date 2010-12-17.12:17:20.393>
labels = ['type-feature']
title = 'pydoc: don\xe2\x80\x99t display raw reST in keyword help'
updated_at = <Date 2010-12-17.15:27:55.316>
user = 'https://github.com/merwok'

bugs.python.org fields:

activity = <Date 2010-12-17.15:27:55.316>
actor = 'georg.brandl'
assignee = 'none'
closed = True
closed_date = <Date 2010-12-17.14:50:14.268>
closer = 'georg.brandl'
components = ['Demos and Tools']
creation = <Date 2010-12-17.12:17:20.393>
creator = 'eric.araujo'
dependencies = []
files = []
hgrepos = []
issue_num = 10726
keywords = []
message_count = 6.0
messages = ['124196', '124201', '124205', '124207', '124208', '124210']
nosy_count = 3.0
nosy_names = ['georg.brandl', 'eric.araujo', 'r.david.murray']
pr_nums = []
priority = 'normal'
resolution = 'works for me'
stage = None
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue10726'
versions = ['Python 3.3']

[merwok]

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.

[bitdancer]

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.

[birkenfeld]

No need for any of that -- the output you see already is the text output from Sphinx.

[bitdancer]

Well, in that case, can we change the text style for code and related markup to be something prettier? Normal single quotes, perhaps?

[bitdancer]

s/prettier/more readable/

[birkenfeld]

Sure, I can do that for the next version.