include rendered output in addition to markup

[tshepang]

BPO	14218
Nosy	@brettcannon, @terryjreedy, @ezio-melotti, @merwok, @sandrotosi, @willingc

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2016-07-22.19:56:25.699>
created_at = <Date 2012-03-07.09:06:33.495>
labels = ['easy', 'type-feature', 'docs']
title = 'include rendered output in addition to markup'
updated_at = <Date 2016-07-22.19:56:25.697>
user = 'https://bugs.python.org/tshepang'

bugs.python.org fields:

activity = <Date 2016-07-22.19:56:25.697>
actor = 'brett.cannon'
assignee = 'none'
closed = True
closed_date = <Date 2016-07-22.19:56:25.699>
closer = 'brett.cannon'
components = ['Devguide']
creation = <Date 2012-03-07.09:06:33.495>
creator = 'tshepang'
dependencies = []
files = []
hgrepos = []
issue_num = 14218
keywords = ['easy']
message_count = 19.0
messages = ['155061', '155067', '155068', '155076', '155127', '155154', '155165', '155176', '155177', '155178', '155179', '155180', '155233', '155240', '155241', '155275', '171035', '217148', '271024']
nosy_count = 7.0
nosy_names = ['brett.cannon', 'terry.reedy', 'ezio.melotti', 'eric.araujo', 'sandro.tosi', 'tshepang', 'willingc']
pr_nums = []
priority = 'normal'
resolution = 'out of date'
stage = 'needs patch'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue14218'
versions = []

[tshepang]

For devguide/documenting, If you show me markup, also show me what output it gives me. It's kinda tedious to keep building the markup just to verify how it's rendered.

[sandrotosi]

3.1 and 2.6 as in security fix only: please don't add those versions for non-sec issue

[sandrotosi]

additionally, devguide has no version associated with it.

[tshepang]

Sandro Tosi <sandro.tosi@gmail.com> added the comment:

3.1 and 2.6 as in security fix only: please don't add those versions for non-sec issue

Sorry, I thought there was an exception for documentation issues.

[merwok]

For devguide/documenting, If you show me markup, also show me what output it gives me.
Would this really be useful? If you’re looking at that page, you want to know what markup to use for what situation; why do you care about output?

It's kinda tedious to keep building the markup just to verify how it's rendered.
I’m not sure I understand; if there were example output in the doc, you’d only have to build the devguide once to see how markup is rendered, wouldn’t you?

[tshepang]

Éric Araujo <merwok@netwok.org> added the comment:
> For devguide/documenting, If you show me markup, also show me what output it gives me.
Would this really be useful?  If you’re looking at that page, you want to know what markup to use for what situation; why do you care about output?

I want to see how it looks like.

> It's kinda tedious to keep building the markup just to verify how it's rendered.
I’m not sure I understand; if there were example output in the doc, you’d only have to build the devguide once to see how markup is rendered, wouldn’t you?

Yes you didn't understand, sorry for my inadequate explanation.

I want to see how the output of the markup looks like, without having
to do the rendering (running sphinx-build) myself.

[merwok]

I don’t understand why you don’t want to build the doc if you want to see what the output looks like. You should build the doc anyway before making a patch to make sure there are no errors, and it does not take that long. As I don’t understand your problem, I disagree to making the doc longer for this.

[tshepang]

Okay, let me try again:

I want the documentation tutorial to tell me, for example, (1) here is the markup for a code block, and (2) here is what it looks like. At the moment, I only get (1)... point is I do not want to have to rebuild a reST file each time I want to see what some specific markup (e.g. a code block) would look like.

[merwok]

I don’t get why you want to know what it looks like, and then, I don’t get why you can’t build the doc or look at docs.python.org. Also, not getting what you talk about re-building: building the devguide or docs once should be enough.

[merwok]

It looks like I have a hard time putting myself in your shoes and seeing what you want, so I’m going to shut up for a while and let Ezio and Sandro state their opinion on your original request. :)

[sandrotosi]

eheh yeah it seems so :)

What I think Tshepang wants is this:

• the devguide contains the description of how to document python
• that documentation is about a set of ReST coding commands that
  generate the desired output
• currently the devguide reports only the ReST code block without,
  right below to that block, the resulting highlitening.
  -> add the resulting "visual" output right below the description of
  the code to use.

so something like

blablabla you have to use word to have the word in bold (or
whatever it generates, I'm too lazy to check :) ) for example:

<insert here the visual output of a ReST doc where word is used>

Tshepang: did I get it correctly? Éric: is it (at least a bit) clearer?

[tshepang]

Sandro Tosi <sandro.tosi@gmail.com> added the comment:
Tshepang: did I get it correctly? Éric: is it (at least a bit) clearer?

that's exactly what I tried to convey

[ezio-melotti]

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.

[tshepang]

Ezio Melotti <ezio.melotti@gmail.com> added the comment:
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.

That would be a good idea. A quick ref check without all the prose.

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.

I also agree. I'm just thinking someone who reads that doc should be
able to see the output without building anything. That is, reading the
doc doesn't necessarily mean you want to apply what you just learned
"right now". There's also "just in case" or "curiosity" learning.

[ezio-melotti]

I also agree. I'm just thinking someone who reads that doc should be
able to see the output without building anything.

Indeed I wasn't thinking about this use case, but IME people learn most of they know about rst "on the field" (i.e. by imitating what they see in the doc page they are working on), and then go check the devguide to expand their knowledge and make sure they are using the markup correctly.

[terryjreedy]

It is not unusual and perhaps common for markup documentation to give rendered output for example input. This is similar to what we do in the tutorial and elsewhere with interactive examples:
>>> 2 + 2 # input code
4         # output of running the code

This may be fairly easy. Since the page is a rendered page, I presume some quoting mechanism is used to keep example text as is without being rendered. If so, all that should be needed is the same marked up text in a second box directive but without the quoting, so that it is rendered.

[ezio-melotti]

Another issue with this is that the devguide and the docs use different themes, so there's no guarantee that the output will look the same.

Some output examples (and the table I mentioned earlier) could still be added for a few cases though.

[terryjreedy]

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.

[brettcannon]

Moved to python/devguide#14