Message155233
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. |
|
Date |
User |
Action |
Args |
2012-03-09 14:28:51 | ezio.melotti | set | recipients:
+ ezio.melotti, eric.araujo, sandro.tosi, tshepang |
2012-03-09 14:28:51 | ezio.melotti | set | messageid: <1331303331.89.0.239979152935.issue14218@psf.upfronthosting.co.za> |
2012-03-09 14:28:51 | ezio.melotti | link | issue14218 messages |
2012-03-09 14:28:50 | ezio.melotti | create | |
|