Přidání dokumentace

Můžete mít nejlepší software na světě, ale pokud nikdo neví, jak ho používat, k čemu je vám? Dokumentace se vždy dá vylepšit – a my potřebujeme vaši pomoc!

Formuláře dokumentace

Dokumentace BeeWare's je napsána pomocí MkDocs a Markdown. Naším cílem je dodržovat rámec Diataxis pro strukturování dokumentace.

Rámec Diataxis popisuje čtyři „formy“ dokumentace:

• Tutoriál – řízená výuka s konkrétním cílem projektu.
• Návod – pokyny, které vedou čtenáře k dosažení konkrétního cíle nebo výsledku.
• Průvodce tématem – Diskuse o jedné myšlence, vysvětlená takovým způsobem, aby byly jasné základní pojmy.
• Reference – Technické popisy konkrétních API nebo jiných rozhraní.

Před zahájením jakéhokoli příspěvku do dokumentace je důležité určit, který formulář je nejvhodnější. Mnoho návrhů dokumentace bude zpočátku popsáno jako požadavek na „tutoriál k tématu X“, ale ve většině případů je ve skutečnosti zapotřebí návod, průvodce tématem nebo vylepšené referenční informace.

Jako příklad si vezměme úkol napsat dokumentaci o pečení sušenek.

Návod

Tutoriál je úvod, zejména zaměřený na začátečníky, jehož cílem by mělo být dovést čtenáře od čistého výchozího bodu k hotovému produktu. Vyžaduje velmi konkrétní pokyny a podrobná vysvětlení, která uvádějí jednotlivé kroky tutoriálu do kontextu. Nesmíte předpokládat žádné znalosti čtenáře o vysvětlovaném nástroji, i když je rozumné předpokládat základní znalost jazyka Python.

Návod by měl obsahovat pravidelné kontrolní body, kde si čtenář může ověřit, zda se mu podařilo provést popsané kroky. U každého kontrolního bodu by měla být jasně stanovena kritéria úspěchu. Známé případy selhání by měly být jasně popsány, včetně vysvětlení všech pravděpodobných chyb nebo problémů, se kterými se čtenář může setkat. Je třeba poukázat na věci, které se změní v důsledku kroků, které čtenář provedl, i když se to může zdát zřejmé. Opakování je vítáno, zejména pokud se snažíte zavést osvědčené postupy nebo běžné procesy. Vysvětlení vnitřních procesů by se mělo vyhnout, stejně jako alternativní cesty k dosažení stejného výsledku.

Návod na pečení sušenek je víc než jen recept. Pokyny v návodu by měly být srozumitelné i pro někoho, kdo nikdy předtím nepekl (například pro dítě), a měly by zahrnovat věci, které zkušený pekař považuje za samozřejmé, jako je například jak smíchat cukr a máslo, jak předehřát troubu nebo jak dlouho nechat sušenky vychladnout před konzumací. Cílem návodu není vyrobit sušenku, ale zprostředkovat základy pečení. Výsledná sušenka je chutná pochoutka, která někoho přesvědčí, aby se do návodu vůbec pustil.

Návod k použití

Návod by se měl zaměřit na konkrétní případ použití v reálném světě a praktické výsledky, spíše než na teoretická vysvětlení. Na rozdíl od tutoriálu můžete předpokládat určitou znalost existujících nástrojů. Čtenář by měl být schopen postupovat podle návodu od začátku do konce a dosáhnout cíle, ale k tomu může potřebovat určité znalosti. Návod by měl obsahovat soubor konkrétních pokynů nebo logických kroků, které je třeba dodržet, aby bylo možné dosáhnout cíle návodu.

Recept v kuchařce je dobrým příkladem návodu. Existuje mnoho receptů na čokoládové sušenky a všechny mají společné rysy, ale každý konkrétní recept by měl být možné dodržet od začátku do konce a výsledek by měl být vždy stejný. Dobrý recept na čokoládové sušenky se nebude zabývat relativními výhodami různých druhů cukru nebo mouky ani nebude obsahovat podrobné pokyny k základní technice nebo postupu; bude obsahovat pouze ingredience a pokyny k upečení sušenek, přičemž se předpokládá, že čtenář má základní znalosti o pečení.

Průvodce tématy

Tematický průvodce popisuje jedno téma nebo myšlenku. Může obsahovat příklady kódu nebo pokyny, ale mnohem více se zaměřuje na poskytnutí obecného přehledu o celkovém konceptu. Může obsahovat názory a alternativní pohledy, ale je třeba zachovat zaměření na konkrétní téma průvodce.

