[issue14218] include rendered output in addition to markup

Brett Cannon added the comment: Moved to https://github.com/python/devguide/issues/14 -- nosy: +brett.cannon resolution: -> out of date status: open -> closed ___ Python tracker

[issue14218] include rendered output in addition to markup

Changes by Carol Willing willi...@willingconsulting.com: -- nosy: +willingc ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue14218 ___ ___

[issue14218] include rendered output in addition to markup

Changes by Berker Peksag berker.pek...@gmail.com: -- keywords: +easy ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue14218 ___ ___ Python-bugs-list

[issue14218] include rendered output in addition to markup

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

[issue14218] include rendered output in addition to markup

Ezio Melotti added the comment: 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. -- stage:

[issue14218] include rendered output in addition to markup

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

[issue14218] include rendered output in addition to markup

Tshepang Lekhonkhobe tshep...@gmail.com added the comment: Ezio Melotti ezio.melo...@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:

[issue14218] include rendered output in addition to markup

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

[issue14218] include rendered output in addition to markup

Terry J. Reedy tjre...@udel.edu added the comment: 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

[issue14218] include rendered output in addition to markup

Tshepang Lekhonkhobe tshep...@gmail.com added the comment: Éric Araujo mer...@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

[issue14218] include rendered output in addition to markup

Éric Araujo mer...@netwok.org added the comment: 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

[issue14218] include rendered output in addition to markup

Tshepang Lekhonkhobe tshep...@gmail.com added the comment: 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

[issue14218] include rendered output in addition to markup

Éric Araujo mer...@netwok.org added the comment: 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.

[issue14218] include rendered output in addition to markup

Éric Araujo mer...@netwok.org added the comment: 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. :) --

[issue14218] include rendered output in addition to markup

Sandro Tosi sandro.t...@gmail.com added the comment: 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

[issue14218] include rendered output in addition to markup

Tshepang Lekhonkhobe tshep...@gmail.com added the comment: Sandro Tosi sandro.t...@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 -- ___ Python tracker

[issue14218] include rendered output in addition to markup

New submission from Tshepang Lekhonkhobe tshep...@gmail.com: 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. -- components: Devguide messages: 155061 nosy:

[issue14218] include rendered output in addition to markup

Sandro Tosi sandro.t...@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 -- nosy: +sandro.tosi versions: -Python 2.6, Python 3.1 ___ Python tracker rep...@bugs.python.org

[issue14218] include rendered output in addition to markup

Sandro Tosi sandro.t...@gmail.com added the comment: additionally, devguide has no version associated with it. -- versions: -Python 2.7, Python 3.2, Python 3.3 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue14218

[issue14218] include rendered output in addition to markup

Tshepang Lekhonkhobe tshep...@gmail.com added the comment: Sandro Tosi sandro.t...@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. --

[issue14218] include rendered output in addition to markup

Éric Araujo mer...@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? It's