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.