Pravidla pro styl dokumentace

Tato příručka obsahuje informace o očekávaném stylu, syntaxi specifické pro MkDocs, různých požadovaných nástrojích a překladu dokumentace, s ohledem na psaní nového obsahu a překlad stávajícího obsahu.

Obecný styl

• V záhlavích a nadpisech by mělo být velké písmeno pouze v prvním slově.
• 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“).
• Pravopis slov „artefact“ a „artefacts“ je uvedený.
• Po tečce používáme jednoduché mezery.
• Jako dlouhou pomlčku používáme jednu pomlčku obklopenou mezerami (nebo HTML — literal).
• 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 jako inline kód, a to tak, že se obklopí jednoduchými zpětnými lomítky, místo aby byl přidán do slovníku.
• Při popisu akcí, které by měl uživatel provést, se vyhýbáme používání výrazů jako „jednoduše“, „jen“ nebo „snadno“. Tyto výrazy mohou být vnímány jako pejorativní, zejména pokud uživatel narazí na potíže.

Křížové odkazy na informace

V dokumentaci byste měli pokud možno používat křížové odkazy na obsah. Tato část popisuje různé způsoby, jak toho dosáhnout, přičemž každý z nich závisí na typu informací, na které odkazujete.

MkDocs vykresluje standardní odkazy ve formátu Markdown. Standardní webové hypertextové odkazy ve formátu Markdown mají následující podobu:

[Link text](https://example.com/)

Tento formát můžete také použít pro odkaz na místní soubor:

[Link text](path/to/file.md)

Odkazování na konkrétní části souborů nebo dokumentace API vyžaduje použití formátu odkazů MkDocs.

Vlastní kotvy Markdown a křížové odkazy na obsah

Markdown generuje kotvy pro všechny záhlaví (vše, co je na jednom řádku a začíná jedním až šesti symboly #), na základě obsahu záhlaví. Například kotva generovaná pro tuto sekci je custom-markdown-anchors-and-content-cross---referencing. Avšak vzhledem k tomu, jak fungují naše překlady, musí mít každé záhlaví sekce, na které se odkazuje, vlastní kotvu.

MkDocs podporuje vykreslování syntaxe odkazů, která umožňuje propojit různé prvky v dokumentaci pomocí upraveného odkazu Markdown. To zahrnuje mimo jiné propojení s vlastními záhlavími Markdown a textovými kotvami.

Odkazy MkDocs jsou jakékoli odkazy ve formátu:

[Link text][link-target]

Je nutné zadat vlastní záhlaví a obsahové kotvy.

Každá sekce záhlaví nebo obsahu, na kterou se odkazuje v textovém obsahu prostřednictvím odkazu MkDocs v dokumentaci BeeWare, musí mít připojenou vlastní kotvu. V opačném případě hrozí, že při překladu obsahu záhlaví dojde k poškození odkazů.

Pokud potřebujete odkazovat na kotvu v záhlaví, budete muset pro daný obsah vytvořit vlastní kotvu. Obecná syntaxe pro nastavení vlastní kotvy je následující:

# Header text { #anchor-name }

Například přizpůsobení kotvy pro tuto sekci na custom-anchors by se provedlo pomocí následujícího formátování:

## Custom Markdown anchors { #custom-anchors }

Můžete také vytvořit odkaz na obecný obsah, včetně textu a bloků kódu. Následující formátování s novými řádky nad a pod by mělo být zahrnuto nad obsahem, na který chcete odkazovat:

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

Jakmile jsou vlastní kotvy vytvořeny, můžete na ně odkazovat ze stejného dokumentu nebo z jiných částí dokumentace.

Standardní Markdown se používá k odkazování na kotvu ve stejném souboru, která je formátována následovně:

[Link text](#anchor-name)

Odkaz na kotvu v samostatném dokumentu používá styl odkazu MkDocs, který je formátován následovně:

[Link text][anchor-name]

Odkazy na referenční API

Odkazy MkDocs také podporují křížové odkazy na dokumentaci API, včetně dokumentovaných tříd, metod nebo atributů tříd a konkrétních odkazů na externí dokumentaci.

Existuje několik možností pro odkazování na dokumentovanou třídu, metodu třídy nebo atribut, bez ohledu na to, zda odkazujete ze stejného souboru nebo z jiného souboru. Při odkazování na třídy atd. musíte do první sady hranatých závorek vložit zpětné lomítko, aby se název zobrazil jako vložený kód. Zpětné lomítko není nutné pouze v případě, že používáte vlastní text, který se nemá zobrazovat jako vložený kód. Zpětné lomítko by nikdy nemělo být zahrnuto do druhé sady hranatých závorek.

Odkaz na třídu při zobrazení jmenného prostoru je formátován následovně:

[`module.ClassName`][]

Odkaz na třídu při zobrazení pouze názvu třídy je formátován následovně:

[`ClassName`][module.ClassName]

Atributy jsou stejné jako výše, včetně názvu atributu. Následující příklad zobrazuje jmenný prostor:

[`module.ClassName.attributename`][]

Stejně jako u tříd je zobrazení pouze názvu atributu formátováno následovně:

[`attributename`][module.ClassName.attributename]

Metody by měly být zobrazeny s () za jmenným prostorem, a proto musí být zpracovány jinak než atributy. Následující postup je správným způsobem pro odkazování na metodu:

[`module.ClassName.methodname()`][module.ClassName.methodname]

Následující příklad zobrazuje pouze název třídy a metody. To také vyžaduje zahrnutí závorek za názvem:

[`Classname.methodname()`][module.Classname.methodname]

Můžete odkazovat na třídu, metodu nebo atribut a zároveň zobrazovat libovolný text pomocí stejné metody s příslušným jmenným prostorem. U třídy se to formátuje následovně:

[link text][module.ClassName]

Je také možné odkazovat přímo na dokumentaci jádra Pythonu, stejně jako na dokumentaci Pillow. Například pro odkaz na dokumentaci pro int:

[`int`][]

Odkaz na dokumentaci Pillow Image:

[`PIL.Image.Image`][]

Tipy pro bloky kódu

Zvýraznění jazyka a kódu

Jazyk kódu obsaženého v bloku kódu můžete určit tak, že za prvními třemi zpětnými lomítky uvedete název jazyka bez mezery. Výsledkem bude správné zvýraznění kódu při jeho vykreslení. Chcete-li například určit jazyk Python, začněte blok kódu znaky ```python.

Příkazy konzole a tlačítko kopírování

Pokud zahrnujete příkazy konzole nebo příkazy s výstupem, označte je jako console nebo doscon, v závislosti na tom, zda popisujete operační systém typu Unix (včetně macOS) nebo Windows. Můžete zahrnout výzvu poskytovanou operačním systémem; po kliknutí na tlačítko Kopírovat se zkopíruje pouze příkaz. Například pokud začnete blok kódu znaky ```console a zahrnete následující obsah:

$ mkdir test
$ ls
test

Poté kliknutím na tlačítko Kopírovat v bloku kódu zkopírujete pouze příkazy a ignorujete výzvy a výstup. Tímto způsobem můžete označit, že se jedná o příkazy konzoly, a zároveň umožnit uživatelům efektivní používání tlačítka Kopírovat.

Zvýraznění konkrétních řádků kódu

Můžete zvýraznit konkrétní řádky kódu. Chcete-li například zvýraznit řádek 2, přidejte za jazyk mezeru a za ni {hl_lines="2"}. Váš blok kódu tak bude začínat ```python {hl_lines="2"}. Výsledek je následující:

import toga
from toga.style.pack import COLUMN, ROW

Můžete zvýraznit více různých řádků. Například python {hl_lines="3 5 9"} zvýrazní řádky 3, 5 a 9. Můžete také zvýraznit rozsah řádků. Například python {hl_lines="3-8"} zvýrazní řádky 3 až 8. Můžete zvýraznit více rozsahů, například python {hl_lines="9-18 23-44"}.

Prvky Markdown, které vyžadují specifické formátování

Vzhledem ke způsobu generování překladových souborů je důležité zahrnout požadované nové řádky do syntaxe Markdown pro upozornění, poznámky, záložky, direktivy Jinja, popisky obrázků a zarovnání atd.

Napomenutí a poznámky

Upozornění musí být formátována následovně, včetně zajištění nového řádku před a za začátkem a koncem upozornění:

Content above.

/// admonition | Title

Admonition text.

A second paragraph.

///

Content below.

To funguje stejným způsobem u všech podporovaných typů upozornění. Například poznámky k upozorněním vyžadují stejné formátování a nové řádky:

Content above.

/// note | Note title

Note text here.

///

Content below.

Všechny podporované typy napomenutí jsou k dispozici pro použití jako napomenutí.

Obsah v záložkách

Obsah s tabulátory je formátován následovně, včetně nového řádku před začátkem a po konci bloku obsahu:

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

Záložka s vnořeným upozorněním by byla formátována následovně, včetně nového řádku před a za blokem obsahu:

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

Sbalený obsah

Sbalený obsah je formátován následovně, včetně nových řádků:

Content above.

/// details-note | Collapsed content title

Collapsed content.

///

Content below.

Všechny podporované typy upozornění jsou k dispozici pro použití se sbaleným obsahem, musíte je však deklarovat jako details-admonitiontype. Takže sbalený blok typu „poznámka“ by byl details-note (jak je uvedeno výše), sbalený blok typu „varování“ by byl details-warning a tak dále.

Jinja direktivy

V dokumentaci je několik prvků, které v textu používají direktivy Jinja. Vše, co používá prvky direktivy Jinja, musí být zabaleno do nových řádků. Například tutoriál BeeWare obsahuje podmíněné výrazy Jinja založené na proměnných, které určují, jaké upozornění se má zobrazit na hlavní stránce. Ty jsou formátovány následovně:

Content above.



Content below.

Existuje také syntaxe pro nahrazování symbolů nebo textu. Tato syntaxe je proměnná uzavřená v páru shodných dvojitých složených závorek a pokud je na samostatném řádku, musí před a za ní být nový řádek.

Content above.

{{ variable }}

Content below.

Formátování obrázků

U obrázků lze nastavit šířku a zarovnat je vlevo, vpravo nebo na střed (s výhradou u „středu“). Obrázky by měly vždy obsahovat smysluplný alternativní text pro účely přístupnosti.

Nastavení šířky 300px u obrázku by bylo formátováno následovně:

![Image alt text](../path/to/image.png){ width="300px" }

Zarovnání obrázku vlevo (nebo vpravo) by bylo formátováno následovně:

![Image alt text](../path/to/image.png){ align=left }

Přidání popisku k obrázku vyžaduje nový řádek před a za popiskem a je formátováno následovně:

Content above.

![Image alt text](/path/to/image.png)

/// caption

Caption content.

///

Content below.

Zarovnání středu obrázku pomocí atributu align není možné. Řešením je vložit za obrázek prázdný titulek, který bude zarovnán na střed. Mezi jednotlivými částmi a před a za nimi musíte vložit nové řádky. Formátování je následující:

Content above.

![Image alt text](../path/to/image.png)

/// caption

///

Content below.

Pluginy se specifickým formátováním Markdown

Následující části popisují, jak používat pluginy, které vyžadují specifické formátování Markdown.

Použití úryvků k vložení externího obsahu

Podrobnosti o tom, jak zahrnout externí obsah z lokálního souboru nebo URL, naleznete v dokumentaci k rozšíření Snippets. Snippets by se měly používat, pokud dokument neobsahuje direktivy Jinja, které je třeba provést (provedení Jinja probíhá souběžně se zpracováním Snippets, a proto nebude žádný Jinja v souboru zpracován). Snippets je nezbytný, pokud chcete používat oddělovače, které vám umožňují zahrnout konkrétní části souboru samostatně, např. zdrojový dokument je rozdělen do sekcí, které mají být vloženy samostatně od sebe.

Důležité poznámky:

• Jako identifikátor úryvků používáme -8<-. Dokumentace uvádí několik možností; prosím, řiďte se naším stylem.
• Soubory nalezené ve sdíleném obsahu nástrojů BeeWare Docs Tools jsou považovány za „lokální“ obsah. Proto budete používat buď pouze název souboru, jako v -8<- "docs-style-guide.md", nebo pokud je obsah v podadresáři, pouze adresář a název souboru, jako v -8<- "style/docs-style-guide.md".
• Pokud zahrnujete externí obsah ze souboru na GitHubu prostřednictvím URL, musíte použít URL surového obsahu, jinak se zobrazí celá webová stránka, kamkoli ji vložíte.

Použití maker k vložení obsahu z BeeWare Docs Tools sdílený obsah

Můžete také zahrnout obsah ze sdíleného adresáře nástrojů BeeWare Docs pomocí pluginu Macros MkDocs. Tato metoda je nezbytná, pokud dokument obsahuje direktivy Jinja, které je třeba provést, a měla by být použita pouze v této situaci. Nefunguje s externím obsahem přes URL. S touto metodou funguje mechanismus nahrazování proměnných Macros.

Existují možnosti pro zahrnutí obsahu pomocí maker:

1. Použijte syntaxi Jinja include, pokud chcete dokument vložit bez dalších ručních změn.

2. Použijte syntaxi Jinja extends, pokud jste do dokumentu zahrnuli syntaxi Jinja block, která vám umožňuje přepsat nebo doplnit konkrétní části.

pyspelling

Používáme spellchecker pyspelling. Spouští se během lint-checků.

Pokud pyspelling označuje chybně napsané slovo, ve většině případů by mělo být opraveno v obsahu dokumentace.

V ojedinělých případech, kdy identifikuje platné slovo, které není ve slovníku pyspelling, máte dvě možnosti:

1. Pokud se jedná o slovo, které bude pravděpodobně použito vícekrát, měli byste jej přidat do dokumentu spelling_wordlist v adresáři docs v abecedním pořadí.
2. Pokud se jedná o slovo, které pravděpodobně nebude znovu použito, můžete jej obalit značkou <nospell> / </nospell> a pyspelling jej v textu ignoruje.