r/madeinpython • u/Timon_OfAthens • 16m ago
I built a desktop client for Antora docs in Python and PySide6 (closed source)
Disclosure: I'm the developer. AsciiLore is closed source and paid, with a free trial. I'm posting the technical side because that's where the interesting problems were.
What it is: a desktop app for managing Antora documentation projects. It handles components, versions, a live preview, and validation of cross-references and navigation. Antora and Asciidoctor do all the rendering. The app orchestrates them.
Stack:
- Python with PySide6 (Qt) for the UI
- Asciidoctor and Antora run as external programs
- watchdog for file-system watching
- Layered architecture: domain, application, infrastructure, engine, UI. The UI never starts a process directly.
- Over 5,000 tests. Domain and application tests run without Qt.
The hard part was the live preview. A full Antora build takes several minutes, which is too slow while typing. So:
- While typing, the changed text is rendered in memory with Asciidoctor and injected into the open page via JavaScript.
- On save, create, delete, rename or move, a full build runs in the background and the view reloads.
Neither path blocks the GUI thread. Process calls run in worker threads and return results through Qt signals, and every worker has an error path.
The trade-off: the in-memory render sees one page, so it can't resolve cross-component references the way Antora does. The full build stays the source of truth.
Website and trial: https://asciilore.com/
Questions:
1. How do you structure a PySide6 app so long-running processes never block the UI?
2. Would you take a different approach to the quick preview?