Průvodce tématem pečení sušenek by se mohl zabývat historií sušenek jako pečeného výrobku, zkoumat, jak průmyslové procesy vedou k odlišným typům sušenek ve srovnání s domácími sušenkami, nebo navrhovat způsoby, jak sušenky začlenit do vyvážené stravy. Samotný dokument by nebyl příliš užitečný, pokud byste chtěli upéct sušenky, ale mohl by poskytnout základní informace, které by umožnily někomu, kdo se vyzná v pečení, úspěšně přizpůsobit stávající recept na sušenky.

Odkaz

Referenční dokumentace je zaměřena na informace a popisuje specifika fungování knihovny nástrojů. Často ji lze vygenerovat přímo z kódu, ale kvalitní dokumentace API může vyžadovat další vysvětlení a kontext. Ačkoli někdy může obsahovat příklady použití, podrobná vysvětlení by se měla vyhnout.

Referenční příručka o pečení může popisovat druhy cukru, které lze použít, a podrobně uvádět jejich vlastnosti při použití v pečení. Popisuje doslovné skutečnosti o cukru, ale širší diskuse o výběru mezi druhy cukru by měla být předmětem návodu nebo tematické příručky. Výživové informace uvedené na většině balených potravin lze považovat za referenční dokumentaci.

Styl dokumentace

Dokumentace BeeWare's se řídí pokyny uvedenými v průvodci stylem dokumentace. Tento průvodce obsahuje základní styl a formátování a postup pro kontrolu pravopisu. Zabývá se také různými detaily syntaxe Markdown, jako je syntaxe odkazů, tipy pro práci s bloky kódu a práce s obrázky.

Přispívání dokumentací

Návrh nové dokumentace

Máte tedy nápad, jak vylepšit BeeWare – jak tento nápad předložit k posouzení?

Proveďte průzkum

Prvním krokem je prohledat systém pro sledování problémů BeeWare a najít existující problémy s funkcemi (problémy označené „vylepšení”), problémy s dokumentací (problémy označené „dokumentace”), nebo diskusní vlákna, abyste zjistili, zda již někdo tento nápad nenavrhl. Pokud ano a máte nové souvislosti nebo nápady, které chcete přidat, zahrňte je do existujícího vlákna. Pokud potřebujete pomoc s výzkumem, můžete se zeptat v kanálu #dev na BeeWare Discord. Možná vám budeme moci ukázat směr existujících vláken, poskytnout souvislosti, o kterých možná nevíte, nebo propojit váš nápad s jiným nápadem, který se na první pohled nemusí zdát související.

Diskutujte o této myšlence

Pokud nenajdete žádné existující odkazy na svůj nápad, založte diskusní vlákno. Uveďte obecný popis účelu a použití svého nápadu. Uveďte také své představy o tom, jak by daná funkce vypadala, pokud by byla implementována, například obecný tvar API, vizuální podoba funkce nebo dokument, který by byl přidán. Pokud je to relevantní, uveďte také veškerý výzkum, který jste provedli ohledně toho, jak by se váš nápad projevil na různých platformách.

Jakmile bude diskusní vlákno otevřeno, tým BeeWare a zbytek komunity na něj zareagují. Jádro týmu se bude snažit poskytnout alespoň první dojem z vašeho nápadu do dvou pracovních dnů. Pokud je nápad obzvláště složitý, může podrobnější analýza trvat až týden. Události jako svátky a konference mohou tyto lhůty mírně prodloužit.

Toto je vaše příležitost zapojit se do diskuse o vašem nápadu. Můžeme vás požádat o další podrobnosti nebo kontext. Do diskuse se mohou zapojit i další členové komunity, kteří mohou přinést jiné pohledy, návrhy nebo protinávrhy. Výsledek této diskuse určí další kroky.

Je důležité si uvědomit, že ne všechny nápady budou přijaty. Důvodem, proč tento proces začíná návrhem, je zabránit tomu, abyste vynaložili veškeré úsilí, jen abyste zjistili, že existuje důvod, proč vaše změna nebude přijata.

To ale neznamená, že to nebyl dobrý nápad! Může existovat technické důvody, proč jej nelze realizovat. Například můžeme nápad zamítnout, pokud:

• Bylo by obtížné nebo nemožné jej spolehlivě implementovat na všech podporovaných platformách; nebo
• Bylo by obtížné jej udržovat nebo by údržba vyžadovala přístup k technologii nebo softwaru, který není široce dostupný; nebo
• Slouží úzké skupině uživatelů, ale ostatním uživatelům způsobuje značné náklady.

