Wikipédia:Sablondokumentáció forrásának megtekintése

{{Fejléc
|stílus = Segítség
|cím = Sablondokumentáció
|1. szint = [[Wikipédia:Segítség|Segítség]]
|2. szint = [[Wikipédia:Sablonok|Sablonok]]
|kapcsolódó lapok=Sablonok
}}
{{technikai leírás}}
A [[Wikipédia:Sablonok|sablonok]] nagyban megnövelik a cikkírók lehetőségeit, de a kezdők számára nehezen érthetőek, és a számtalan különböző sablont és paramétert nehéz fejben tartani. Ezért fontos, hogy minden sablonhoz részletes dokumentáció tartozzon, ami leírja, mire való a sablon és hogyan kell használni, és a hasonló sablonok megtalálását is megkönnyíti.

== Mi szerepeljen a dokumentációban? ==
* Mindenekelőtt '''a sablon célja''': mit csinál a sablon, és (ha nem magától értetődő) mi értelme azt csinálni. Ha van idevágó irányelv, útmutató vagy segítség lap, említsd meg. Ha vannak erre a feladatra más sablonok is, említsd meg őket és mondd meg, miben különbözik ez a sablon a többitől; így kisebb az esélye, hogy a rossz sablont használja valaki.
* A sablon '''paraméterei'''. Írd le, hogy milyen paramétereket lehet használni, mik a névtelen paraméterek, mely paraméterek opcionálisak és mi az alapértelmezett értékük (ha van). Ha van valami kötelező vagy jellemző használati módja az egyes paramétereknek (pl. csak szám lehet; ha belső linket akarsz, kézzel kell beleírni), add meg azt is.
* '''Példák'''. Adj néhány példát, hogyan kell használni, és az mit eredményez. Ha a sablonnak sok paramétere van, csinálj egy konkrét értékek nélküli, másolható mintát a <tt><nowiki><tt>...</tt></nowiki></tt> vagy a <tt><nowiki><pre>...</pre></nowiki></tt> használatával. 
* '''Kapcsolódó sablonok''': ha a sablon több, együtt használandó vagy hasonló funkciójú sablon egyike, mindig linkelj a többi sablonra, hogy megkönnyítsd a navigációt. Ha elég sok sablonról van szó, érdemes külön navigációs sablont csinálni erre a feladatra. (Lásd például az angol [[:en:Template:Protection templates|Protection templates]] sablont.) A sablonok megadásához érdemes az {{sl|sl}} sablont használni.

== Hogyan írj dokumentációt? ==
{{fő|Sablon:Sablondokumentáció}}
Az egyszerűbb megoldás, ha simán beírod a dokumentáció szövegét, a kategóriákat a sablon végén elhelyezett <tt><nowiki><noinclude>...</noinclude></nowiki></tt> blokkba, hogy csak a sablon saját lapján jelenjen meg, a sablon használatakor ne. (Ügyelj rá, hogy a <tt><nowiki><noinclude></nowiki></tt> ne új sorban kezdődjön, hanem az utolsó nem üres sor végén! Máskülönben a sablon használatakor több üres hely lesz utána, mint szeretnéd.) Ha a sablon a saját lapján csúnyán jelenik meg (például mert nincsenek megadva a paraméterek, amik a megjelenését szabályozzák), beleteheted a kódját egy <tt><nowiki><includeonly>...</includeonly></nowiki></tt> blokkba (de a dokumentációt nem!), hogy csak beillesztéskor jelenjen meg, a sablon saját lapján ne.

A '''javasolt megoldás''' azonban a '''[[Sablon:Sablondokumentáció|dokumentációs allap]]''' használata, ilyenkor a dokumentáció a ''Sablon:Sablonneve/doc'' lapról lesz beillesztve. Ennek számos előnye van:
* mind a sablon, mind a dokumentáció szövege áttekinthetőbb lesz;
* nem áll fenn a veszélye, hogy a dokumentáció átírása közben véletlenül elrontja valaki a sablont;
* a dokumentáció akkor is szerkeszthető, ha a sablon le van védve;
* a dokumentáció nem növeli a sablont (ami nem lehet tetszőlegesen nagy – lásd [[:en:Wikipedia:Template limits]]);
* a MediaWiki fordítójának nem kell a dokumentáció minden egyes változtatásakor ellenőriznie, hogy a sablon változott-e.

