Pomoc:Schemat opisu szablonu

Schemat opisu szablonu

Niniejsza strona opisuje sposób tworzenia dokumentacji szablonów w Enkolu.

Dokumentacji rozbudowanego szablonu nie należy umieszczać bezpośrednio w jego kodzie. Zamiast tego należy utworzyć osobną podstronę dokumentacji o nazwie:

Szablon:Nazwa szablonu/opis

i dołączyć ją do strony właściwego szablonu.

Takie rozwiązanie oddziela kod wykonawczy szablonu od jego instrukcji obsługi. Ułatwia utrzymanie dokumentacji, zmniejsza ryzyko przypadkowego uszkodzenia szablonu podczas edycji opisu oraz pozwala niezależnie edytować kod i dokumentację.

Schemat

Dla szablonu:

Szablon:X

tworzymy stronę:

Szablon:X/opis

Na stronie Szablon:X znajduje się właściwy kod szablonu, natomiast na stronie Szablon:X/opis jego dokumentacja.

Tworzenie strony dokumentacji

Na początku strony:

Szablon:X/opis

należy umieścić:

{{Podstrona dokumentacji}}<!-- EDYTUJ DOKUMENTACJĘ SZABLONU PONIŻEJ TEJ LINII -->

Poniżej należy umieścić właściwą dokumentację szablonu.

Typowa dokumentacja może zawierać następujące sekcje:

== Zastosowanie ==

== Użycie ==

== Parametry ==

== Przykłady ==

== Szablony podrzędne i pomocnicze ==

== Dane semantyczne ==

== Uwagi techniczne ==

Nie każdy szablon wymaga wszystkich wymienionych sekcji. Dokumentacja powinna odpowiadać rzeczywistemu stopniowi złożoności szablonu.

Dołączenie dokumentacji do szablonu

Na końcu właściwego kodu strony Szablon:X należy dodać:

<noinclude>
{{Dokumentacja}}
</noinclude>

Ważne: otwierający znacznik <noinclude> powinien znajdować się bezpośrednio po końcu kodu szablonu, w tej samej linii.

Przykład:

</includeonly><noinclude>
{{Dokumentacja}}
</noinclude>

Nie należy stosować:

</includeonly>
<noinclude>
{{Dokumentacja}}
</noinclude>

ponieważ znak końca linii pomiędzy właściwym kodem a <noinclude> może zostać uwzględniony przy dołączaniu szablonu do innych stron.

Zalecana zawartość dokumentacji

Zastosowanie

Należy krótko opisać:

• do czego służy szablon;
• na jakiego rodzaju stronach powinien być używany;
• jakie informacje wyświetla lub generuje;
• czy zapisuje dane semantyczne.

Przykład:

== Zastosowanie ==

Szablon służy do wyświetlania metryki pojazdu oraz zapisywania podstawowych danych jako właściwości Semantic MediaWiki.

Użycie

Należy podać co najmniej jedno prawidłowe wywołanie szablonu.

Dla bardziej rozbudowanych szablonów wskazane jest podanie:

• przykładu minimalnego;
• przykładu pełnego lub typowego.

Przykład:

== Użycie ==

<pre>
{{Nazwa szablonu
|Parametr1=
|Parametr2=
}}

Jeżeli dokumentowany kod zawiera znaczniki <pre>, można zamiast nich zastosować znaczniki <syntaxhighlight> albo odpowiednio rozdzielić przykłady, aby uniknąć zagnieżdżenia identycznych znaczników.

Parametry

Parametry najlepiej opisywać w tabeli:

{| class="wikitable"
! Parametr
! Znaczenie
! Uwagi
|-
| <code>Parametr1</code>
| Opis parametru
| Informacja dodatkowa
|-
| <code>Parametr2</code>
| Opis parametru
| Pole opcjonalne
|}

W opisie należy w szczególności zaznaczać:

• parametry obowiązkowe;
• parametry opcjonalne;
• wartości domyślne;
• dozwolone wartości;
• zależności między parametrami;
• szczególne zachowanie dla określonych wartości.

Przykłady

Jeżeli samo zestawienie parametrów nie wyjaśnia działania szablonu wystarczająco jasno, należy podać praktyczne przykłady.

Warto pokazywać przede wszystkim przypadki typowe oraz takie, w których zachowanie szablonu może nie być oczywiste.

Dane semantyczne

Jeżeli szablon korzysta z Semantic MediaWiki, dokumentacja powinna wskazywać zapisywane właściwości.

