#45 rendered docstring is not possible to copypaste examples

[Paul Pogonyshev]

Rendered Python prompts (>>> or ...) in docstring blocks make it impossible to copypaste examples. While it would still not always be possible to paste directly to interpreter (because of blank lines), prompts also make it difficult to copy examples to Python files.

There can either be a different block syntax for example code or, preferably, block rendering should be modified in such a way that prompts are either omitted completely, or (even better) not copied. I'm not sure how to accomplish the latter, though.

[Edward Loper]

Logged In: YES
user_id=195958
Originator: NO

I wouldn't want to omit the prompts -- they're useful to the reader in distinguishing the example code from the example output. I wouldn't mind changes that make the prompts omitted when you copy/paste the code, but I won't have time to make that change in the near future. Patches of course would be welcome. For bonus points, add comment markers ("#") in front of the example output lines when you copy/paste them. :)

[Paul Pogonyshev]

Logged In: YES
user_id=1203127
Originator: YES

OK. I can see two ways: put everything in a table with two cells---prompts in one, code in other, side by side with the first,---or use images for prompts. First is not simple to code, second might have usability problems. It's not that important for me to dive into Epydoc code :)

[Edward Loper]

Logged In: YES
user_id=195958
Originator: NO

I made a mock-up of the table approach at [1]. (Click "cell borders on" to see where the table cells are.) It works ok for selecting single commands, but when you try to copy/paste the whole block you get quite odd results. Overall, it doesn't seem to me like an improvement over the current state. Now that Daniele has added a "..python::" directive in restructuredtext, which can be used to render colored blocks in docstrings without prompts, I'm somewhat inclined to close this feature request. The image approach would work in principle, but I would imagine it would cause trouble when people try to change font size.

So, unless anyone speaks up for keeping this feature request open, I'm going to close it as "WontFix".

[1] http://epydoc.sourceforge.net/doctest_block_with_tables.html

[Paul Pogonyshev]

Logged In: YES
user_id=1203127
Originator: YES

Unless I'm mistaken, you cannot put simple cross-links in reST, or no? In that case, reST implementation won't suffice for many Epydoc users, including me.

I personally think that your table approach _is_ an improvement. Mainly because I don't have examples with several docstring blocks (i.e. I'd have only two cells: prompts and the code itself.) However, decide yourself. This is probably not a very important issue.

[Edward Loper]

Logged In: YES
user_id=195958
Originator: NO

So your docstring examples don't generate output?

I'm not sure what you mean about "putting simple cross-links in reST". If you're asking about the equivalent of L{foo}, it's simply `foo`. Or do you mean something else?

[Paul Pogonyshev]

Logged In: YES
user_id=1203127
Originator: YES

Indeed. Need to study reST a bit, maybe it has more appealing features.