[issue14218] include rendered output in addition to markup

[Ezio Melotti]

Ezio Melotti <ezio.melotti at gmail.com> added the comment:

My opinion is that in general you should worry about the semantic of the role/directive you are using, rather than its aspect while rendered.
Some entries (especially some directives) might benefit from a rendered example, but I don't think it's necessary to add the output to each role/directive.

Another idea that we were discussing on IRC (and IIRC on another issue that I can't find anymore), was to add at the top a table like:
----------------------------------------
arguments       *arg*
strong text     **strong**
code snippets   ``print('hello world')``
True/False/None ``True``
functions       :func:`sorted`
methods         :meth:`list.sort`
...
----------------------------------------

This will allow people that are searching for the right markup to find quickly what role they should use.

I also agree with Éric that you should always build the doc anyway to check for errors.  Sometimes it happens that I have to experiment a bit if I'm using some uncommon role/directive, but that doesn't happen often, and building the doc a few times is not a problem for me in these cases.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue14218>
_______________________________________