Pokud usoudíme, že váš nápad není vhodný, nemusí to nutně znamenat, že byste ho měli vzdát. I když můžeme odmítnout konkrétní nápad, můžeme být mnohem vstřícnější k přidání rozhraní pluginu nebo jiného rozšíření, které by vám umožnilo zachovat stejnou funkci jako externí knihovna. Tímto způsobem můžete mít danou funkci, ale bez konkrétních problémů s údržbou nebo omezeními, která by se stala překážkou pro samotný projekt.

Převést na formální požadavek na funkci

Jakmile se v diskusi dosáhne shody ohledně podoby funkce, můžete v systému pro sledování problémů beeware vytvořit nový požadavek na funkci, který shrne diskusi a bude obsahovat odkaz na diskusi pro kontext.

Nemusíte svůj návrh funkce implementovat sami; můžete otevřít issue s podrobnostmi o tom, co navrhujete. Pouhé zveřejnění issue však neznamená, že bude pro vás implementováno. Budete muset počkat, až se ho ujme někdo jiný, kdo má o stejnou funkci zájem, ať už se jedná o jiného člena komunity nebo členy hlavního týmu; není však zaručeno, že se tak stane. Pokud chcete mít jistotu, že bude funkce implementována, budete ji muset implementovat sami nebo zaplatit někoho, kdo to udělá za vás.

Nastavení vývojového prostředí

Příspěvky do BeeWare vyžadují nastavení vývojového prostředí.

Předpoklady

Budete muset nainstalovat následující předpoklady.

macOSLinuxWindows

BeeWare vyžaduje Python 3.10+. Budete také potřebovat metodu pro správu virtuálních prostředí (například venv).

Verzi nainstalovaného Pythonu můžete ověřit spuštěním:

$ python3 --version

Pokud máte nainstalováno více než jednu verzi Pythonu, možná budete muset nahradit python3 konkrétním číslem verze (např. python3.13)

Doporučujeme se vyhnout nedávno vydané verzi Pythonu (tj. verzím, které mají mikroverzi „.0“ nebo „.1“, jako např. 3.14.0). Důvodem je to, že nástroje potřebné pro podporu Pythonu na macOS často zaostávají a obvykle nejsou k dispozici pro nedávno vydané stabilní verze Pythonu.

BeeWare vyžaduje Python 3.10+. Budete také potřebovat metodu pro správu virtuálních prostředí (například venv).

Verzi nainstalovaného Pythonu můžete ověřit spuštěním:

$ python3 --version

Pokud máte nainstalováno více než jednu verzi Pythonu, možná budete muset nahradit python3 konkrétním číslem verze (např. python3.13)

Doporučujeme se vyhnout nedávno vydané verzi Pythonu (tj. verzím, které mají mikroverzi „.0“ nebo „.1“, jako např. 3.14.0). Důvodem je to, že nástroje potřebné pro podporu Pythonu v systému Linux často zaostávají a obvykle nejsou k dispozici pro nedávno vydané stabilní verze Pythonu.

BeeWare vyžaduje Python 3.10+. Budete také potřebovat metodu pro správu virtuálních prostředí (například venv).

Verzi nainstalovaného Pythonu můžete ověřit spuštěním:

C:\...>py -3 --version

Pokud máte nainstalováno více než jednu verzi Pythonu, možná budete muset nahradit -3 konkrétním číslem verze (např. -python3.13)

Doporučujeme se vyhnout nedávno vydané verzi Pythonu (tj. verzím, které mají mikroverzi „.0“ nebo „.1“, jako např. 3.14.0). Důvodem je to, že nástroje potřebné pro podporu Pythonu ve Windows často zaostávají a obvykle nejsou k dispozici pro nedávno vydané stabilní verze Pythonu.

Nastavte si vývojové prostředí

Doporučeným způsobem nastavení vývojového prostředí pro BeeWare je použití virtuálního prostředí, a následná instalace vývojové verze BeeWare a jejích závislostí.

Klonujte repozitář BeeWare

Dále přejděte na stránku BeeWare na GitHubu, a pokud jste tak ještě neučinili, forkněte repozitář do svého vlastního účtu. Poté klikněte na tlačítko „<> Code“ ve vašem forku. Pokud máte v počítači nainstalovanou desktopovou aplikaci GitHub, můžete vybrat možnost „Open with GitHub Desktop“ (Otevřít v GitHub Desktop); v opačném případě zkopírujte uvedenou adresu HTTPS URL a použijte ji ke klonování repozitáře do svého počítače pomocí příkazového řádku:

