[issue14218] include rendered output in addition to markup

[Terry J. Reedy]

Terry J. Reedy added the comment:

The link in the first message does not work. This should:
https://docs.python.org/devguide/documenting.html
The section under discussion, which pydev controls, as opposed to the full .rst doc at http://docutils.sourceforge.net/rst.html, is
https://docs.python.org/devguide/documenting.html#restructuredtext-primer
https://docs.python.org/devguide/documenting.html#additional-markup-constructs

I still agree in general with the request. What I tried to say before is that showing results somehow reinforces learning. Why does the tutorial start with
>>> 2 + 2
4
? Everyone *knows* that 2 + 2 is 4. Yet is helps to show that Python actually does the right thing. Tshepang is asking for something similar.

I agree that one or more tables are needed. The example given could have a third column. One thing good about the table is that is gives the goal first, and then the means. Contrast that with 
  one asterisk: *text* for emphasis (italics),
This sentence might be ok for a reading guide (if I see one asterisk, what does it mean), but not for choosing what to write.

Here is a sentence that would be really clearer with the result:
"it must be separated from surrounding text by non-word characters. Use a backslash escaped space to work around that: thisis\ *one*\ word."
It took me several seconds to really get that the result would be "thisisONEword", where the capitals indicate italics.

This sentence I do not understand. "Every explicit markup block which isn’t a valid markup construct (like the footnotes above) is regarded as a comment." It seems to say that the footnote markup given is not valid. And what does 'regarded as a comment' mean? Is the invalid markup block deleted? specially displayed? or displayed normally?

As for style differences: the guide could start with "The exact way markup is rendered depends on the theme. The examples below are rendered with the 'devguide' theme used for the rest of the devguide."

I am probably the best person nosy here to write at least a draft of a patch since I believe it is needed, have some sense of doc style, but still know .rst poorly enough to have difficulties with the current version. It would be a good way to finally learn the markup.

It is somewhat confusing that many of the same topics are covered twice, first for standard .rst, and then for python extensions. Ezio's example table seems to combine both. If this is done (and I think it helpful), there should be a column indicating which is which.

----------

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