Some missing newlines for prompts

[slateny]

For example, in the enum howto (source) becomes

class Perm(IntFlag):
    R = 4
    W = 2
    X = 1
    RWX = 7
Perm.RWX

~Perm.RWX

Perm(7)

but when pasted into the prompt, gives

>>> class Perm(IntFlag):
...     R = 4
...     W = 2
...     X = 1
...     RWX = 7
... Perm.RWX
  File "<stdin>", line 6
    Perm.RWX
    ^^^^
SyntaxError: invalid syntax

There are a number of such examples that could use a newline with ... for ease of pasting.

#98993

Linked PRs

• gh-99087: Add missing newline for prompts in docs #98993

[erlend-aasland]

Making it easier to copy & paste is a valid point, in my opinion. I find the style guide a little hard to interpret regarding the secondary prompt:

The ellipsis for the sys.ps2 secondary interpreter prompt should only be used sparingly, where it is necessary to clearly differentiate between input lines and output lines. Besides contributing visual clutter, it makes it difficult for readers to cut-and-paste examples so they can experiment with variations.

[erlend-aasland]

It should be noted that C&P is only a problem when pasting into the REPL.

[pochmann]

Regarding this:

makes it difficult for readers to cut-and-paste examples so they can experiment with variations.

Is that argument still valid? The >>> button at the top-right of the code blocks toggles the >>> and ... away, so there's no such difficulty.

[erlend-aasland]

I find that whole sentence kinda confusing. It's not clear to me what's being copied/cut, it is not clear to me what the existing difficulties the dev guide points to are, it's not clear to me if the dev guide suggests pasting into a source file or into the REPL prompt...

[pochmann]

Hmm, yeah, readers can't cut. Only copy.

I believe:

what's being copied

The code, with or without the extra >>> and ....

what the existing difficulties the dev guide points to are

The >>> and ... aren't executable, so you need to remove them in order to execute the code. Annoying if you need to do that manually.

if the dev guide suggests pasting into a source file or into the REPL prompt...

Both. The extra >>> and ... are a problem in both cases.

[erlend-aasland]

what's being copied

The code, with or without the extra >>> and ....

Let me be slightly more accurate: for examples where Sphinx implicitly adds prompts to the rendered output, you can choose to display the prompts or to hide them. Example from the enum docs:

Versus:

Trying to copy and paste from the former into the REPL of course results in a disaster. Trying to copy and paste from the latter into the REPL is less a disaster, but results in a syntax error. However, if you paste the latter into a new source file, you'll be able to run it without problems.

[erlend-aasland]

if the dev guide suggests pasting into a source file or into the REPL prompt...

Both. The extra >>> and ... are a problem in both cases.

You assume you know what is being copied and where it is being copied. These details matter, hence my initial comments.

If you click the upper right >>> icon, the prompts will disappear, and if you now try to copy and paste into a file, there will be no problem. You are assuming that the user did not click on the >>> icon. Which leads us back to my initial comment: we do not know what the dev guide is assuming the user is copying (with or without prompts? it might be the latter!), and we do not know where the dev guide is assuming the user is pasting (into a REPL or into a file?). If a user is copying with prompts, there will of course be havoc not matter where the ill-copied source code is pasted. If a user is copying without prompts, there may be a problem, but it depends on where the user is pasting the now potentially-ok source code.

[erlend-aasland]

Let's get back to the problem that Stanley has highlighted:

If a doctest-style¹ example is missing an empty line or a single ellipsis prompt, the user may run into syntax errors if they copy and paste code into the REPL, even if they disable the prompts (using the >>> "button") before copying. This is unfortunate, as it may be surprising to a beginner. I believe it is worth fixing. I also believe it is worth revisiting the wording in the dev guide to make it more accurate, thus providing better guidance for core devs and doc writers.

Footnotes

1. an example mimicing an interactive session, using Sphinx' own words ↩

[pochmann]

You are assuming that the user did not click on the >>> icon

No, I'm assuming that the >>> icon didn't exist back when that style guide was written. (It's at least 11 years old.)

[erlend-aasland]

Regarding the dev guide.

Before

The ellipsis for the sys.ps2 secondary interpreter prompt should only be used sparingly, where it is necessary to clearly differentiate between input lines and output lines. Besides contributing visual clutter, it makes it difficult for readers to cut-and-paste examples so they can experiment with variations.

Possible improvement (shot in the dark)

For examples mimicing interactive input, the ellipsis [...] should be used so that, for HTML rendered output, examples can be copied and pasted into the REPL prompt after the prompts have been hidden by the user using the >>> icon. Example: [...]
For examples mimicing interactive input where the secondary prompt has no effect if copied and pasted into the REPL prompt, it should be omitted in order to declutter the rendered output.
Example: [...]

[erlend-aasland]

No, I'm assuming that the >>> didn't exist back when that style guide was written. (It's at least 11 years old.)

I prefer not to assume, and I prefer docs to not assume things either. Explicit docs are to be preferred. That goes both for the user docs (docs.python.org) and for the dev guide.