Przejdź do treści

Przewodnik po stylu dokumentacji

Niniejszy przewodnik zawiera informacje dotyczące oczekiwanego stylu, składni specyficznej dla MkDocs, różnych wymaganych narzędzi oraz tłumaczenia dokumentacji, w odniesieniu do pisania nowych treści i tłumaczenia istniejących treści.

Ogólny styl

  • W nagłówkach i tytułach tylko pierwsze słowo powinno być pisane wielką literą.
  • Preferujemy pisownię amerykańską, z pewnymi swobodami w zakresie kolokwializmów związanych z programowaniem (np. „apps”) oraz czasownikowania rzeczowników (np. „scrollable”).
  • Pisownia słów „artefakt” i „artefakty” jest zgodna z podaną powyżej.
  • Po kropce stosujemy pojedyncze spacje.
  • Używamy pojedynczego łącznika otoczonego spacjami jako myślnika (lub literału HTML —).
  • Wszelkie odniesienia do nazwy produktu powinny być zapisywane zgodnie z preferowaną wielkością liter. (np. „macOS”, „GTK”, „pytest”, „Pygame”, „PyScript”).
  • Jeśli termin jest używany „jako kod”, należy go zacytować jako kod wbudowany, otaczając go pojedynczymi znakami backtick, zamiast dodawać go do słownika.
  • Unikamy używania takich terminów jak „po prostu”, „tylko” lub „łatwo” podczas opisywania czynności, które użytkownik powinien wykonać. Terminy te mogą być odbierane jako pejoratywne, zwłaszcza gdy użytkownik napotyka trudności.

Informacje dotyczące odniesień krzyżowych

W miarę możliwości należy umieszczać odniesienia do treści w dokumentacji. W tej sekcji omówiono różne sposoby, w jakie można to zrobić, z których każdy opiera się na rodzaju informacji, do których się odwołuje.

MkDocs renderuje standardowe linki sformatowane w Markdown. Standardowe hiperłącza internetowe sformatowane w Markdown wyglądają następująco:

