Show README logs and use relative SVG links

Author: wolph

README.rst

@@ -14,7 +14,7 @@ unknown-length progress, and pipe-friendly CLI usage.
     :alt: coverage status
     :target: https://coveralls.io/r/WoLpH/python-progressbar?branch=master
 
-.. image:: https://raw.githubusercontent.com/WoLpH/python-progressbar/develop/docs/_static/progressbar-hero.svg
+.. image:: docs/_static/progressbar-hero.svg
     :alt: progressbar2 showing clean progress output with logs
 
 Install
@@ -73,19 +73,19 @@ Prints and logs while the bar is active
 Multiple bars
 ==============================================================================
 
-.. image:: https://raw.githubusercontent.com/WoLpH/python-progressbar/develop/docs/_static/progressbar-multibar.svg
+.. image:: docs/_static/progressbar-multibar.svg
     :alt: multiple progress bars updating together
 
 Unknown length and animated bars
 ==============================================================================
 
-.. image:: https://raw.githubusercontent.com/WoLpH/python-progressbar/develop/docs/_static/progressbar-unknown-length.svg
+.. image:: docs/_static/progressbar-unknown-length.svg
     :alt: unknown length progress with an animated marker
 
 Tqdm-style ergonomic options
 ==============================================================================
 
-.. image:: https://raw.githubusercontent.com/WoLpH/python-progressbar/develop/docs/_static/progressbar-ergonomics.svg
+.. image:: docs/_static/progressbar-ergonomics.svg
     :alt: progressbar2 tqdm-style desc total unit scale and postfix output
 
 CLI usage

docs/_static/progressbar-hero.svg

@@ -28,6 +28,7 @@ class Demo:
     name: str
     title: str
     snippet: str
+    log_lines: int = 0
 
 
 DEMOS = [
@@ -54,6 +55,7 @@ class Demo:
         bar.update(step + 1, force=True)
         time.sleep(0.005)
 """,
+        log_lines=2,
     ),
     Demo(
         'multibar',
@@ -174,7 +176,10 @@ def capture_demo(demo: Demo) -> list[list[str]]:
     except subprocess.TimeoutExpired as error:
         raise SystemExit(f'timed out capturing demo: {demo.name}') from error
 
-    return frames_from_output(result.stdout)
+    frames = parse_frames(result.stdout)
+    if demo.log_lines:
+        frames = keep_recent_logs_with_progress(frames, demo.log_lines)
+    return limit_animation_frames(frames) or [['No output captured']]
 
 
 def normalize_terminal_line(line: str) -> str:
@@ -185,6 +190,12 @@ def normalize_terminal_line(line: str) -> str:
 
 
 def frames_from_output(output: str) -> list[list[str]]:
+    return limit_animation_frames(parse_frames(output)) or [
+        ['No output captured']
+    ]
+
+
+def parse_frames(output: str) -> list[list[str]]:
     frames: list[list[str]] = []
     output = output.replace('\x1b[2K', '')
     if '\f' in output:
@@ -196,14 +207,35 @@ def frames_from_output(output: str) -> list[list[str]]:
             ]
             if lines:
                 frames.append(lines)
-        return limit_animation_frames(frames) or [['No output captured']]
+        return frames
 
     for raw_frame in output.splitlines():
         for part in raw_frame.split('\r'):
             line = part.strip()
             if line:
                 frames.append([normalize_terminal_line(line)])
-    return limit_animation_frames(frames) or [['No output captured']]
+    return frames
+
+
+def keep_recent_logs_with_progress(
+    frames: list[list[str]],
+    log_lines: int,
+) -> list[list[str]]:
+    logs: list[str] = []
+    output: list[list[str]] = []
+
+    for frame in frames:
+        log_frame = [line for line in frame if line.startswith('log:')]
+        progress_frame = [
+            line for line in frame if not line.startswith('log:')
+        ]
+        if log_frame:
+            logs.extend(log_frame)
+            logs = logs[-log_lines:]
+        if progress_frame:
+            output.append(logs + progress_frame)
+
+    return output
 
 
 def limit_animation_frames(frames: list[list[str]]) -> list[list[str]]:

scripts/render_readme_demos.py

@@ -87,6 +87,19 @@ def test_demo_definitions_are_ordered_and_exercise_key_features() -> None:
     assert 'postfix=' in snippets['ergonomics']
 
 
+def test_readme_uses_branch_relative_demo_assets() -> None:
+    readme = (demos.ROOT / 'README.rst').read_text(encoding='utf-8')
+
+    assert (
+        'raw.githubusercontent.com/WoLpH/python-progressbar/develop'
+        not in readme
+    )
+    assert '.. image:: docs/_static/progressbar-hero.svg' in readme
+    assert '.. image:: docs/_static/progressbar-multibar.svg' in readme
+    assert '.. image:: docs/_static/progressbar-unknown-length.svg' in readme
+    assert '.. image:: docs/_static/progressbar-ergonomics.svg' in readme
+
+
 def test_render_svg_first_frame_is_visible_without_animation(
     tmp_path: Path,
 ) -> None:
@@ -205,6 +218,18 @@ def test_readme_demos_show_wide_determinate_progress_bars() -> None:
         assert max(_bar_widths(frames_by_name[name])) >= 32
 
 
+def test_hero_demo_keeps_recent_logs_visible_above_progress() -> None:
+    demo = next(demo for demo in demos.DEMOS if demo.name == 'hero')
+    frames = demos.capture_demo(demo)
+
+    assert max(len(frame) for frame in frames) >= 3
+    assert any(
+        any(line.startswith('log: completed step 8') for line in frame)
+        and any('Build:' in line for line in frame)
+        for frame in frames
+    )
+
+
 def test_capture_frames_normalizes_variable_timing_text() -> None:
     frames = demos.frames_from_output(
         'Build:  50% Elapsed Time: 0:01:23 ETA:   9:08:07\n'