RunMe – nejkrásnější spouštěč programů

Vítejte! Runme se snaží poskytnout skvělý zážitek hned po vybalení. Pokračujte prosím a zjistěte, jak co nejlépe využít naše dokumenty prostřednictvím Runme. Proč vlastně nepoužít Runme k tomu, abyste se o Runme dozvěděli?

Co je Runme? 

Runme vám umožní bezproblémově přeměnit vaše stávající dokumenty Markdown, jako je README.md, na spustitelné notebooky.

⏯ Runme umožňuje, aby se statické dokumenty staly interaktivními pro jejich čtenáře a výrazně zlepšily jejich výuku.

Jako uživatel VS Code stačí kliknout sem využijte Runme k procházení tohoto průvodce Začínáme.

Instalace

Otevřete a prohledejte runme z panelu rozšíření uvnitř kódu VS nebo kliknutím nainstalujte z Marketplace:

• Oficiální tržiště VS Code: https://marketplace.visualstudio.com/items?itemName=stateful.runme
• Otevřete registr VSX: https://open-vsx.org/extension/stateful/runme

Proč Runme? 

Zatímco markdown dokumenty jsou v softwaru všudypřítomné a psané slovo je základem dokumentace, bit-rot a „broken docs“ jsou až příliš běžné. Nízká vazba mezi statickým textem dokumentace a kódem dokumentovaného systému vystavuje naše dokumenty rozbití. Runme je tu, aby tento základní problém vyřešil. Cílem Runme je vytvořit ze stávajících dokumentů markdown obojí spustitelný a následně testovatelné. Hodně stejným způsobem, jak se jednotkové testy vztahují k vašemu kódu.

Skočit přímo dovnitř

Stačí otevřít tuto příručku jako notebook uvnitř VS Code a zažít Runme z první ruky.

Uvnitř kódu VS

export MY_NAME=Enter your name $ echo "Hi $MY_NAME, just let Runme execute your docs for you." 

Ve vašem terminálu

Případně můžete ve svém terminálu použít Runme’s CLI. V systému MacOS:

$ brew install stateful/tap/runme $ runme --filename getting-started.md 

Podívejte se na stránku vydání Runme a stáhněte si CLI pro všechny ostatní platformy.

Co potřebujete vědět

Runme změní libovolné soubory markdown na spustitelné notebooky. Pokud vaše markdown obsahuje bloky s oploceným kódem s příkazy kompatibilními se shellem, Runme je váš přítel. Nejčastěji je najdete v README.md, DEV.md, BUILD.md atd., ale záleží na vašich redakčních preferencích.

Zadejte jazyk v blocích

Runme, stejně jako většina prohlížečů Markdown, bude fungovat nejlépe, aniž by bylo jasné, jaký jazyk je obsažen uvnitř chráněných bloků kódu. Je-li to možné, vždy specifikujte jazyk podle normy a vyobrazení níže.

```sh $ echo "language identifier in fenced code block" ``` 

Runme ihned po vybalení využije model Guesslang ML/AI se zaujatostí vůči Shell k detekci jazyků pro neidentifikované bloky kódu. I když to v mnoha případech funguje dobře, přesnost není ani zdaleka 100 %.

Nakonfigurujte spouštění buňky

Ne všechny příkazy jsou stejné a očekávání způsobu provádění se liší. Nejběžnější případy jsou:

1. Sledování souborů pro kompilátory a svazky by měly běžet jako úlohy na pozadí
2. Interaktivní vs neinteraktivní provedení
3. Výstup zaměřený na člověka: JSON, text, obrázky atd
4. Viditelnost terminálu, když nedochází k žádným chybám

Stačí kliknout na „Konfigurovat“ na příslušné buňce a provést úpravy chování při provádění buňky.

Jak zvládnout dlouhotrvající procesy ( pozadí )​

Chcete-li povolit nastavení na pozadí, pokud bude provádění poznámkového bloku pokračovat po neomezenou dobu na jeden příkaz.

Je velmi běžné používat na pozadí během vývoje kompilátory/svazky umožňující sledování souborů (npm start dev, watchexec. atd.). U každé buňky obsahující instanci těchto příkazů nezapomeňte zaškrtnout nastavení buňky „pozadí“. Zabraňuje spuštění trvale blokovat UX notebooku. Po zaškrtnutí si všimněte, že se ve stavovém řádku buňky zobrazí štítek „Úloha na pozadí“.

Interaktivní vs neinteraktivní provádění ( interaktivní )​

Pokud příkazy buňky nevyžadují žádný vstup ze čtečky, může být vhodné zahrnout výstup buňky do notebooku. To je užitečné, pokud by výsledný výstup mohl být užitečný jako vstup v následné buňce.

Vezměte prosím na vědomí, že tým Runme aktuálně pracuje na vytvoření výstupu ve výchozím chování notebooku i terminálu.

Výstup zaměřený na člověka: JSON, text, obrázky atd. ( mimeType ).

Ne všechny výstupy buňky jsou prostý text. Pomocí specifikátoru mimeType je možné určit typ očekávaného výstupu. Notebooky mají různé renderery, které je zobrazí přátelsky k lidem.

Mezi jinými je zde několik oblíbených možností: image/svg+xml , text/x-json , text/x-javascript , text/x-html , text/x-rust atd.

Viditelnost terminálu, když nedojde k žádným chybám ( closeTerminalOnSuccess )​

Prováděcí terminál buňky je automaticky skryt, pokud selže. Toto výchozí chování lze přepsat, pokud je ponechání terminálu otevřeného v zájmu čtečky notebooku Runme. Stačí odlepit closeTerminalOnSuccess ( false ).

Klíčové vlastnosti

• Spouštějte příkazové bloky pomocí jednoduchého ️⏯ tlačítka přehrávání namísto kopírování a vkládání do vašeho terminálu
• Využijte zástupný symbol a výzvy, aby čtenáři interaktivně vyplnili ENV VAR
• Jemně dolaďte spustitelné buňky poznámkového bloku vašeho dokumentu, abyste ostatním zjednodušili práci se spouštěním
• Spusťte sledovače pro kompilaci/svazování jako úlohy na pozadí
• Zachyťte neinteraktivní výstup přímo do výstupu příslušné buňky notebooku
• Kontrolujte, zda má terminál buňky zůstat otevřený po úspěšném provedení
• Použijte identifikátory jazyka v blocích chráněného kódu, abyste se zbavili detekce jazyka a zvýšili spolehlivost
• Nastavte typ MIME výstupu buňky tak, aby vykresloval obrázky, JSON nebo jakýkoli jiný formát způsobem kompatibilním s lidmi