Add visual docs (wip)

Author: johnslavik

Lib/_pyrepl/content.py

@@ -7,6 +7,17 @@
 
 @dataclass(frozen=True, slots=True)
 class ContentFragment:
+    """A single display character with its visual width and style.
+
+    The body of ``>>> def greet`` becomes one fragment per character::
+
+        d  e  f     g  r  e  e  t
+        ╰──┴──╯     ╰──┴──┴──┴──╯
+        keyword       (unstyled)
+
+    e.g. ``ContentFragment("d", 1, StyleRef(tag="keyword"))``.
+    """
+
     text: str
     width: int
     style: StyleRef = StyleRef()
@@ -21,7 +32,21 @@ class PromptContent:
 
 @dataclass(frozen=True, slots=True)
 class SourceLine:
-    """One logical line from the editor buffer, before styling."""
+    """One logical line from the editor buffer, before styling.
+
+    Given this two-line input in the REPL::
+
+        >>> def greet(name):
+        ...     return name
+                       ▲ cursor
+
+    The buffer ``"def greet(name):\\n    return name"`` yields::
+
+        SourceLine(lineno=0, text="def greet(name):",
+                   start_offset=0, has_newline=True)
+        SourceLine(lineno=1, text="    return name",
+                   start_offset=17, cursor_index=14)
+    """
 
     lineno: int
     text: str
@@ -36,6 +61,15 @@ def cursor_on_line(self) -> bool:
 
 @dataclass(frozen=True, slots=True)
 class ContentLine:
+    """A logical line paired with its prompt and styled body.
+
+    For ``>>> def greet(name):``::
+
+        >>> def greet(name):
+        ╰─╯ ╰──────────────╯
+        prompt       body: one ContentFragment per character
+    """
+
     source: SourceLine
     prompt: PromptContent
     body: tuple[ContentFragment, ...]

Lib/_pyrepl/layout.py

@@ -11,7 +11,16 @@
 
 @dataclass(frozen=True, slots=True)
 class LayoutRow:
-    """Metadata for one physical screen row."""
+    """Metadata for one physical screen row.
+
+    For the row ``>>> def greet(name):``::
+
+        >>> def greet(name):
+        ╰─╯ ╰──────────────╯
+         4    char_widths=(1,1,1,…)  ← 16 entries
+              buffer_advance=17      ← includes the newline
+    """
+
     prompt_width: int
     char_widths: tuple[int, ...]
     suffix_width: int = 0
@@ -33,7 +42,13 @@ def screeninfo(self) -> ScreenInfoRow:
 class LayoutMap:
     """Mapping between buffer positions and screen coordinates.
 
-    Single source of truth for cursor placement.
+    Single source of truth for cursor placement.  Given::
+
+        >>> def greet(name):     ← row 0, buffer_advance=17
+        ...     return name      ← row 1, buffer_advance=15
+                       ▲cursor
+
+    ``pos_to_xy(31)`` → ``(18, 1)``:  prompt width 4 + 14 body chars.
     """
     rows: tuple[LayoutRow, ...]
 
@@ -102,7 +117,14 @@ def xy_to_pos(self, x: int, y: int) -> int:
 
 @dataclass(frozen=True, slots=True)
 class WrappedRow:
-    """One physical screen row after wrapping, with all metadata needed for rendering."""
+    """One physical screen row after wrapping, ready for rendering.
+
+    When a line overflows the terminal width, it splits into
+    multiple rows with a ``\\`` continuation marker::
+
+        >>> x = "a very long li\\   ← suffix="\\", suffix_width=1
+        ne that wraps"              ← prompt_text="" (continuation)
+    """
     prompt_text: str = ""
     prompt_width: int = 0
     fragments: tuple[ContentFragment, ...] = ()
@@ -125,8 +147,13 @@ def layout_content_lines(
     start_offset: int,
 ) -> LayoutResult:
     """Wrap content lines to fit *width* columns.
-    
-    Line boundaries are marked with ``\\``.
+
+    A short line passes through as one ``WrappedRow``; a long line is
+    split at the column boundary with ``\\`` markers::
+
+        >>> short = 1           ← one WrappedRow
+        >>> x = "a long stri\\  ← two WrappedRows, first has suffix="\\"
+        ng"
     """
     if width <= 0:
         return LayoutResult((), LayoutMap(()), ())

Lib/_pyrepl/reader.py

@@ -157,7 +157,13 @@ def make_default_commands() -> dict[CommandName, CommandClass]:
 
 @dataclass(frozen=True, slots=True)
 class RefreshInvalidation:
