3. Tworzenie własnej dokumentacji
3.3. Rozdziały
3.2. Plik settings.ini
« Poprzedni
3.4. Składnia pliku
Następny »

3.3. Rozdziały

W TypeFriendly poszczególne rozdziały dokumentacji tworzysz jako pliki tekstowe w katalogu /input/jezyk/. Każdy taki plik składa się z dwóch części:

  1. Nagłówek
  2. Treść

W nagłówku znajduje się kilka opcji, które pozwalają ustawić np. właściwy tytuł danego rozdziału lub powiązania z innymi częściami dokumentacji. Pod nagłówkiem umieszczana jest treść w formacie Markdown. Dokładny opis składni tych plików znajduje się dalej, gdyż tutaj pragniemy omówić inną rzecz związaną z rozdziałami, mianowicie ustalanie ich kolejności.

TypeFriendly do ustalania zależności między rozdziałami używa samej nazwy pliku. Każda nazwa musi składać się z rozszerzenia .txt oraz grupy identyfikatorów rozdzielonych kropkami. Każdy identyfikator określa kolejne podrozdziały, do których przypisany jest dany plik. Oto przykładowa lista plików:

  1. wstep.txt
  2. instalacja.txt
  3. instalacja.prosta.txt
  4. instalacja.zlozona.txt
  5. api.txt
  6. api.klasa.txt
  7. api.klasa.funkcja1.txt
  8. api.klasa.funkcja2.txt
  9. api.interfejs.txt
  10. api.interfejs.funkcja1.txt
  11. api.interfejs.funkcja2.txt

Przyjrzyjmy się np. rozdziałowi poświęconemu instalacji. Jest stworzony plik tekstowy dla niego, w którym możemy zamieścić jakieś wprowadzenie. Jednocześnie umieszczamy w nim dwa podrozdziały: instalacja.prosta i instalacja.zlozona. TypeFriendly na podstawie nazw pliku powiąże jedno z drugim i wygeneruje odpowiednią nawigację. Opis API jest już bardziej złożony, ponieważ mamy tutaj aż trzy poziomy. Po słowie wstępu w pliku api.txt tworzymy wprowadzenie do opisu pierwszej z klas (api.klasa.txt). Klasa ma jakieś funkcje, tak więc opisujemy każdą z nich jako osobny podrozdział. Pamiętaj, że jeżeli chcesz stworzyć plik o nazwie foo.bar.joe.txt, w dokumentacji muszą również istnieć foo.txt i foo.bar.txt - inaczej TypeFriendly zwróci błąd.

Domyślnie TypeFriendly sortuje poziomy zagnieżdżeń alfabetycznie. Możemy wpływać na tę kolejność, tworząc w głównym katalogu projektu plik sort_hints.txt z dodatkowymi wskazówkami dla tych rozdziałów, które chcesz sortować inaczej. Bez nich powyższy przykład zostanie automatycznie ułożony w następującej kolejności:

  1. api.txt
  2. api.interfejs.txt
  3. api.interfejs.funkcja1.txt
  4. api.interfejs.funkcja2.txt
  5. api.klasa.txt
  6. api.klasa.funkcja1.txt
  7. api.klasa.funkcja2.txt
  8. instalacja.txt
  9. instalacja.prosta.txt
  10. instalacja.zlozona.txt
  11. wstep.txt

Jest to trochę bez sensu, ponieważ o ile super, że funkcje są sortowane automatycznie, o tyle wstęp na końcu dokumentacji może już wzbudzić u czytelników zdumienie. Umieśćmy więc w sort_hints.txt parę wskazówek:

wstep
instalacja
instalacja.prosta
instalacja.zlozona
api
api.klasa
api.interfejs

Widać, że w pliku tym podajemy po prostu w nowych liniach żądaną kolejność. Jeśli dla jakiegoś rozdziału pasuje nam sortowanie alfabetyczne, po prostu nie wymieniamy jego zawartości (np. nie wypisaliśmy tutaj żadnych funkcji z api.klasa i api.interfejs). Jeżeli spróbujemy zrobić mix, wymieniając tylko część zawartości danego rozdziału, TypeFriendly zgłosi błąd podczas próby wygenerowania dokumentacji.

Wskazówki:

  1. Plik ze wskazówkami jest jeden dla wszystkich języków, dlatego bardzo ważne jest, aby w każdej wersji językowej odpowiadające sobie rozdziały miały tę samą nazwę pliku.
  2. Nazwa pliku jest też wykorzystywana do identyfikowania rozdziałów przy tworzeniu ręcznym odnośników w tekście. Dlatego wybieraj nazwy krótkie i intuicyjne, trzymając się jakichś reguł. Ułatwi to późniejsze odnalezienie się w tym wszystkim.
  3. TypeFriendly pomija pliki z innym rozszerzeniem lub kończące się np. tyldą, tak więc nie trzeba wyłączać opcji tworzenia kopii zapasowej w edytorze, aby tworzyć dokumentację.

Zobacz także:

3.3. Rozdziały
3. Tworzenie własnej dokumentacji
« Poprzedni
3.2. Plik settings.ini
Następny »
3.4. Składnia pliku