Przewodnik po stylu dokumentacji TensorFlow

Najlepsze praktyki

• Skoncentruj się na zamiarach użytkownika i odbiorcach.
• Używaj codziennych słów i używaj krótkich zdań.
• Używaj spójnej konstrukcji zdań, sformułowań i wielkich liter.
• Używaj nagłówków i list, aby ułatwić sobie skanowanie dokumentów.
• Pomocny jest przewodnik po stylach Dokumentów Google dla programistów .

Obniżka cen

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

Napisz o kodzie

Wzmianki o kodzie w tekście

Umieść `backticks` wokół następujących symboli, gdy są one używane w tekście:

• Nazwy argumentów: `input` , `x` 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 lub warunki matematyczne: `-1-input.dims() <= dim <= input.dims()`

Bloki kodu

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

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

Linki w Markdown i notatnikach

Linki między plikami w repozytorium

Używaj względnych łączy między plikami w jednym repozytorium GitHub. Dołącz rozszerzenie pliku.

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

• [Basics](../../guide/basics.ipynb) tworzy podstawy .

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

Linki zewnętrzne

W przypadku łączy do plików, które nie znajdują się w bieżącym repozytorium, użyj standardowych łączy Markdown z pełnym identyfikatorem URI. Preferuj link do identyfikatora URI tensorflow.org , jeśli jest dostępny.

Aby utworzyć link do kodu źródłowego, użyj linku 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.

Gdy łączysz się z tensorflow.org , dołącz {:.external} na łączu Markdown, aby wyświetlić symbol „łącza zewnętrznego”.

• [GitHub](https://github.com/tensorflow/docs){:.external} tworzy GitHub

Nie dołączaj parametrów zapytania URI w łączu:

• Użyj: <a href="https://www.tensorflow.org/guide/data">https://www.tensorflow.org/guide/data</a>
• Nie: <a href="https://www.tensorflow.org/guide/data?hl=en">https://www.tensorflow.org/guide/data?hl=en</a>

Zdjęcia

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

Ogólnie rzecz biorąc, nie powinieneś ewidencjonować obrazów, zamiast tego dodać zespół TensorFlow-Docs do swojego PR i poprosić go o udostępnienie obrazów na tensorflow.org . Pomaga to zmniejszyć rozmiar repozytorium.

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

Linki do dokumentacji API

Linki API są konwertowane, gdy witryna jest publikowana. Aby utworzyć link do strony referencyjnej interfejsu API symbolu, umieść ścieżkę symbolu w backtickach:

• `tf.data.Dataset` tworzy tf.data.Dataset

Pełne ścieżki są nieco preferowane, z wyjątkiem długich ścieżek. Ścieżki można skrócić, upuszczając wiodące komponenty ścieżek. Ścieżki częściowe zostaną przekonwertowane na łącza, jeśli:

• Jest co najmniej jeden . na ścieżce i
• Ścieżka częściowa jest unikalna w ramach projektu.

Ścieżki API są połączone dla każdego projektu za pomocą API Pythona opublikowanego na tensorflow.org . Możesz łatwo połączyć się z wieloma podprojektami z jednego pliku, umieszczając nazwy API w backtickach. 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, która pasuje do strony API na tensorflow.org . Wszystkie aliasy przekierowują do właściwej strony.

Matematyka w Markdown

Możesz używać MathJax w TensorFlow podczas edycji plików Markdown, ale pamiętaj, że:

• MathJax poprawnie renderuje się na tensorflow.org .
• MathJax nie renderuje się poprawnie na GitHub.
• Ta notacja może zniechęcać nieznanych programistów.
• Dla spójności tensorflow.org przestrzega 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 wbudowane wyrażenia MathJax za pomocą $ ... $ :

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

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

Ograniczniki \\( ... \\) działają również w przypadku matematyki wbudowanej, ale formularz $ jest czasami bardziej czytelny.

Styl prozy

Jeśli zamierzasz pisać lub edytować istotne fragmenty dokumentacji opisowej, zapoznaj się z Przewodnikiem po stylu dokumentacji dla programistów Google .

Zasady dobrego stylu

• Sprawdź pisownię i gramatykę w swoich wypowiedziach. Większość edytorów zawiera moduł sprawdzania pisowni lub ma dostępną wtyczkę do sprawdzania pisowni. Możesz także wkleić swój tekst do Dokumentów Google lub innego oprogramowania do obsługi dokumentów, aby uzyskać bardziej niezawodne sprawdzanie pisowni i gramatyki.
• Używaj swobodnego i przyjaznego głosu. Pisz dokumentację TensorFlow jak rozmowę — tak, jakbyś rozmawiał z inną osobą w cztery oczy. Użyj wspierającego tonu w artykule.

• Unikaj oświadczeń, opinii i ocen wartościujących. Słowa takie jak „łatwo”, „tylko” i „proste” są obciążone założeniami. Coś może ci się wydawać łatwe, ale może być trudne dla innej osoby. Staraj się ich unikać, gdy tylko jest to możliwe.
• Używaj prostych, konkretnych zdań bez skomplikowanego żargonu. Zdania złożone, łańcuchy klauzul i idiomy specyficzne dla lokalizacji mogą utrudniać zrozumienie i przetłumaczenie tekstu. Jeśli zdanie można podzielić na dwie części, prawdopodobnie powinno. Unikaj średników. W razie potrzeby używaj list punktowanych.
• Podaj kontekst. Nie używaj skrótów bez ich wyjaśnienia. Nie wspominaj o projektach innych niż TensorFlow bez łączenia się z nimi. Wyjaśnij, dlaczego kod jest napisany tak, jak jest.

Przewodnik użytkowania

Ops

W plikach markdown użyj # ⇒ 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, jest wyświetlane automatycznie).

W dokumentacji referencyjnej API preferuje się używanie doctest do wyświetlania wyników.

Tensory

Kiedy mówisz ogólnie o tensorze, nie używaj wielkiej litery tensor . Kiedy mówisz o konkretnym obiekcie, który został dostarczony lub zwrócony z operacji, powinieneś pisać słowo Tensor z dużej litery i dodać wokół niego znaki odwrotne, ponieważ mówisz o obiekcie Tensor .

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

Użyj kształtu słowa, aby wyszczególnić osie tensora i pokaż kształt w nawiasach kwadratowych z zaznaczeniem. 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, wolą „oś” lub „indeks” niż „wymiar”, kiedy mówimy 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.