docs cleanup.

Author: jonathanslenders

docs/images/prompt-with-frame.png

@@ -37,8 +37,6 @@ Further, we can pass a :class:`~prompt_toolkit.styles.Style` instance using the
 
 .. code:: python
 
-    from __future__ import annotations
-
     from prompt_toolkit.formatted_text import HTML
     from prompt_toolkit.shortcuts import choice
     from prompt_toolkit.styles import Style

docs/pages/asking_for_a_choice.rst

@@ -997,6 +997,42 @@ input mode.
     prompt(">", cursor=ModalCursorShapeConfig())
 
 
+Adding a frame
+--------------
+
+A frame can be displayed around the input by passing ``show_frame=True`` as a
+parameter. The color of the frame can be chosen by styling the ``frame.border``
+element:
+
+.. code:: python
+
+    from prompt_toolkit import prompt
+    from prompt_toolkit.styles import Style
+
+    style = Style.from_dict(
+        {
+            "frame.border": "#884444",
+        }
+    )
+
+    answer = prompt("Say something > ", style=style, show_frame=True)
+    print(f"You said: {answer}")
+
+.. image:: ../images/prompt-with-frame.png
+
+It is also possible to pass a :ref:`filter <filters>`, for instance
+``show_frame=~is_done``, so that the frame is only displayed when asking for
+input, but hidden once the input is accepted.
+
+.. code:: python
+
+    from prompt_toolkit import prompt
+    from prompt_toolkit.filters import is_done
+
+    answer = prompt("Say something > ", show_frame=~is_done)
+    print(f"You said: {answer}")
+
+
 Prompt in an `asyncio` application
 ----------------------------------
 

docs/pages/asking_for_input.rst

@@ -1,11 +1,7 @@
 #!/usr/bin/env python
 """
-Autocompletion example.
-
-Press [Tab] to complete the current word.
-- The first Tab press fills in the common part of all completions
-    and shows all the completions. (In the menu)
-- Any following tab press cycles through all the possible completions.
+Example of a frame around a prompt input that has autocompletion and a bottom
+toolbar.
 """
 
 from prompt_toolkit import prompt

examples/prompts/with-frames/frame-and-autocompletion.py

@@ -1,11 +1,7 @@
 #!/usr/bin/env python
 """
-Autocompletion example.
-
-Press [Tab] to complete the current word.
-- The first Tab press fills in the common part of all completions
-    and shows all the completions. (In the menu)
-- Any following tab press cycles through all the possible completions.
+Example of a frame around a prompt input that has autocompletion and a bottom
+toolbar.
 """
 
 from prompt_toolkit import prompt

examples/prompts/with-frames/gray-frame-on-accept.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 """
-Example of a colored prompt.
+Example of a frame around a prompt input.
 """
 
 from prompt_toolkit import prompt