Przewodnik po stylu dokumentacji TensorFlow

Najlepsze praktyki

• Skoncentruj się na intencjach użytkownika i odbiorcach.
• Używaj codziennych słów i staraj się, aby zdania były krótkie.
• Stosuj spójną konstrukcję zdań, słownictwo i kapitalizację.
• Używaj nagłówków i list, aby ułatwić przeglądanie dokumentów.
• Przydatny będzie przewodnik stylistyczny Google Developer Docs .

Obniżka cen

Z kilkoma wyjątkami, TensorFlow używa składni Markdown podobnej do GitHub Flavored Markdown (GFM). W tej sekcji wyjaśniono różnice między składnią Markdown GFM a składnią Markdown używaną w dokumentacji TensorFlow.

Napisz o kodzie

Wzmianki o kodzie w tekście

W tekście należy używać znaku `backticks` przy następujących symbolach:

• Nazwy argumentów: `input` , `x` , `tensor`
• Zwrócone nazwy tensorów: `output` , `idx` , `out`
• Typy danych: `int32` , `float` , `uint8`
• Inne nazwy operacji odwołują się w tekście: `list_diff()` , `shuffle()`
• Nazwy klas: `tf.Tensor` , `Strategy`
• Nazwa pliku: `image_ops.py` , `/path_to_dir/file_name`
• Wyrażenia matematyczne lub warunki: `-1-input.dims() <= dim <= input.dims()`

Bloki kodu

Użyj trzech znaków odwrotnego apostrofu, aby otworzyć i zamknąć blok kodu. Opcjonalnie, po pierwszej grupie znaków odwrotnego apostrofu określ język programowania, na przykład:

```python
# some python code here
```

Linki w Markdown i notatnikach

Linki między plikami w repozytorium

Używaj linków względnych między plikami w jednym repozytorium GitHub. Uwzględnij rozszerzenie pliku.

Na przykład plik, który czytasz, pochodzi z repozytorium https://github.com/tensorflow/docs . Dlatego może używać ścieżek względnych do linkowania do innych plików w tym samym repozytorium, w następujący sposób:

• [Basics](../../guide/basics.ipynb) generuje Podstawy .

To preferowane podejście, ponieważ w ten sposób linki na tensorflow.org , GitHub i Colab działają. Ponadto, czytelnik pozostaje na tej samej stronie po kliknięciu linku.

Linki zewnętrzne

W przypadku linków do plików, których nie ma w bieżącym repozytorium, należy używać standardowych linków Markdown z pełnym URI. Najlepiej linkować do URI tensorflow.org, jeśli jest dostępny.

Aby połączyć się z kodem źródłowym, użyj łącza zaczynającego się od https://www.github.com/tensorflow/tensorflow/blob/master/ , po którym następuje nazwa pliku zaczynająca się od katalogu głównego GitHub.

Przy linkowaniu do tensorflow.org należy umieścić symbol `` przy linku Markdown, aby widoczny był symbol „linku zewnętrznego”.

