Nápověda:Jak dokumentovat šablony

Z thewoodcraft.org
Přehled nápovědy
Editace obsahu
Pro thewoodcraft.org
Knihy
Systém wiki
Zabezpečení stránek
Zásady
Upozornění 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:

Příklad
<noinclude>{{Dokumentace}}</noinclude>
Upozornění 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í:

  1. Hned v úvodu vloženou šablonu {{Podstránka s dokumentací}}
  2. 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.
  3. Systémovou konstantu , která potlačí generování obsahu
  4. Popis šablony - co dělá, k čemu slouží, pro jaký účel byla vytvořena
  5. Syntaxe - jak má vypadat zápis šablony, případně jaké lze u ní použít parametry
  6. Použití - ukázka interpretace šablony
  7. Kategorie - i šablony musí být odpovídajícím způsobem kategorizovány
PoznámkaU komplikovaných šablon je vhodné vložit hned na počátku obsahu dokumentace do párového tagu noinclude šablonu {{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
Upozornění 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
PříkladNásledující příklad demonstruje jak má vypadat kategorizace u nově vytvořené šablony:
<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.

PříkladTakto se vkládá lokalizovaná dokumentace s nápovědou k šabloně {{ll}}:
__NOTOC__
{{Podstránka s dokumentací}}
<includeonly>{{Složitá šablona}}</includeonly>
{{:{{#explode:{{ll|Multijazyčné odkazy na stránky/{{int:languagecode}}|none|}}|&#35|0}}}}