AHA: Wide Table Formatting for Narrow RST Pages#

Created: 2026-03-26

Problem: sphinx-book-theme pages have a fixed content width (~720 px). Tables with 5+ columns of text content overflow, get horizontal scrollbars, or squeeze columns until text is unreadable. This is a recurring problem for comparison tables, audit tables, and any tabular data with long string values.

Solution: A three-tier strategy (A → B → C), tried in order. The prompt below can be given to Claude to reformat any specific table.

The Prompt#

You are reformatting a wide RST table that does not render well on
sphinx-book-theme pages (~720 px content width). Apply the following
three-tier strategy IN ORDER. Move to the next tier only when the
current one genuinely cannot produce a readable result.

─── TIER A: Rebalance the table within RST ───

1. MEASURE each column's actual content.
   - For each column, find the longest cell value (in characters).
   - Identify columns that are mostly short (IDs, counts, flags)
     vs. columns that carry long text (descriptions, titles).

2. SET :widths: proportionally to real content, not equally.
   - Give narrow columns (counts, flags) just enough width.
   - Give text-heavy columns the remaining space.
   - Never let a text column go below ~20 chars rendered width.

3. INSERT line breaks within cells to balance fill.
   - In list-table cells, a newline followed by proper indentation
     creates a line break inside the cell.
   - Break long values at natural word boundaries so that every
     column is roughly equally "full" vertically.
   - Column HEADERS must never be truncated or wrapped mid-word.

4. CHECK by estimating rendered widths.
   - The total available width is ~100 characters of monospace.
   - Each column's share = (its :widths: value / sum of widths) × 100.
   - Confirm that no column's longest content line exceeds its share.
   - If any column's minimum content (a single word, a number)
     exceeds its share, Tier A cannot work — proceed to Tier B.

CRITICAL: Never "squeeze" a column so much that content is cut off
or requires horizontal scrolling. If the table cannot fit without
cutting content, do not force it — move to Tier B.


─── TIER B: Standalone HTML page ───

If Tier A fails (too many columns, or columns with irreducibly long
content), create a standalone HTML page:

1. CREATE a file named <original-name>-wide.html in the same
   directory as the RST source (or in _static/ if preferred).
   - Copy the styles from the current sphinx-book-theme so the
     standalone page looks consistent (fonts, colors, link styles).
   - The HTML page lives OUTSIDE the RST toctree, so it gets the
     full browser viewport width — no sidebar, no nav chrome.
   - Use a responsive <table> with appropriate CSS:
     * thead sticky on scroll
     * alternating row backgrounds for readability
     * column widths via <colgroup> matched to content
     * horizontal scroll as last resort (with visible scrollbar)

2. IN THE ORIGINAL RST PAGE, replace the too-wide table with:
   - A 1–2 sentence description of what the full table contains.
   - The column names and row count so readers know what to expect.
   - A small PREVIEW table (3–5 representative rows, most
     important columns only) that fits within Tier A constraints.
   - A prominent link: "View full table (N columns × M rows)"
     pointing to the standalone HTML file.

3. ENSURE the HTML file is included in the Sphinx build.
   - Add it to html_extra_path in conf.py, OR
   - Place it in _static/ and link with a relative path, OR
   - Use a raw:: html directive with an iframe (least preferred).


─── TIER C: Structured list fallback ───

If even a standalone HTML table is impractical (e.g., the data is
inherently not tabular, or there are hundreds of rows and columns
making even a wide table hard to scan), convert to a structured list:

1. For each row of the original table, create a definition-list
   entry or a rubric + field-list block:

   .. rubric:: Row identifier (e.g., page name)

   :Column A: value
   :Column B: value
   :Column C: value

2. Group entries by a meaningful category if possible (section,
   type, status) with section headings between groups.

3. Add a summary at the top: total entries, breakdown by category,
   and any notable outliers.

This format is always readable on any width, but loses the
at-a-glance comparison that tables provide. Use it only as a
last resort.


─── GENERAL RULES (all tiers) ───

- NEVER delete or omit data. Every cell from the original table
  must appear in the output, regardless of which tier is used.
- NEVER truncate content with "..." unless the original had "...".
- Preserve all RST cross-references (:doc:, :ref:, links).
- Keep the page's .. meta:: block and any SOCIAL-CARD blocks
  unchanged.
- If the table has both an OO and PP version of the same field,
  consider whether a two-row-per-entry layout (OO row, PP row)
  would be narrower than a side-by-side layout.

Usage#

To apply this prompt to a specific page, tell Claude:

Read source/matheology/socialcards/comparison/beginner.rst
and the AHA at source/matheology/compiler/aha/wide-table-formatting.rst.
Apply the wide-table-formatting prompt to fix the table layout.

Or for batch processing:

Apply the wide-table-formatting AHA prompt to all list-tables in
source/matheology/socialcards/comparison/.