You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In the Documentation chapter, Style Guide / Code Examples has
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.
(Perhaps it should be mentioned here that doctesting the code example requires such differentiation and hence requires secondary prompts. Perhaps the primary prompt should also be left off.)
Representing an interactive session requires including the prompts and output along with the Python code. No special markup is required for interactive sessions. After the last line of input or output presented, there should not be an “unused” primary prompt; this is an example of what not to do:
>>>1 + 1
2
>>>
I think both advices should be in the same place and a reference added in the other.
The text was updated successfully, but these errors were encountered:
FWIW I think the first paragraph predates the [>>>] button at the top right of interactive code examples, which I added to make it easier to copy1-and-paste. On one hand the button requires an extra click and people might not notice it, so there is still some advantage of leaving the secondary prompts out, but on the other hand the lack of secondary prompts looks inconsistent with the actual interactive interpreter and might create confusion and -- as you mentioned -- it also breaks doctests.
Omitting the "unused" prompt at the end is a good advice.
Footnotes
the quoted text uses cut which seems wrong here. ↩
In the Documentation chapter, Style Guide / Code Examples has
(Perhaps it should be mentioned here that doctesting the code example requires such differentiation and hence requires secondary prompts. Perhaps the primary prompt should also be left off.)
reStructured Text Markup / Additional Markup Constructs / Showing Code Examples has
I think both advices should be in the same place and a reference added in the other.
The text was updated successfully, but these errors were encountered: