diff --git a/documentation/markup.rst b/documentation/markup.rst index 834127891..ca3a5d361 100644 --- a/documentation/markup.rst +++ b/documentation/markup.rst @@ -617,6 +617,8 @@ There is also a generic version of these directives: Describes a Python bytecode instruction. +.. _showing-code-examples: + Showing code examples --------------------- @@ -634,6 +636,9 @@ be no trailing prompt. An example of correct usage is: >>> 1 + 1 2 +Style guidance for when to use secondary prompts, and related copy-and-paste +notes, lives under :ref:`code-examples` in the style guide. + Syntax highlighting is handled in a smart way: * There is a "highlighting language" for each source file. By default, diff --git a/documentation/style-guide.rst b/documentation/style-guide.rst index 9747651b6..05147a745 100644 --- a/documentation/style-guide.rst +++ b/documentation/style-guide.rst @@ -350,11 +350,19 @@ a typical use case. For instance, the :meth:`str.rpartition` method is better demonstrated with an example splitting the domain from a URL than it would be with an example of removing the last word from a line of Monty Python dialog. -The ellipsis for the :py:data:`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. +When writing interactive examples, keep prompt style consistent and copy-friendly: + +* Use the ellipsis for the :py:data:`sys.ps2` secondary interpreter prompt only + sparingly, where it is necessary to clearly differentiate between input lines + and output lines. Besides contributing visual clutter, it makes it harder for + readers to copy-and-paste examples so they can experiment with variations. + (Published docs also offer a copy control on interactive examples that strips + prompts for pasting.) +* After the last line of input or output, do not leave a trailing unused primary + prompt (``>>>``). + +For the reST markup used to present interactive sessions, see +:ref:`showing-code-examples`. Code equivalents