macOSLinuxWindows

Rozdělte repozitář BeeWare a poté:

$ git clone https://github.com/<your username>/beeware.git

(nahraďte svým uživatelským jménem na GitHubu)

Rozdělte repozitář BeeWare a poté:

$ git clone https://github.com/<your username>/beeware.git

(nahraďte svým uživatelským jménem na GitHubu)

Rozdělte repozitář BeeWare a poté:

C:\...>git clone https://github.com/<your username>/beeware.git

(nahraďte svým uživatelským jménem na GitHubu)

Vytvořte virtuální prostředí

Chcete-li nastavit virtuální prostředí a upgradovat pip, spusťte:

macOSLinuxWindows

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

Vaše výzva by nyní měla mít před sebou předponu (.venv).

Nainstalovat BeeWare

Nyní, když máte zdrojový kód, můžete provést editovatelnou instalaci BeeWare do svého vývojového prostředí. Spusťte následující příkaz:

macOSLinuxWindows

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

Povolit předběžné potvrzení

BeeWare používá nástroj nazvaný pre-commit, který identifikuje jednoduché problémy a standardizuje formátování kódu. Toho dosahuje instalací git hooku, který automaticky spustí sérii linterů kódu před finalizací jakéhokoli git commitu. Chcete-li povolit pre-commit, spusťte:

macOSLinuxWindows

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

Nyní jste připraveni začít hackovat BeeWare!

Práce z pobočky

Než začnete pracovat na změně, ujistěte se, že jste vytvořili větev. Ve výchozím nastavení se při klonování vidlice repozitáře dostanete do větve main. Jedná se o přímou kopii větve BeeWare .

I když můžete odeslat žádost o stažení z vaší větve main, je lepší, když to nebudete dělat. Pokud odešlete žádost o stažení, která je téměř správná, člen jádrového týmu, který vaši žádost o stažení posuzuje, může provést potřebné změny, místo aby vám poskytl zpětnou vazbu s žádostí o drobnou změnu. Pokud však odešlete žádost o stažení z vaší větve main, recenzenti nebudou moci provádět úpravy.

Práce na hlavní větvi také ztěžuje práci vám po dokončení prvního požadavku na stažení. Pokud chcete pracovat na druhém požadavku na stažení, budete potřebovat „čistou“ kopii hlavní větve upstreamového projektu, na které budete moci založit svůj druhý příspěvek; pokud jste svůj první příspěvek vytvořili z větve main, již nemáte k dispozici tuto čistou verzi.

Místo toho byste měli provádět změny na funkční větvi. Funkční větev má jednoduchý název, který identifikuje změnu, kterou jste provedli. Pokud například opravujete chybu, která způsobuje problémy s kompilací ve Windows 11, můžete vytvořit feature branch fix-win11-build. Pokud se vaše chyba týká konkrétního nahlášeného problému, je také běžné odkazovat na číslo tohoto problému v názvu větve (např. fix-1234).

Chcete-li vytvořit větev funkcí fix-win11-build, spusťte:

macOSLinuxWindows

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build

Vyhněte se rozšiřování rozsahu

K „rozšíření rozsahu“ dochází, když seznam vyřešených problémů nebo implementovaných funkcí v rámci jednoho příspěvku výrazně přesáhne původní záměr na začátku práce. Začnete s jednoduchým problémem, objevíte úzce související problém a rozhodnete se zahrnout i jeho opravu, pak třetí… a než se nadějete, máte pull request, který uzavírá 5 problémů a přidává 3 nové funkce, včetně desítek souborů.

Rozšíření rozsahu se stává každému. Je to pojem, který je zkušeným vývojářům velmi dobře známý; všichni jsme to už několikrát zažili a setkali se se všemi problémy, které s tím souvisejí.

Existují velmi praktické důvody, proč se vyhnout rozšiřování rozsahu. Čím větší je příspěvek, tím obtížnější je s ním pracovat. Je těžší identifikovat okrajové případy nebo potenciální problémy, což znamená, že celková kvalita příspěvku může být snížena. Recenze se také stávají náročnějšími, když recenzent musí řešit více potenciálně nesouvisejících kontextů. Větší příspěvek znamená více recenzních komentářů a jako přispěvatel může být obtížné sledovat více recenzních vláken. Utrpí tím i vaše zkušenost s GitHubem – uživatelské rozhraní GitHubu se bude zpomalovat s rostoucí velikostí PR, což znamená, že procházení souborů prostřednictvím rozhraní GitHubu a pokusy o zanechání recenzních komentářů budou stále obtížnější.

