Головний, як то кажуть, selling point, цієї розмітки у тому що невідрендерений документ, себто у сирому вигляді, має добре парситись оком. Саме тому у ньому заголовки зроблені через підкреслення, тайтл лінки можні відділяти від самої лінки і тд.
Чи то через сам Sphinx, чи то через ергономічність reST, але я прям кайфую коли пишу документацію у цьому форматі, чи то через процес чи через результат. І ось коли писав чергову сторінку і пішов подивитись у Cheat Sheet, зрозумів що хотілось би якоїсь інтерактивної доки для reST, інтерактивної по типу https://pythontutor.com/, або https://mypy-play.net/. Щоб можна було потикати приклади прям у браузері і одразу бачити результат. Але нажаль окрім офф доки нічого більш не знайшов. Та коли це нас стримувало - тож я зафігачив свій туторіал, який працює без бекенда - повністю у браузері, ще й "на решту" зробив плейграунд, із можливістю шерінгу (вийшло щось типу pastebin).
Працювати без бекенду воно може завдяки PyScript - це штука котра через pyodide вміє ранити пайтон у браузері і надає апі для маніпулювання DOM-деревом. Трошки заморочившись можна навіть обійтись без CDN і зробити цю штуку офлайновою (у моєму випадку - не залежити від CDN а роздавати усе що треба для туторіала із свого сервера). Для цього щоправда треба трошки поприсідати, бо всі файли треба витягувати вручну із встановлених npm пакетів, але завдяки докеру це можна зробити досить просто:
docker run --rm -it -v $(pwd):/code -w /code node bash. Тож щоб запускати пайтон скрипти у браузері треба підключити у html файлі бандл пайскріпта (взагалі CDN, але у моєму випадку файлики які я сам роздаю)
<script type="module" src="/pyscript/core.js"></script>
<link rel="stylesheet" href="/pyscript/core.css">
<script type="py" src="./main.py" config="./pyscript.toml"></script>
pyscript.toml виглядає так:
name = "reStructuredText Tutorial"
description = "RST tutorial app"
# так як я хочу роздавати бандл пайскрипту сам - прописую шлях до нього
interpreter = "/pyodide/pyodide.mjs"
# ці пакети PyScript сам витягне із інтернету при старті, але іх можна роздавати
# і самому, щоб взагалі не залежити від зовнішніх ресурсів
packages = ["docutils", "pygments", "lzma"]
У html можна навішувати івенти через атрибути,
<textarea py-input="_render_rst_from_input_debounced"></textarea>, де _render_rst_from_input_debounced це назва функції у main.pyСпочатку я зробив кожен урок туторіала окремою сторінкою, на яку мав навігувати браузер сам, але інтерпретатор стартує не миттєво і ця затримка при перемиканні між вправами дуже відчувається.
Тож прийшлось зробити SPA на мінімалках - PyScript разом із Pyodide завантажується один раз, а навігація відбувається вже самою апкою через підміну частин сторінки і відсдідковування івента "popstate".
Із кнопкою "Share" у плейграунді вийшло прикольно - можна ділитись документом, але сам документ мені ніде зберігати не потрібно - текст написаний у полі вводу стискається, пакується у base64 і вставляється у URL, тож посилання збергіє у собі весь текст і навіть якщо цей сервіс раптом буде недоступний - маючи посилання можна із нього дістати текст вручну. Приклад посилання:
https://rst-tutorial.yakimka.me/playground?paste=_Td6WFoAAATm1rRGAgAhARYAAAB0L-Wj4ABNAD5dAB7r_UTECOiaAZNIfAWoaP1gjlgAhbSC1dTSjED1rIQXc6T3aTSyiu8C_wll5dYjrwFJZQEcq5rmMFbwrvwAAAAA5PjAT436nmgAAVpOYmy28R-2830BAAAAAARZWg%3D%3D
Прикольна технологія, звісно для "заміни js у браузері" воно так собі підходить, а от робити якісь штуки яким треба пайтонівська ліба, аналогів якої немає у npm - саме те (цікаво, чи можна запустити веб сервер у браузері? 😁)
Лінки:
- https://rst-tutorial.yakimka.me/
- https://rst-tutorial.yakimka.me/playground
- https://www.sphinx-doc.org/en/master/
- https://docutils.sourceforge.io/docs/index.html
- https://pyscript.net/
- https://docs.pyscript.net/2025.3.1/user-guide/offline/