-    """Parts of the screen state that have changed and need to be refreshed."""
+    """Which parts of the screen need to be recomputed on the next refresh.
+
+    Typing a character sets ``buffer_from_pos`` (rebuild from that offset).
+    Moving the cursor without editing sets ``cursor_only``.
+    Resizing the terminal sets ``layout`` (reflow all lines).
+    Opening a completion menu sets ``overlay``.
+    """
 
     cursor_only: bool = False
     buffer_from_pos: int | None = None
@@ -310,7 +316,12 @@ class Reader:
     ## cached metadata to speed up screen refreshes
     @dataclass
     class RefreshCache:
-        """Previously computed render/layout data for incremental refresh."""
+        """Previously computed render/layout data for incremental refresh.
+
+        Stores the output of the last ``calc_screen`` so that the next
+        refresh can reuse unchanged rows (e.g. only re-render from the
+        edited line onward instead of the whole screen).
+        """
 
         render_lines: list[RenderLine] = field(default_factory=list)
         layout_rows: list[LayoutRow] = field(default_factory=list)

Lib/_pyrepl/render.py

@@ -24,6 +24,14 @@ def __getitem__(self, key: str, /) -> str: ...
 
 @dataclass(frozen=True, slots=True)
 class RenderCell:
+    """One terminal cell: a character, its column width, and SGR style.
+
+    A screen row like ``>>> def`` is a sequence of cells::
+
+        >  >  >     d  e  f
+                    ╰──┴──╯ styled with keyword SGR escape
+    """
+
     text: str
     width: int
     style: StyleRef = field(default_factory=StyleRef)
@@ -95,6 +103,12 @@ def append_plain_text(segment: str) -> None:
 
 @dataclass(frozen=True, slots=True)
 class RenderLine:
+    """One physical screen row as a tuple of :class:`RenderCell` objects.
+
+    ``text`` is the pre-rendered terminal string (characters + SGR escapes);
+    ``width`` is the total visible column count.
+    """
+
     cells: tuple[RenderCell, ...]
     text: str
     width: int
@@ -140,10 +154,15 @@ def from_rendered_text(cls, text: str) -> Self:
 class ScreenOverlay:
     """An overlay that replaces or inserts lines at a screen position.
 
-    If insert is True, lines are spliced in (shifting content down);
-    if False (default), lines replace existing content at y.
+    If *insert* is True, lines are spliced in (shifting content down);
+    if False (default), lines replace existing content at *y*.
+
+    For example, a tab-completion menu inserted below the input::
 
-    Overlays are used to display tab completion menus and status messages.
+        >>> os.path.j           ← line 0 (base content)
+                     join       ← ScreenOverlay(y=1, insert=True)
+                     junction   ←   (pushes remaining lines down)
+        ...                     ← line 1 (shifted down by 2)
     """
     y: int
     lines: tuple[RenderLine, ...]
@@ -152,6 +171,19 @@ class ScreenOverlay:
 
 @dataclass(frozen=True, slots=True)
 class RenderedScreen:
+    """The complete screen state: content lines, cursor, and overlays.
+
+    ``lines`` holds the base content; ``composed_lines`` is the final
+    result after overlays (completion menus, messages) are applied::
+
+        lines:                     composed_lines:
+        ┌──────────────────┐       ┌──────────────────┐
+        │>>> os.path.j     │       │>>> os.path.j     │
+        │...               │  ──►  │             join  │ ← overlay
+        └──────────────────┘       │...               │
+                                   └──────────────────┘
+    """
+
     lines: tuple[RenderLine, ...]
     cursor: CursorXY
     overlays: tuple[ScreenOverlay, ...] = ()
@@ -220,6 +252,17 @@ def screen_lines(self) -> tuple[str, ...]:
 
 @dataclass(frozen=True, slots=True)
 class LineDiff:
+    """The changed region between an old and new version of one screen row.
+
+    When the user types ``e`` so the row changes from
+    ``>>> nam`` to ``>>> name``::
+
+        >>> n a m       old
+        >>> n a m e     new
+                  ╰─╯
+                  start_cell=7, new_cells=("m","e"), old_cells=("m",)
+    """
+
     start_cell: int
     start_x: int
     old_cells: tuple[RenderCell, ...]

Lib/_pyrepl/unix_console.py

@@ -151,6 +151,21 @@ def poll(self, timeout: float | None = None) -> list[int]:
 
 @dataclass(frozen=True, slots=True)
 class UnixRefreshPlan:
+    """Instructions for updating the terminal after a screen change.
+
+    After the user types ``e`` to complete ``name``::
+
+        Before: >>> def greet(nam|):   
+                                 ▲
+                        LineUpdate here: insert_char "e"
+
+         After: >>> def greet(name|):
+                                  ▲
+
+    Only the changed cells are sent to the terminal; unchanged rows
+    are skipped entirely.
+    """
+
     grow_lines: int
     """Number of blank lines to append at the bottom to accommodate new content."""
     use_tall_mode: bool