[Link text](https://example.com/)

Możesz również użyć tego formatu, aby utworzyć link do pliku lokalnego:

[Link text](path/to/file.md)

Odwołania do konkretnych sekcji plików lub dokumentacji API wymagają użycia formatu linków referencyjnych MkDocs.

Niestandardowe kotwice Markdown i odsyłacze do treści

Markdown generuje kotwice dla wszystkich nagłówków (wszystko w jednej linii zaczynające się od jednego do sześciu symboli #), na podstawie treści nagłówka. Na przykład kotwica wygenerowana dla tej sekcji to custom-markdown-anchors-and-content-cross---referencing. Jednak ze względu na sposób działania naszych tłumaczeń, za każdym razem, gdy odwołujemy się do nagłówka sekcji, musi on mieć niestandardową kotwicę.

MkDocs obsługuje renderowanie składni linków referencyjnych, która umożliwia tworzenie linków do różnych innych elementów dokumentacji przy użyciu zmodyfikowanego linku Markdown. Obejmuje to między innymi linkowanie do niestandardowych nagłówków Markdown i kotwic tekstowych.

Linki referencyjne MkDocs to wszelkie linki sformatowane w następujący sposób:

[Link text][link-target]

Wymagane są niestandardowe nagłówki i kotwice treści.

Każdy nagłówek lub sekcja treści, do której odwołuje się treść tekstowa za pomocą linku odniesienia MkDocs w dokumentacji BeeWare, musi mieć dołączoną niestandardową kotwicę. W przeciwnym razie istnieje ryzyko uszkodzenia linków podczas tłumaczenia treści nagłówka.

Jeśli chcesz utworzyć link do kotwicy nagłówkowej, musisz wygenerować niestandardową kotwicę dla wybranej treści. Ogólna składnia ustawiania niestandardowej kotwicy jest następująca:

# Header text { #anchor-name }

Na przykład dostosowanie kotwicy dla tej sekcji do custom-anchors można wykonać za pomocą następującego formatowania:

## Custom Markdown anchors { #custom-anchors }

Możesz również utworzyć kotwicę w treści ogólnej, w tym w tekście i blokach kodu. Poniższe formatowanie, z nowymi wierszami powyżej i poniżej, powinno zostać umieszczone powyżej treści, do której chcesz utworzyć link:

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

Po utworzeniu niestandardowych kotwic można utworzyć do nich linki w tym samym dokumencie lub w innych częściach dokumentacji.

Standardowy znacznik Markdown służy do tworzenia linków do kotwicy w tym samym pliku, która ma następujący format:

[Link text](#anchor-name)

Łącze do kotwicy w oddzielnym dokumencie wykorzystuje styl odnośnika MkDocs, który ma następujący format:

[Link text][anchor-name]

Linki do dokumentacji API

Linkowanie referencyjne MkDocs obsługuje również odsyłanie do dokumentacji API, w tym do udokumentowanych klas, metod lub atrybutów klas oraz konkretnych odniesień do dokumentacji zewnętrznej.

Istnieje wiele opcji łączenia się z udokumentowaną klasą, metodą klasy lub atrybutem, niezależnie od tego, czy łączymy się z tego samego pliku, czy z oddzielnego pliku. Podczas łączenia się z klasami itp. należy umieścić znaki backtick w pierwszym zestawie nawiasów kwadratowych, aby renderować nazwę jako kod wbudowany. Znaki backtick nie są konieczne tylko w przypadku używania niestandardowego tekstu, który nie powinien być renderowany jako kod wbudowany. Znaków backtick nie należy nigdy umieszczać w drugim zestawie nawiasów kwadratowych.

Łącze do klasy z wyświetleniem przestrzeni nazw ma następujący format:

[`module.ClassName`][]

Łącze do klasy, które wyświetla tylko nazwę klasy, ma następujący format:

[`ClassName`][module.ClassName]

Atrybuty są takie same jak powyżej, z uwzględnieniem nazwy atrybutu. Poniżej przedstawiono przestrzeń nazw:

[`module.ClassName.attributename`][]

Podobnie jak w przypadku klas, wyświetlanie samej nazwy atrybutu jest sformatowane w następujący sposób:

[`attributename`][module.ClassName.attributename]

Metody powinny być wyświetlane z () po przestrzeni nazw, dlatego należy je traktować inaczej niż atrybuty. Poniżej przedstawiono prawidłowy sposób tworzenia odnośnika do metody:

[`module.ClassName.methodname()`][module.ClassName.methodname]

Poniżej wyświetlane są tylko nazwy klas i metod. Wymaga to również dodania nawiasów po nazwie:

[`Classname.methodname()`][module.Classname.methodname]

Można utworzyć odnośnik do klasy, metody lub atrybutu, wyświetlając dowolny tekst, przy użyciu tej samej metody z odpowiednią przestrzenią nazw. W przypadku klasy formatowanie wygląda następująco:

[link text][module.ClassName]

Możliwe jest również bezpośrednie połączenie z dokumentacją rdzenia języka Python, a także dokumentacją biblioteki Pillow. Na przykład, aby połączyć się z dokumentacją dla int:

[`int`][]

Aby uzyskać link do dokumentacji Pillow Image:

[`PIL.Image.Image`][]

Wskazówki dotyczące bloków kodu

Podświetlanie języka i kodu

Możesz określić język kodu zawartego w bloku kodu, dodając nazwę języka po pierwszych trzech znakach backtick, bez spacji między nimi. Dzięki temu kod zostanie odpowiednio podświetlony po wyrenderowaniu. Na przykład, aby określić język Python, należy rozpocząć blok kodu od ```python.

Polecenia konsoli i przycisk kopiowania

Jeśli dodajesz polecenia konsoli lub polecenia z wynikami, oznacz je jako console lub doscon, w zależności od tego, czy opisujesz system operacyjny typu Unix (w tym macOS), czy Windows. Możesz dodać monit wyświetlany przez system operacyjny; po kliknięciu przycisku kopiowania skopiowane zostanie tylko polecenie. Na przykład, jeśli blok kodu zaczynasz od ```console, a następnie dodajesz następującą treść:

$ mkdir test
$ ls
test

Następnie kliknięcie przycisku kopiowania w bloku kodu spowoduje skopiowanie tylko poleceń, pomijając monity i wyniki. Pozwala to wskazać, że są to polecenia konsoli, jednocześnie umożliwiając użytkownikom efektywne korzystanie z przycisku kopiowania.

Podświetlanie określonych linii kodu

Możesz wyróżnić określone linie kodu. Na przykład, aby wyróżnić linię 2, dodaj spację po języku, a następnie {hl_lines="2"}. Twój blok kodu będzie więc zaczynał się od ```python {hl_lines="2"}. Wynik będzie następujący:

import toga
from toga.style.pack import COLUMN, ROW

Możesz zaznaczyć wiele różnych linii. Na przykład python {hl_lines="3 5 9"} zaznaczy linie 3, 5 i 9. Możesz również zaznaczyć zakres linii. Na przykład python {hl_lines="3-8"} zaznacza linie od 3 do 8. Możesz zaznaczyć wiele zakresów, na przykład python {hl_lines="9-18 23-44"}.

Elementy Markdown wymagające określonego formatowania

Ze względu na sposób generowania plików tłumaczeniowych ważne jest, aby w składni Markdown uwzględnić wymagane znaki nowej linii w przypadku ostrzeżeń, uwag, zakładek, dyrektyw Jinja, podpisów pod obrazkami, wyrównania itp.

Upomnienia i uwagi

Ostrzeżenia muszą być sformatowane w następujący sposób, z uwzględnieniem znaku nowej linii przed i po rozpoczęciu oraz zakończeniu ostrzeżenia:

Content above.

/// admonition | Title

Admonition text.

A second paragraph.

///

Content below.

Działa to w ten sam sposób w przypadku każdego obsługiwanego typu ostrzeżenia. Na przykład ostrzeżenia dotyczące notatek wymagają takiego samego formatowania i znaków nowej linii:

Content above.

/// note | Note title

Note text here.

///

Content below.

Wszystkie obsługiwane typy upomnień są dostępne do wykorzystania jako upomnienia.

Treść w zakładkach

Treść z zakładkami jest sformatowana w następujący sposób, z uwzględnieniem znaku nowej linii przed początkiem i po zakończeniu bloku treści:

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

Zakładka z zagnieżdżonym ostrzeżeniem byłaby sformatowana w następujący sposób, z wierszem nowym przed i po bloku treści:

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

Zwiń treść

Zwiń treść jest sformatowana w następujący sposób, z uwzględnieniem znaków nowej linii:

Content above.

/// details-note | Collapsed content title

Collapsed content.

///

Content below.

Wszystkie obsługiwane typy ostrzeżeń są dostępne do użycia z zawartością zwiniętą, jednak należy je zadeklarować jako details-admonitiontype. Tak więc blok zwinięty typu „uwaga” będzie miał postać details-note (jak pokazano powyżej), blok zwinięty typu „ostrzeżenie” będzie miał postać details-warning itd.

Dyrektywy Jinja

W dokumentacji znajduje się kilka funkcji, które wykorzystują dyrektywy Jinja w tekście. Wszystko, co wykorzystuje funkcje dyrektyw Jinja, musi być otoczone znakami nowej linii. Na przykład samouczek BeeWare zawiera warunki Jinja oparte na zmiennych, które określają, jakie ostrzeżenie ma być wyświetlane na stronie głównej. Są one sformatowane w następujący sposób:

Content above.



Content below.

Istnieje również składnia służąca do zastępowania symboli lub tekstu. Składnia ta jest zmienną ujętą w parę pasujących podwójnych nawiasów klamrowych i, jeśli znajduje się w osobnym wierszu, musi zawierać znak nowej linii przed i po niej.

Content above.

{{ variable }}

Content below.

Formatowanie obrazów

Obrazy mogą mieć ustawioną szerokość i mogą być wyrównane do lewej, prawej lub do środka (z zastrzeżeniem dotyczącym „wyśrodkowania”). Obrazy powinny zawsze zawierać znaczący tekst alternatywny dla celów dostępności.

Ustawienie szerokości 300px dla obrazu będzie wyglądało następująco:

![Image alt text](../path/to/image.png){ width="300px" }

Wyrównanie obrazu do lewej (lub prawej) strony będzie miało następujący format:

![Image alt text](../path/to/image.png){ align=left }

Dodanie podpisu do obrazu wymaga znaku nowej linii przed i po nim i jest sformatowane w następujący sposób:

Content above.

![Image alt text](/path/to/image.png)

/// caption

Caption content.

///

Content below.

Wyrównanie środka obrazu nie jest możliwe za pomocą atrybutu align. Rozwiązaniem jest dodanie pustego podpisu pod obrazem, co spowoduje jego wyśrodkowanie. Należy dodać znaki nowej linii między każdą sekcją oraz przed i po niej. Formatowanie wygląda następująco:

Content above.

![Image alt text](../path/to/image.png)

/// caption

///

Content below.

Wtyczki z określonym formatowaniem Markdown

Poniższe sekcje opisują, jak korzystać z wtyczek wymagających określonego formatowania Markdown.

Wykorzystanie fragmentów kodu do włączenia treści zewnętrznych

Szczegółowe informacje na temat dodawania treści zewnętrznych z pliku lokalnego lub adresu URL można znaleźć w dokumentacji rozszerzenia Snippets. Fragmenty powinny być używane, o ile dokument nie zawiera dyrektyw Jinja, które muszą zostać wykonane (wykonanie Jinja odbywa się równolegle z przetwarzaniem fragmentów, dlatego też żadna dyrektywa Jinja w pliku nie zostanie przetworzona). Rozszerzenie Snippets jest niezbędne, jeśli chcesz używać separatorów, które pozwalają na osobne włączenie określonych części pliku, np. dokument źródłowy jest podzielony na sekcje, które mają być wstawiane osobno.

Ważne uwagi:

  • Używamy -8<- jako identyfikatora fragmentów. Dokumentacja przedstawia kilka opcji; prosimy o stosowanie się do naszego stylu.
  • Pliki znalezione w udostępnianych treściach BeeWare Docs Tools są traktowane jako treści „lokalne”. Dlatego też należy używać tylko nazwy pliku, jak w -8<- "docs-style-guide.md", lub, jeśli treść znajduje się w podkatalogu, tylko katalogu i nazwy pliku, jak w -8<- "style/docs-style-guide.md".
  • Jeśli dodajesz treści zewnętrzne z pliku na GitHubie za pomocą adresu URL, musisz użyć adresu URL z surową treścią, bo inaczej cała strona internetowa zostanie wyświetlona tam, gdzie ją umieścisz.

Wykorzystanie makr do włączenia treści z BeeWare Docs Tools udostępnione treści

Możesz również dołączyć treści z katalogu treści udostępnianych przez narzędzia BeeWare Docs, korzystając z wtyczki Macros MkDocs. Metoda ta jest konieczna, jeśli dokument zawiera dyrektywy Jinja, które muszą zostać wykonane, i powinna być stosowana wyłącznie w tej sytuacji. Nie będzie działać w przypadku treści zewnętrznych udostępnianych za pośrednictwem adresu URL. Mechanizm zastępowania zmiennych Macros działa w połączeniu z tą metodą.

Istnieją opcje dodawania treści za pomocą makr:

  1. Użyj składni Jinja include, jeśli chcesz dołączyć dokument bez wprowadzania żadnych innych ręcznych zmian.

  2. Jeśli w dokumencie zastosowano składnię Jinja extends, należy użyć [składni Jinja (https://jinja.palletsprojects.com/en/stable/templates/#child-template)]block, która pozwala na nadpisanie lub dodanie określonych sekcji.

pyspelling

Korzystamy z modułu sprawdzania pisowni pyspelling. Jest on uruchamiany podczas kontroli lint.

Gdy pyspelling oznacza błędnie napisane słowo, w większości przypadków należy je poprawić w treści dokumentacji.

W rzadkich przypadkach, gdy program rozpozna słowo, które nie znajduje się w słowniku pyspelling, masz dwie możliwości:

  1. Jeśli jest to słowo, które prawdopodobnie będzie wielokrotnie używane, należy dodać je do dokumentu spelling_wordlist w katalogu docs, w porządku alfabetycznym.
  2. Jeśli jest to słowo, które prawdopodobnie nie zostanie ponownie użyte, można je ująć w tag <nospell> / </nospell>, a pyspelling zignoruje je w tekście.