From 73f4268561832394de446ec4a1fafab80ec9224c Mon Sep 17 00:00:00 2001
From: Muhammad Ali <96878085+muhammad-a-dev@users.noreply.github.com>
Date: Thu, 15 Oct 2026 11:53:48 +0500
Subject: [PATCH] docs: consolidate interactive prompt guidance (#1135)

Move prompt style notes into the Code examples section of the style
guide, cross-link markup and style-guide sections, and prefer
copy-and-paste wording.
---
 documentation/markup.rst      |  5 +++++
 documentation/style-guide.rst | 18 +++++++++++++-----
 2 files changed, 18 insertions(+), 5 deletions(-)

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