• [GitHub](https://github.com/tensorflow/docs) generuje GitHub

Nie należy uwzględniać parametrów zapytania URI w linku:

• Użyj: https://www.tensorflow.org/guide/data
• Nie: https://www.tensorflow.org/guide/data?hl=en

Obrazy

Porady w poprzedniej sekcji dotyczą linków do stron. Obrazy są obsługiwane inaczej.

Generalnie nie należy rejestrować obrazów, a zamiast tego dodać zespół TensorFlow-Docs do swojego PR i poprosić o hostowanie obrazów na tensorflow.org . Pomaga to ograniczyć rozmiar repozytorium.

Jeśli przesyłasz obrazy do swojego repozytorium, pamiętaj, że niektóre systemy nie obsługują ścieżek względnych do obrazów. Lepiej użyć pełnego adresu URL wskazującego docelową lokalizację obrazu na tensorflow.org .

Linki do dokumentacji API

Linki API są konwertowane podczas publikacji witryny. Aby utworzyć link do strony referencyjnej API symbolu, należy umieścić ścieżkę symbolu w odwrotnym apostrofie:

• `tf.data.Dataset` generuje tf.data.Dataset

Pełne ścieżki są nieco preferowane, z wyjątkiem ścieżek długich. Ścieżki można skrócić, usuwając początkowe elementy ścieżki. Częściowe ścieżki zostaną przekształcone w linki, jeśli:

• Na ścieżce znajduje się co najmniej jeden znak . i
• Ta częściowa ścieżka jest unikatowa w ramach projektu.

Ścieżki API są powiązane dla każdego projektu z API Pythona opublikowanym na stronie tensorflow.org . Można łatwo linkować do wielu podprojektów z jednego pliku, umieszczając nazwy API w odwrotnych apostrofach. Na przykład:

• `tf.metrics` , `tf_agents.metrics` , `text.metrics` generuje: tf.metrics , tf_agents.metrics , text.metrics .

W przypadku symboli z wieloma aliasami ścieżek istnieje niewielka preferencja dla ścieżki odpowiadającej stronie API na tensorflow.org . Wszystkie aliasy będą przekierowywać do właściwej strony.

Matematyka w Markdown

Możesz używać MathJax w TensorFlow podczas edycji plików Markdown, ale pamiętaj o następujących kwestiach:

• MathJax renderuje się poprawnie na tensorflow.org .
• MathJax nie renderuje się poprawnie w serwisie GitHub.
• Taka notacja może być zniechęcająca dla niezaznajomionych z tematem programistów.
• Aby zapewnić spójność, tensorflow.org stosuje się do tych samych zasad co Jupyter/Colab.

Użyj $$ wokół bloku MathJax:

$$
E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2
$$

\[ E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2 \]

Zawijaj wyrażenia MathJax za pomocą $ ... $ :

This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $

Oto przykład wbudowanego wyrażenia MathJax: \( 2 \times 2 = 4 \)

Rozdzielacze \\( ... \\) działają również w przypadku obliczeń inline, ale forma $ jest czasami bardziej czytelna.

Styl prozy

Jeśli zamierzasz napisać lub edytować znaczną część dokumentacji narracyjnej, zapoznaj się z Przewodnikiem po stylu dokumentacji programistycznej Google .

Zasady dobrego stylu

• Sprawdź pisownię i gramatykę w swoich tekstach. Większość edytorów posiada moduł sprawdzania pisowni lub udostępnia wtyczkę do sprawdzania pisowni. Możesz również wkleić tekst do Dokumentów Google lub innego oprogramowania do obsługi dokumentów, aby uzyskać dokładniejsze sprawdzenie pisowni i gramatyki.
• Używaj swobodnego i przyjaznego tonu. Pisz dokumentację TensorFlow jak rozmowę – tak, jakbyś rozmawiał z kimś sam na sam. W artykule stosuj wspierający ton.

• Unikaj zastrzeżeń, opinii i osądów wartościujących. Słowa takie jak „łatwo”, „po prostu” i „proste” są pełne założeń. Coś może wydawać się łatwe dla Ciebie, ale dla innej osoby może być trudne. Staraj się ich unikać, kiedy tylko to możliwe.
• Używaj prostych, konkretnych zdań, bez skomplikowanego żargonu. Zdania złożone, ciągi zdań i idiomy specyficzne dla danego miejsca mogą utrudniać zrozumienie i tłumaczenie tekstu. Jeśli zdanie można podzielić na dwie części, prawdopodobnie należy to zrobić. Unikaj średników. Używaj wypunktowań, gdy jest to konieczne.
• Podaj kontekst. Nie używaj skrótów bez wyjaśnienia. Nie wspominaj o projektach spoza TensorFlow bez linkowania do nich. Wyjaśnij, dlaczego kod jest napisany w taki, a nie inny sposób.

Instrukcja użytkowania

Operacje

W plikach markdown używaj # ⇒ zamiast pojedynczego znaku równości, gdy chcesz pokazać, co zwraca operacja.

# 'input' is a tensor of shape [2, 3, 5]
tf.expand_dims(input, 0)  # ⇒ [1, 2, 3, 5]

W notatnikach wyświetl wynik zamiast dodawać komentarz (jeśli ostatnie wyrażenie w komórce notatnika nie jest przypisane do zmiennej, zostanie ono automatycznie wyświetlone).

W dokumentach referencyjnych API do wyświetlania wyników preferowany jest tryb doctest .

Tensory

Mówiąc ogólnie o tensorze, nie pisz słowa tensor wielką literą. Mówiąc o konkretnym obiekcie, który jest dostarczany do lub zwracany przez operację, pisz słowo Tensor wielką literą i dodaj odwrotny apostrof, ponieważ mówimy o obiekcie Tensor .

Nie używaj słowa „Tensors” (liczba mnoga) do opisywania wielu obiektów Tensor , chyba że faktycznie mówisz o obiekcie Tensors . Zamiast tego powiedz „lista (lub kolekcja) obiektów Tensor ”.

Użyj słowa „ kształt” , aby szczegółowo opisać osie tensora, i pokaż kształt w nawiasach kwadratowych z apostrofami. Na przykład:

If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.

Jak powyżej, lepiej używać „osi” lub „indeksu” niż „wymiaru”, mówiąc o elementach kształtu Tensor . W przeciwnym razie łatwo pomylić „wymiar” z wymiarem przestrzeni wektorowej. „Wektor trójwymiarowy” ma pojedynczą oś o długości 3.