Nápověda:Jak dokumentovat šablony
|
Každá šablona musí být náležitě zdokumentována a kategorizována, aby bylo zřejmé jakým způsobem a pro jaký účel se může použít. |
Dokumentace šablony
Dokumentace šablony se nikdy nepíše přímo do šablony, ale vždy na její podstránce s názvem doc.
Do šablony se bezprostředně za vlastní obsah šablony do elementu noinclude vloží pouze šablona {{Dokumentace}}, za kterou následuje kategorizace šablony:
<noinclude>{{Dokumentace}}</noinclude>
|
|
Pozor na odřádkování! U některých šablon může v takovém případě docházet k nežádoucí interpretaci. |
Podstránku doc, s dokumentací k šabloně, lze zavolat buď přímo přes její URL, nebo kliknutím na odkaz, který na stránce šablony generuje šablona {{Dokumentace}}.
Náležitosti dokumentace
Každá dokumentace k šabloně musí obsahovat následující:
- Hned v úvodu vloženou šablonu
{{Podstránka s dokumentací}} - V případě složitých šablon šablonu
{{Složitá šablona}}, která zajistí vygenerování upozornění pro případné editory u komplexních šablon. - Systémovou konstantu
, která potlačí generování obsahu - Popis šablony - co dělá, k čemu slouží, pro jaký účel byla vytvořena
- Syntaxe - jak má vypadat zápis šablony, případně jaké lze u ní použít parametry
- Použití - ukázka interpretace šablony
- Kategorie - i šablony musí být odpovídajícím způsobem kategorizovány
{{Složitá šablona}}, aby byl každý předem varován, že nežádoucí úpravou šablony může dojít k narušení její funkcionality|
|
Pokud se na stránce s dokumentací šablony nezobrazuje kategorizace, pak s největší pravděpodobností chybí na počátku stránky šablona {{Podstránka s dokumentací}}!
|
Kategorizace šablony
- Každá šablona, která není podstránkou
- se zařadí do kategorie Kategorie:Šablony.
- Šablona, která je sama podstránkou nějaké šablony nebo je na nějaké jiné šabloně závislá
- se zařadí do kategorie Kategorie:Šablony závislé
- Šablona, která má na něco upozornit, či před něčím varovat
- se přidá do kategorie Kategorie:Výstražné šablony
- Šablona, která je závislá na některém z rozšíření
- se přidá do kategorie šablon které používají příslušného rozšíření např. Kategorie:Šablony užívající ParserFunctions
<noinclude>
[[Kategorie:Šablony]]
[[Kategorie:Výstražné šablony]]
[[Kategorie:Nedokumentováno]]
{{Dokumentace}}
</noinclude>
Po založení podstránky s dokumentací se z kategorizace šablony vyřadí Kategorie:Nedokumentováno, a samotná podstránka doc se kategorizuje do kategorie Kategorie:Šablony (dokumentace), tím že se do jejího záhlaví vloží šablona {{Podstránka s dokumentací}}.
Lokalizace dokumentace k šablonám
Pokud chceme lokalizovat dokumentaci k šabloně, je lepší dokumentaci přesunout na novou samostatnou stránku a tu následně vkládat do stránky doc, stejným způsobem jak demonstruje níže uvedený příklad.
{{ll}}:
__NOTOC__
{{Podstránka s dokumentací}}
<includeonly>{{Složitá šablona}}</includeonly>
{{:{{#explode:{{ll|Multijazyčné odkazy na stránky/{{int:languagecode}}|none|}}|#|0}}}}
