Ezio Melotti <ezio.melo...@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 <rep...@bugs.python.org>
<http://bugs.python.org/issue14218>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