Dokumentációs allap használatához a sablon végére a '''<tt><nowiki><noinclude>{{sablondokumentáció}}</noinclude></nowiki></tt>''' szöveget írd be. (Ilyenkor is ügyelj rá, hogy a <tt><nowiki><noinclude></nowiki></tt> ne új sorban kezdődjön!) A sablon elmentése után megjelenő doboz "szerkeszt" gombjára kattintva szerkesztheted a dokumentációs allapot. A kategóriákat ilyenkor a dokumentációs allap végén egy <tt><nowiki><includeonly>...</includeonly></nowiki></tt> blokkba zárd, hogy csak a sablonra vonatkozzanak, az allapra ne.

===Navigációs sablonok dokumentációja===
{{fő|Sablon:Navbox sablondokumentációja}}
A navigációs sablonok számára speciális, de egyszerűen használható sablondokumentáció készült, melyet az alábbi módon illeszthetsz be (<code><nowiki><noinclude></noinclude></nowiki></code> közé):

;{{sl|navbox}} esetében:
<pre>
{{Navbox sablondokumentációja||helyettesítő szöveg}}
</pre>

;{{sl|navoszlop}} esetében:

<pre>
{{Navbox sablondokumentációja||helyettesítő szöveg||navoszlop=igen}}
</pre>

=== TemplateData ===
Ahhoz, hogy a sablon a [[Wikipédia:VisualEditor|vizuális szerkesztőben]] kényelmesen használható legyen, [[Wikipédia:TemplateData|TemplateData]]-leírás szükséges. Ez egy szabványos formátum, ami tartalmazza a sablon általános leírását és az egyes paramétereket is (címke, leírás, kötelező-e stb.). A beillesztés helyén megjelenik a sablondokumentációban, így általában a paraméterekhez ezen felül nem szükséges dokumentáció, de a vizuális szerkesztő is le tudja kérdezni, ezáltal a használónak nem kell megnyitnia a sablon lapját ahhoz, hogy tudja, milyen paraméterek vannak és azok mire valók. A TemplateData egy &lt;templatedata&gt; és &lt;/templatedata&gt; címkék között elhelyezett [[JSON]]-tömb, sablondokumentáció szerkesztésekor létrehozható a ''{{int:templatedata-editbutton}}'' gombbal.

== A kategóriák elhelyezése ==
A sablon lapján a sablondokumentációs allap beillesztését (<tt><nowiki>{{sablondokumentácó}}</nowiki></tt>) „noinclude”-ba tesszük, hiszen nem akarjuk, hogy a sablondokumentáció ott is megjelenjen, ahova a sablont beillesztjük.
*A sablondokumentációt tartalmazó doc lapon pedig „includeonly”-val ellátott részbe tesszük azokat a kategóriákat, amik nem a dokumentációra, hanem a sablonra vonatkoznak. Így a sablondokumentáció maga nem lesz ezekbe a kategóriákba besorolva, de a sablon igen;<br />a sablondokumentáció saját kategóriáinak viszont egy „noinclude”-os részben van a helye, hogy csak a sablondokumentáció kerüljön be ezekbe a kategóriákba, a sablon ne.
Ezt az elég nehezen megjegyezhető szisztémát a sablondokumentáció egy előre betöltött mintával, és az azon feltüntetett kommentárokkal segíti.

Ez a gyakorlat elkerülhetővé teszi, hogy magának a sablonnak a megváltoztatására legyen szükség a sablon kategóriáin végzett változtatásokkor. Ha a változtatások közvetlenül a sablonokon történnének, az a szervernél az összes olyan lap frissítését vonná maga után, amire a sablon be van illesztve. Ez egy gyakran használt sablonnál tetemes terhelést jelenthet.

== Példa ==
A [[Sablon:Cite web|Cite web]] sablon példa egy allappal dokumentált sablonra.

== Lásd még ==
* {{sl|sablondokumentáció}}
* {{sl|nincs dokumentáció}}
* [[:Kategória:Sablonok dokumentációval]]
* [[m:Help:Template#Noinclude, includeonly, and onlyinclude|<nowiki>a <noinclude> és az <includeonly></nowiki>]] {{en}}
* [[m:Meta:Template doc page pattern]] {{en}}

[[Kategória:Technikai leírások]]