Kdykoli najdete důvod přidat do svého příspěvku něco, co není výslovně součástí původního návrhu nebo hlášení o chybě, měli byste zvážit, zda se nevydáváte směrem k rozšiřování rozsahu. Existují dvě odlišné funkce, které by mohly být implementovány samostatně? Mohla by být funkce implementována se známým omezením nebo chybou a tato chyba opravena v následném požadavku na stažení? Je jedna část opravy chyby nezávislá na druhé? Pokud lze část změny vynechat, aniž by došlo ke změně původního příspěvku, pravděpodobně by tak mělo být učiněno.

Vývoj softwaru je vždy proces postupného zlepšování. Každý jednotlivý příspěvek by měl po sloučení zanechat kódovou základnu v lepším stavu, ale je zcela přijatelné ponechat chyby nebo části funkcí jako úkol pro budoucí vylepšení. To může znamenat rozdělení žádosti o stažení na více částí, které lze zkontrolovat samostatně, nebo zaznamenání problému, aby jej mohl někdo jiný prošetřit a vyřešit.

Omezení rozsahu každého příspěvku pomáhá všem zúčastněným, včetně vás. Vaši recenzenti, a dokonce i vy sami, to oceníte.

Stavební dokumentace

Před provedením jakýchkoli změn v dokumentaci BeeWare je užitečné ověřit, zda můžete sestavit stávající dokumentaci.

Musíte mít nainstalovaný interpret Python 3.13 a musí být dostupný ve vaší cestě (tj. python3.13 musí spustit interpret Python 3.13).

BeeWare používá tox pro vytváření dokumentace. Následující příkazy tox musí být spuštěny ze stejného umístění jako soubor tox.ini, který se nachází v kořenovém adresáři projektu.

Náhled živé dokumentace

Pro podporu rychlé úpravy dokumentace má BeeWare režim „živého náhledu“.

Živý náhled se vytvoří s varováními!

Live serve je k dispozici pro opakované aktualizace dokumentace. Během aktualizace může dojít k problému s označením. Problémy označené jako WARNING způsobí selhání standardní kompilace, ale live serve je nastaven tak, aby v konzoli zobrazoval varování a pokračoval v kompilaci. To vám umožňuje opakovat aktualizace bez nutnosti restartovat živý náhled.

WARNING se liší od ERROR. Pokud zavedete problém, který je považován za ERROR, živý server selže a bude vyžadovat restart. Nezačne znovu fungovat, dokud nebude problém WARNING vyřešen.

Spuštění živého serveru:

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

Tím se vytvoří dokumentace, spustí se webový server pro poskytování dokumentace a bude sledován souborový systém, zda nedošlo k nějakým změnám ve zdrojovém kódu dokumentace.

Po spuštění serveru se v konzoli zobrazí následující výstup:

INFO    -  [11:18:51] Serving on http://127.0.0.1:8000/

Otevřete prohlížeč a přejděte na uvedenou adresu URL. Nyní můžete začít s iterací dokumentace. Pokud bude zjištěna změna, dokumentace bude znovu sestavena a všechny prohlížeče, které zobrazují upravenou stránku, budou automaticky aktualizovány.

docs-live je první krok

Spuštění docs-live pro práci s živým serverem je určeno pro počáteční iterace. Před odesláním žádosti o stažení byste měli vždy spustit lokální sestavení.

Místní sestavení

Jakmile dokončíte iterace, budete muset provést lokální sestavení dokumentace. Tento proces sestavení je navržen tak, aby selhal v případě jakýchkoli problémů se značkami. To vám umožní zachytit vše, co jste mohli na živém serveru přehlédnout.

Generování lokální sestavení

Pro vytvoření lokální sestavení:

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

Výstup této sestavení bude umístěn v adresáři _build v kořenovém adresáři projektu.

Vytvoření lokálně přeložené sestavy

Dokumentace BeeWare' je přeložena do několika jazyků. Aktualizace anglické dokumentace mohou způsobit problémy v jiných jazykových verzích. Před odesláním žádosti o stažení je důležité ověřit, zda všechny verze fungují správně.

Chcete-li vygenerovat sestavení všech dostupných překladů:

macOSLinuxWindows

(venv) $ tox -e docs-all

(venv) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

Výstup každé jazykové sestavy bude umístěn v příslušném adresáři _build/html/<languagecode>, kde <languagecode> je dvoumístný nebo pětimístný kód jazyka přidružený ke konkrétnímu jazyku (např. fr pro francouzštinu, it pro italštinu atd.).

