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í funkcionalityPokud 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}}}}