PyRST Architecture¶

This document describes the system architecture, component breakdown, and technical design decisions for PyRST.

Overview ¶

PyRST is a client-side web application that runs Python code in the browser using WebAssembly (via Pyodide). The application processes reStructuredText markup and converts it to HTML without any server-side processing.

High-Level Architecture ¶

┌─────────────────────────────────────────────────────────────┐
│                        Browser                              │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                   User Interface                       │  │
│  │  ┌─────────────┐      ┌──────────────┐               │  │
│  │  │   Editor    │      │   Preview    │               │  │
│  │  │   Panel     │◄────►│    Panel     │               │  │
│  │  └─────────────┘      └──────────────┘               │  │
│  │  ┌──────────────────────────────────────┐            │  │
│  │  │         Toolbar & Controls            │            │  │
│  │  └──────────────────────────────────────┘            │  │
│  │  ┌──────────────────────────────────────┐            │  │
│  │  │         Error Panel                   │            │  │
│  │  └──────────────────────────────────────┘            │  │
│  └───────────────────────────────────────────────────────┘  │
│                           │                                  │
│  ┌────────────────────────▼──────────────────────────────┐  │
│  │              JavaScript Layer                         │  │
│  │  ┌──────────┐  ┌──────────┐  ┌────────────────────┐  │  │
│  │  │  app.js  │  │app_export│  │error-highlighting.js│ │  │
│  │  └──────────┘  └──────────┘  └────────────────────┘  │  │
│  └────────────────────────────────────────────────────────┘  │
│                           │                                  │
│  ┌────────────────────────▼──────────────────────────────┐  │
│  │            Pyodide (Python in WASM)                   │  │
│  │  ┌──────────────────────────────────────────────────┐ │  │
│  │  │               main.py                             │ │  │
│  │  │         (RST Processing Logic)                    │ │  │
│  │  └──────────────────────────────────────────────────┘ │  │
│  │  ┌──────────────────────────────────────────────────┐ │  │
│  │  │          docutils Package                         │ │  │
│  │  │      (RST Parser & HTML Generator)                │ │  │
│  │  └──────────────────────────────────────────────────┘ │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │              Browser Storage (localStorage)            │  │
│  │                (Panel sizes, preferences)              │  │
│  └────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

System Architecture ¶

Frontend Layer (HTML/CSS/JS)¶

The frontend is built with vanilla JavaScript and Tailwind CSS, providing:

HTML Structure (index.html): Semantic layout with editor, preview, toolbar, and error panels
CSS Styling: Three CSS modules for different concerns:
- editor.css: Editor-specific styles, toolbar, error panel
- preview.css: RST HTML output styling (headings, tables, code blocks, admonitions)
- resizable.css: Drag-to-resize divider styling
JavaScript Modules: Three main JS files:
- app.js: Core initialization, toolbar, resizing, RST conversion
- app_export.js: Export functionality (copy, download as RST/HTML/PDF)
- error-highlighting.js: Error parsing, panel management, line highlighting

Python Layer (Pyodide/docutils)¶

The Python layer runs in WebAssembly via Pyodide:

main.py: Contains convert_rst() function that uses docutils to parse RST and generate HTML
docutils: Installed via micropip at runtime, provides the RST parser
Pyodide Bridge: JavaScript-Python interop using pyodide.runPythonAsync() and pyodide.globals

Storage Layer ¶

LocalStorage: Persists panel sizes across sessions
No Server Storage: All document data stays in the browser

Component Breakdown ¶

1. Editor Panel ¶

Purpose: Text input area for writing RST

Components:

Textarea element with monospace font
Highlight overlay for error/warning line highlighting
Auto-sync with preview via input events

Files:

index.html (lines 77-158)
app.js (toolbar functions)
error-highlighting.js (line highlighting)

2. Preview Panel ¶

Purpose: Rendered HTML output of RST

Components:

Preview div that displays docutils-generated HTML
Export buttons (copy/download RST, HTML, PDF)
Styled with comprehensive CSS for all RST elements

Files:

index.html (lines 188-227)
preview.css (all RST element styling)
app_export.js (export functionality)

4. Error Panel ¶

Purpose: Display RST syntax errors and warnings

Components:

Error list with clickable items
Error/warning counts
Collapsible panel
Line jump functionality

Files:

index.html (lines 160-181)
error-highlighting.js

Key Functions:

parseSystemMessages(html): Extracts errors from docutils system messages
updateErrorPanel(errors): Updates UI with error list
highlightEditorLines(errors): Highlights error lines in editor
jumpToLine(lineNumber): Scrolls editor to specific line

5. Resizable Panels ¶

Purpose: Adjustable split between editor and preview

Components:

Draggable divider
Panel flex sizing
LocalStorage persistence

Files:

app.js (lines 12-111)
resizable.css

Key Functions:

initResizablePanels(): Sets up drag handlers
loadPanelSizes(): Restores saved sizes
savePanelSizes(): Persists to localStorage

6. Pyodide Integration ¶

Purpose: Run Python/docutils in browser

Components:

Pyodide loader
micropip for package installation
Python-JavaScript bridge

Files:

app.js (lines 351-467)
main.py

Key Functions:

initPyodide(): Loads Pyodide, installs docutils, initializes editor
convertRST(rstText): Calls Python to convert RST to HTML
convert_rst(rst_text): Python function using docutils

Data Flow ¶

Initialization Flow ¶

1. Page Load
   ↓
2. DOMContentLoaded Event
   ↓
3. initPyodide()
   ├─ Load Pyodide from CDN
   ├─ Install micropip
   ├─ Install docutils
   ├─ Load main.py
   ├─ Load sample.rst
   ├─ Initialize editor with sample
   ├─ Set up event listeners
   └─ Initialize toolbar, export, resizing
   ↓
4. Ready to Use

Editing Flow ¶

1. User types in editor
   ↓
2. 'input' event fired
   ↓
3. Debounced convertRST() called (300ms delay)
   ↓
4. JavaScript → Python bridge
   ├─ Set rst_input in Python globals
   ├─ Run publish_string() via docutils
   └─ Return HTML string
   ↓
5. Parse HTML for system messages
   ↓
6. Update preview panel with HTML
   ↓
7. Update error panel with errors
   ↓
8. Highlight error lines in editor

Export Flow ¶

1. User clicks export button
   ↓
2. Export function called
   ├─ Copy RST → clipboard.writeText(editor.value)
   ├─ Copy HTML → clipboard.writeText(preview.innerHTML)
   ├─ Download RST → Blob → download link
   ├─ Download HTML → Full HTML with CSS → download
   └─ PDF → window.print()
   ↓
3. Show toast notification

File Structure ¶

pyrst/
├── src/pyrst/
│   ├── index.html              # Main HTML structure
│   ├── app.js                  # Core app logic, toolbar, resizing
│   ├── app_export.js           # Export functions, toast notifications
│   ├── error-highlighting.js   # Error parsing and highlighting
│   ├── main.py                 # Python RST conversion logic
│   ├── sample.rst              # Sample RST content
│   ├── __init__.py             # Empty Python package marker
│   └── css/
│       ├── editor.css          # Editor, toolbar, error panel styles
│       ├── preview.css         # RST HTML output styles
│       └── resizable.css       # Resizable divider styles
├── docs/                       # Documentation
├── tests/                      # Test files
├── pyproject.toml              # Python project metadata
├── Makefile                    # Build commands
├── README.md                   # Project README
└── uv.lock                     # Dependency lock file