Przykładowy układ:

{| class="wikitable"
! Właściwość
! Źródło danych
|-
| <code>Nazwa właściwości</code>
| parametr <code>Nazwa parametru</code>
|}

Jeżeli właściwość jest zapisywana przez szablon podrzędny, warto również to zaznaczyć.

Szablony podrzędne i pomocnicze

W przypadku rozbudowanych szablonów należy wymienić szablony, od których zależy ich działanie.

Warto rozróżnić:

• szablony wywoływane bezpośrednio – znajdujące się w kodzie dokumentowanego szablonu;
• szablony pomocnicze – używane np. wewnątrz wartości jego parametrów albo przez inne szablony podrzędne.

Przykład:

== Szablony podrzędne i pomocnicze ==

=== Szablony wywoływane bezpośrednio ===

* [[Szablon:X dane]] – wyświetla pojedynczy element danych;
* [[Szablon:X grafika]] – wyświetla grafikę.

=== Szablony pomocnicze ===

* [[Szablon:X historia]] – tworzy pojedynczy wpis historii.

Dzięki temu łatwiej ustalić zależności pomiędzy szablonami przed ich zmianą albo usunięciem.

Uwagi techniczne

W tej sekcji można opisać informacje istotne dla osób utrzymujących kod, na przykład:

• sposób działania responsywnego układu;
• klasy CSS wykorzystywane przez szablon;
• zależność od MediaWiki:Common.css;
• sposób obsługi pustych parametrów;
• nietypowe zachowanie parsera;
• ograniczenia wynikające z konstrukcji szablonu.

Nie należy natomiast przepisywać tutaj całego kodu szablonu.

Kategorie

Jeżeli szablon należy do kategorii, kategorię należy umieścić na jego podstronie dokumentacji, a nie bezpośrednio na stronie właściwego szablonu.

Na końcu strony Szablon:X/opis można w takim przypadku użyć:

<includeonly>
[[Kategoria:Nazwa kategorii szablonów]]
</includeonly>

Jeżeli szablon nie jest kategoryzowany, blok ten nie jest potrzebny.

Dlaczego dokumentacja jest oddzielona od kodu

Oddzielenie dokumentacji od właściwego kodu daje kilka korzyści:

• dokumentację można edytować bez ingerowania w działający kod szablonu;
• zmiana opisu nie powoduje zmiany treści transkludowanej na stronach używających szablonu;
• rozbudowana instrukcja obsługi nie zwiększa niepotrzebnie kodu właściwego szablonu;
• łatwiej zabezpieczyć ważny szablon przed przypadkową zmianą, pozostawiając możliwość poprawiania jego dokumentacji;
• struktura stron szablonów jest bardziej przejrzysta.

Przykład

Dla szablonu:

Szablon:Lw metryka pojazdu

dokumentacja znajduje się na stronie:

Szablon:Lw metryka pojazdu/opis

Końcówka właściwego szablonu ma postać:

</includeonly><noinclude>
{{Dokumentacja}}
</noinclude>

Natomiast strona dokumentacji rozpoczyna się od:

{{Podstrona dokumentacji}}<!-- EDYTUJ DOKUMENTACJĘ SZABLONU PONIŻEJ TEJ LINII -->

Dobre praktyki

• Dokumentacja powinna opisywać aktualne działanie szablonu, a nie jego historyczne wersje.
• Po istotnej zmianie parametrów należy zaktualizować również stronę /opis.
• Nazwy parametrów w dokumentacji powinny być zapisane dokładnie tak samo jak w kodzie.
• W przykładach należy używać rzeczywiście obsługiwanych wartości.
• Nie należy dokumentować nieistniejących właściwości semantycznych ani nieużywanych podszablonów.
• Przed usunięciem szablonu podrzędnego należy sprawdzić jego użycie za pomocą strony „Linkujące tutaj”.
• Jeżeli zachowanie szablonu zależy od CSS, należy wskazać odpowiednie klasy lub stronę zawierającą style.
• Dokumentacja powinna być możliwie kompletna, ale nie powinna niepotrzebnie powtarzać oczywistych fragmentów kodu.

Zobacz też

• Pomoc:Szablony
• MediaWiki:Common.css

Źródło rozwiązania

Schemat oddzielania dokumentacji od kodu szablonu został opracowany na podstawie rozwiązania stosowanego w polskojęzycznej Wikipedii na stronie „Pomoc:Schemat opisu szablonu”.