How tvhong/incremental-reading works
Project type and purpose
• This is an Anki 2.1+ desktop plug-in (Python) that lets users import long-form content (web pages, RSS/Atom feeds, Pocket articles), read it inside Anki, highlight or extract bits into flashcards, and control their scheduling.
File structure
• Top level: CI configs, linter, Makefile, docs, tests.
• ir/ directory:
– main.py & manifest.json: plug-in entry point & metadata.
– settings.py: configuration API.
– importer/: content-ingestion pipeline (base_importer, html_cleaner, concrete importers: epub, web, rss, pocket, local_file).
– gui.py & view.py: Qt dialog glue + web view integration.
– web/: static HTML/CSS/JS assets (model.css, scroll.js, text.js, table_of_contents.js).
– schedule.py: hooks into Anki’s scheduling engine.
– util.py & text.py: core text-processing utilities.
– lib/: bundled third-party wrappers (feedparser, cgi).
README for architecture clues
• Describes four subsystems: Import, Read/Highlight/Extract, Scheduling, Quick-Keys/UI.
• Mentions integration points with Anki (menus, shortcuts, note editor).
• External dependencies: certain Python libraries, Anki’s Python API, Pocket service.
A. Host Environment (Anki Application)
B. IR Add-on “Shell” (ir/main.py + manifest.json)
C. Settings Manager (ir/settings.py ↔ Anki’s config store)
D. Importer Pipeline
– BaseImporter → Concrete Importers (Web, RSS/Atom, Pocket, EPUB, LocalFile)
– HTMLCleaner & Exception Handling
– Models (intermediate IR data structures)
E. UI Layer
– Native Qt Dialogs & Menus (ir/gui.py)
– Embedded WebView (HTML/CSS/JS under ir/web/)
– View Controller (ir/view.py)
F. Core Logic
– Text Processing (ir/text.py)
– Scheduling Logic (ir/schedule.py)
– Utility functions (ir/util.py)
G. Persistence & External Services
– Anki SQLite DB (notes, cards, scheduling data)
– External Feeds (RSS/Atom), Web pages, Pocket API
– Local files (EPUB, HTML)
H. Third-Party Libraries (feedparser, CGI)
Relationships & data flows
1. User triggers import via menu/shortcut → GUI Layer
2. GUI invokes Importer Pipeline → fetches content from External Services
3. Pipeline → HTMLCleaner → builds IR data models
4. Models passed back to GUI → WebView renders text with embedded JS/CSS
5. User selects/highlights/extracts text → View Controller captures events
6. View passes selections to Core Logic → ir/text.py & schedule.py decide card creation & scheduling
7. Core Logic uses Anki API → writes to Anki SQLite DB
8. Settings Manager persists any option changes
Architectural patterns & principles
• Plugin architecture: clear boundary between Anki host and IR code.
• MVC (roughly) in UI: Qt dialogs (View), view.py (Controller), JS/CSS (View).
• Pipeline pattern in importer: chain of responsibility for cleaning and parsing.
• Layered design: Importer → Core → Persistence, UI decoupled from data-ingestion.
Detail level advice
• Don’t over-complicate: break the add-on into these logical components rather than every single Python file.
• If necessary, expand the importer pipeline further to show base_importer vs. concrete_importers vs. html_cleaner.
• UI interaction flows clearly: user → GUI → core → DB → back to GUI (for scheduling display).
• Call out the embedding of ir/web assets in the WebView (HTML/CSS/JS) as a distinct subcomponent.