This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author ezio.melotti
Recipients eric.araujo, ezio.melotti, sandro.tosi, tshepang
Date 2012-03-09.14:28:50
SpamBayes Score 2.1062616e-09
Marked as misclassified No
Message-id <1331303331.89.0.239979152935.issue14218@psf.upfronthosting.co.za>
In-reply-to
Content
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.
History
Date User Action Args
2012-03-09 14:28:51ezio.melottisetrecipients: + ezio.melotti, eric.araujo, sandro.tosi, tshepang
2012-03-09 14:28:51ezio.melottisetmessageid: <1331303331.89.0.239979152935.issue14218@psf.upfronthosting.co.za>
2012-03-09 14:28:51ezio.melottilinkissue14218 messages
2012-03-09 14:28:50ezio.melotticreate