Pokud narazíte na problém s jednotlivou sestavou, můžete ji spustit samostatně pomocí příkazu tox -e docs-<languagecode>. Chcete-li například sestavit pouze francouzskou dokumentaci, spusťte:

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

Výstup jednojazyčné sestavy bude umístěn v adresáři _build.

Kontrola dokumentace

Proces sestavení identifikuje problémy s Markdownem, ale BeeWare provádí některé další kontroly stylu a formátování, známé jako „linting“. Chcete-li spustit kontroly lintingu:

macOSLinuxWindows

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

Tím se ověří, že dokumentace neobsahuje:

• nefunkční odkazy
• špatně napsaná slova

Pokud je platný pravopis slova identifikován jako chybný, přidejte slovo do seznamu v docs/spelling_wordlist. Tím se slovo přidá do slovníku kontroly pravopisu. Při přidávání do tohoto seznamu mějte na paměti:

• Upřednostňujeme americkou pravopisnou normu, s určitými výjimkami pro programátorské slangové výrazy (např. „apps“) a slovesné tvary podstatných jmen (např. „scrollable“).
• Při odkazování na název produktu je třeba používat preferované velká písmena (např. „macOS“, „GTK“, „pytest“, „Pygame“, „PyScript“).
• Pokud je termín používán „jako kód“, měl by být uveden v uvozovkách (like this) namísto přidání do slovníku.

Psaní dokumentace

Toto jsou kroky, které je třeba dodržet při psaní příspěvku do dokumentace BeeWare.

Aktualizace stávající dokumentace

Pokud upravujete existující dokumenty, budete muset najít soubor v adresáři /docs/en. Struktura souborů odpovídá struktuře stránek, takže soubor můžete najít pomocí URL adresy dokumentace.

Přidání nové dokumentace

Pokud přidáváte nový dokument, je třeba provést několik dalších kroků.

Dokument budete muset vytvořit na příslušném místě v adresáři docs/en. Pro účely této diskuse budeme předpokládat, že přidáváte nový dokument s názvem new_doc.md.

Poté budete muset aktualizovat soubor docs/en/SUMMARY.md, aby zahrnoval váš nový soubor. Soubor SUMMARY.md je uspořádán tak, aby v zásadě odrážel strukturu adresáře docs/en, ale co je důležitější, přímo určuje strukturu levého postranního panelu. Pokud najdete sekci, do které chcete zahrnout new_doc.md, nemusíte v souboru SUMMARY.md nic měnit, pokud vidíte uvedenou cestu se zástupnými znaky. Například:

- ./path/to/directory/*

Pokud je část, do které chcete vložit new_doc.md, seznamem jednotlivých odkazů Markdown, budete muset přidat explicitní odkaz na ten svůj. Například:

- [My new document](new_doc.md)

Psaní dokumentace

Nyní můžete otevřít požadovaný soubor ve svém editoru a začít psát.

Máme průvodce stylem dokumentace, který popisuje naše pokyny pro psaní dokumentace pro BeeWare.

Přidat poznámku o změně

Mnoho nástrojů BeeWare používá towncrier k pomoci při vytváření poznámek k vydání pro každé vydání. Když odešlete žádost o stažení do jednoho z příslušných nástrojů, bude nutné zahrnout poznámku o změně – tato poznámka o změně se stane záznamem v poznámkách k vydání popisujícím provedenou změnu.

Každý pull request musí obsahovat alespoň jeden soubor v adresáři changes/, který obsahuje krátký popis změny implementované pull requestem. Poznámka ke změně by měla být ve formátu Markdown, v souboru s názvem ve formátu <id>.<fragment type>.md. Pokud změna, kterou navrhujete, opraví chybu nebo implementuje funkci, pro kterou již existuje číslo problému, bude ID číslem tohoto tiketu. Pokud změna nemá odpovídající problém, lze jako ID použít číslo PR. Toto číslo PR nebudete znát, dokud neodešlete žádost o stažení, takže první CI test selže při kontrole towncrier; přidejte poznámku o změně a odešlete aktualizaci PR a CI by pak mělo projít.

Existuje pět typů fragmentů:

• feature: PR přidává nové chování nebo schopnost, která dříve nebyla možná (např. přidání podpory pro nový formát balení nebo novou funkci ve stávajícím formátu balení);
• bugfix: PR opravuje chybu ve stávající implementaci;
• doc: PR představuje významné zlepšení dokumentace;
• removal; PR představuje zpětně nekompatibilní změnu v API BeeWare; nebo
• misc; Drobná nebo administrativní změna (např. oprava překlepu, drobné jazykové upřesnění nebo aktualizace verze závislosti), kterou není nutné oznamovat v poznámkách k vydání.

Tento popis v poznámce ke změně by měl být obecný „marketingový“ souhrn změny z pohledu uživatele, nikoli podrobný technický popis nebo podrobnosti implementace. Liší se od zprávy o potvrzení – zpráva o potvrzení popisuje, co bylo provedeno, aby budoucí vývojáři mohli sledovat důvody změny; poznámka ke změně je popis pro uživatele, kteří nemusí mít znalosti o vnitřním fungování.

Například pokud opravíte chybu související s pojmenováním projektu, zpráva o potvrzení může znít:

Použijte přísnější kontrolu regulárních výrazů, aby nebyly povoleny názvy projektů začínající číslicemi.

Odpovídající poznámka o změně by zněla přibližně takto:

Názvy projektů již nemohou začínat číslicí.

Některé PR zavádějí více funkcí a opravují více chyb nebo zavádějí více změn, které nejsou zpětně kompatibilní. V takovém případě může PR obsahovat více souborů se změnami. Pokud potřebujete spojit dva typy fragmentů se stejným ID, můžete přidat číselnou příponu. Například pokud PR 789 přidalo funkci popsanou v ticketu 123, opravilo chybu popsanou v ticketu 234 a také provedlo dvě zpětně nekompatibilní změny, můžete mít 4 soubory se změnami:

• 123.feature.md
• 234.bugfix.md
• 789.removal.1.md
• 789.removal.2.md

Další informace o typech fragmentů towncrier a fragmentů najdete v části Fragmenty zpráv. Stávající příklady fragmentů zpráv najdete také v adresáři changes repozitáře BeeWare. Pokud je tato složka prázdná, je to pravděpodobně proto, že BeeWare nedávno vydalo novou verzi; soubory se změnami jsou smazány a sloučeny, aby se aktualizovaly poznámky k vydání s každým vydáním. V tomto souboru si můžete prohlédnout požadovaný styl komentářů; v nedávno sloučených PR si můžete prohlédnout, jak formátovat poznámky ke změnám.

Odeslat žádost o stažení

Nyní, když jste potvrdili všechny změny, jste připraveni odeslat žádost o stažení. Abyste zajistili hladký průběh procesu kontroly, měli byste provést několik kroků.

Práce s pre-commit

Při potvrzení jakékoli změny se automaticky spustí pre-commit. Pokud jsou v potvrzení nalezeny nějaké problémy, potvrzení selže. Pokud je to možné, pre-commit provede změny potřebné k opravě nalezených problémů. V následujícím příkladu byla kontrolou ruff nalezena chyba ve formátování kódu:

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

V tomto případě ruff problém automaticky vyřešilo; můžete tedy znovu přidat všechny soubory, které byly upraveny v důsledku kontrol před odesláním, a změnu znovu odeslat. Některé kontroly však budou vyžadovat ruční úpravy. Jakmile tyto změny provedete, znovu přidejte všechny upravené soubory a znovu je odešlete.

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

Jakmile vše proběhne, zobrazí se zpráva o dokončení commitu a váš git log zobrazí váš commit jako nejnovější přírůstek. Nyní jste připraveni odeslat data na GitHub.

Odesílejte své změny na GitHub a vytvořte žádost o stažení.

Při prvním odeslání na GitHub vám bude poskytnuta URL adresa, která vás přenese přímo na stránku GitHub, kde můžete vytvořit nový pull request. Klikněte na URL adresu a vytvořte svůj pull request.

Následující příklad ukazuje, co můžete očekávat na push, s vyznačenou URL adresou.

macOSLinuxWindows

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

Pokud jste již aktuální větev odeslali na GitHub, URL adresu znovu neobdržíte. Existují však i jiné způsoby, jak získat URL adresu pro vytvoření PR:

• Přejděte do upstreamového repozitáře, klikněte na „Pull Requests“ (Žádosti o stažení) a poté na „New pull request“ (Nová žádost o stažení) a vyberte, odkud chcete odeslat svou žádost o stažení.
• Pokud jste nedávno provedli push, přejděte do upstreamového repozitáře, najděte banner nad seznamem souborů, který označuje, že repozitář „měl nedávné pushy“, a klikněte na tlačítko „Porovnat a stáhnout požadavek“.
• Použijte příkaz GitHub CLI gh pr create a vyplňte požadované údaje.
• Pomocí příkazu GitHub CLI gh pr create --web otevřete webový prohlížeč na stránce pro vytvoření PR.

Kterákoli z těchto možností vám umožní vytvořit nový pull request.

CLI GitHub: gh

GitHub poskytuje GitHub CLI, které vám umožňuje přístup k mnoha funkcím GitHubu z vašeho terminálu pomocí příkazu gh. Dokumentace GitHub CLI popisuje všechny funkce.

Obsah žádosti o stažení

Název žádosti o stažení musí být informativní, jasný a stručný. Snažte se, aby byl pokud možno krátký, ale v případě potřeby jsou přijatelné i delší názvy. Dobrý název PR by měl osobě bez jakéhokoli kontextu poskytnout přiměřeně solidní představu o tom, jaká chyba nebo funkce je ve vašem PR implementována.

Popis PR musí jasně odrážet změny v PR. Osoba bez jakéhokoli kontextu by měla být schopna přečíst váš popis a získat relativně úplné pochopení toho, proč se změna provádí. Vyhněte se vtipům, idiomům, hovorovým výrazům a zbytečnému formátování, jako je používání velkých písmen nebo nadměrné interpunkce; má se jednat o přímé vysvětlení toho, co se děje ve vašem PR, a vyhýbání se těmto věcem činí popis přístupnějším pro ostatní.

Pokud existují nějaké případy reprodukce nebo testovací režimy, které jste použili a které ještě nejsou součástí změn uvedených v PR, měly by být vysvětleny a zahrnuty do PR. Vysvětlení by mělo zahrnovat způsob jejich spuštění a postup pro reprodukci požadovaného výsledku.

Pokud váš pull request vyřeší problém #1234, měli byste do popisu pull requestu zahrnout text Fixes #1234. Tím se problém automaticky uzavře, jakmile bude pull request sloučen. Stejnou syntaxi #1234 můžete použít i pro odkazy na jiné diskuze, problémy nebo pull requesty. Pro odkaz na problém v jiném repozitáři před číslo vložte znak - například python/cpython#1234 odkazuje na problém 1234 v repozitáři CPython.

Kontinuální integrace

Kontinuální integrace (CI) je proces automatizované kontroly vašich požadavků na stažení. Může zahrnovat jednoduché kontroly, jako je zajištění správného formátování kódu, ale také spuštění testovací sady a vytvoření dokumentace.

Existuje řada změn, které mohou vést k selhání CI. Obecně řečeno, PR, které neprojde CI, nebudeme posuzovat. Pokud vytvoříte pull request a CI selže, nezačneme s posuzováním, dokud neprojde. Pokud vaše změny vedou k selhání, je vaší povinností zjistit důvod a problém vyřešit.

Pokud CI selže, odkazy na selhání se zobrazí v dolní části stránky PR pod nadpisem „Některé kontroly nebyly úspěšné“. Zobrazí se seznam neúspěšných kontrol, který se zobrazí v horní části seznamu všech kontrol, pokud existují i úspěšné kontroly. Pokud kliknete na odkaz na selhání, dostanete se do protokolu. Protokol často poskytuje všechny informace, které potřebujete k zjištění příčiny selhání. Přečtěte si protokol a zkuste zjistit, proč k selhání dochází, a poté proveďte nezbytné kroky k jeho vyřešení.

Občas se může stát, že kontrola CI selže z důvodů, které nesouvisejí s vašimi změnami. Může to být způsobeno problémem na stroji, na kterém se kontrola CI provádí, nebo nestabilitou kontroly CI. Pokud zaznamenáte selhání a jste si poměrně jisti, že nesouvisí s vašimi změnami, přidejte k vaší PR komentář s touto informací a my se na to podíváme.

Chcete-li spustit nový běh CI, musíte do své větve odeslat nové změny.

Pokud se ocitnete v situaci, kdy potřebujete pomoc s úspěšným absolvováním CI, zanechte komentář k PR, dejte nám vědět a my uděláme, co bude v našich silách, abychom vám pomohli.

Kontroly pre-commit a towncrier

Pokud kontrola pre-commit nebo towncrier selže, zablokuje to spuštění většiny zbývajících kontrol CI. Než bude možné spustit kompletní sadu kontrol, je nutné vyřešit příslušné problémy.

Máme omezené zdroje CI. Je důležité si uvědomit, že pokaždé, když provedete push do větve, spustí se CI. Pokud hodláte provést několik změn, je lepší je provést lokálně a poté je všechny najednou odeslat. CI se spustí pouze na nejnovější commit v dávce, čímž se minimalizuje zatížení našeho systému CI.

Proces odeslání PR není dokončen, dokud neprojde CI, nebo dokud neposkytnete vysvětlení, proč tomu tak není.