Przewodnik po stylu dokumentacji TensorFlow

Najlepsze praktyki

  • Skoncentruj się na intencjach użytkownika i odbiorcach.
  • Używaj słów codziennego użytku 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ć skanowanie dokumentów.
  • Pomocny jest Przewodnik po stylu Dokumentów Google dla programistów .

Obniżka cen

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

Napisz o kodzie

Wbudowane wzmianki o kodzie

Jeśli są używane w tekście, umieść `backticks` wokół następujących symboli:

  • Nazwy argumentów: `input` , `x` , `tensor`
  • Zwracane nazwy tensorów: `output` , `idx` , `out`
  • Typy danych: `int32` , `float` , `uint8`
  • Inne nazwy operacji odnoszą się do tekstu: `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 zwrotów, aby otworzyć i zamknąć blok kodu. Opcjonalnie po pierwszej grupie znaczników podaj język programowania, na przykład:


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

Użyj 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ą wszystkie linki na tensorflow.org , GitHub i Colab . Ponadto czytelnik pozostaje w tej samej witrynie po kliknięciu łącza.

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

Aby utworzyć łącze do kodu źródłowego, użyj łącza rozpoczynającego się od https://www.github.com/tensorflow/tensorflow/blob/master/ , po którym następuje nazwa pliku rozpoczynająca się od katalogu głównego GitHub.

Łącząc się z tensorflow.org , umieść `` na łączu Markdown, aby pojawił się symbol „linku zewnętrznego”.

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

Nie podawaj 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>

Obrazy

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

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

Jeśli przesyłasz obrazy do swojego 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 .

Łącza API są konwertowane w momencie publikacji witryny. Aby utworzyć łącze do strony referencyjnej API symbolu, ujmij ścieżkę symbolu znakami wstecznymi:

Pełne ścieżki są nieco preferowane, z wyjątkiem długich ścieżek. Ścieżki można skracać, usuwając wiodące komponenty ścieżki. Częściowe ścieżki zostaną przekonwertowane na łącza, jeżeli:

  • Jest przynajmniej jeden . na ścieżce i
  • Ścieżka częściowa jest unikalna w obrębie projektu.

Ścieżki API są powiązane dla każdego projektu z API Pythona opublikowanym na tensorflow.org . Możesz łatwo połączyć wiele podprojektów z jednego pliku, zawijając nazwy API za pomocą backticków. Na przykład:

W przypadku symboli z wieloma aliasami ścieżek preferowana jest ścieżka zgodna ze stroną API na tensorflow.org . Wszystkie aliasy przekierują na właściwą stronę.

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 GitHubie.
  • Ta notacja może zniechęcić nieznanych programistów.
  • Aby zachować spójność, tensorflow.org stosuje te same zasady, 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 $

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

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

Styl prozatorski

Jeśli zamierzasz pisać lub edytować znaczną część dokumentacji narracyjnej, przeczytaj Przewodnik po stylu dokumentacji Google Developer .

Zasady dobrego stylu

  • Sprawdź pisownię i gramatykę w swoich wpisach. Większość edytorów zawiera moduł sprawdzania pisowni lub posiada dostępną wtyczkę do sprawdzania pisowni. Możesz także wkleić tekst do Dokumentu Google lub innego oprogramowania do obsługi dokumentów, aby dokładniej sprawdzić pisownię i gramatykę.
  • 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 zastrzeżeń, opinii i ocen wartościujących. Słowa takie jak „łatwo”, „tylko” i „proste” są obciążone założeniami. Coś może wydawać się łatwe dla ciebie, ale dla innej osoby może być trudne. Staraj się ich unikać, jeśli to możliwe.
  • Używaj prostych, rzeczowych zdań, bez skomplikowanego żargonu. Zdania złożone, łańcuchy zdań i idiomy specyficzne dla lokalizacji mogą sprawić, że tekst będzie trudny do zrozumienia i przetłumaczenia. Jeśli zdanie można podzielić na dwie części, prawdopodobnie powinno. Unikaj średników. W stosownych przypadkach używaj list punktowanych.
  • Podaj kontekst. Nie używaj skrótów bez ich wyjaśnienia. Nie wspominaj o projektach innych niż TensorFlow bez linkowania do nich. Wyjaśnij, dlaczego kod jest napisany w taki, a nie inny sposób.

Przewodnik użytkowania

Operacje

W plikach przeceny użyj # ⇒ zamiast pojedynczego znaku równości, jeśli 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 wolą używać doctest do wyświetlania wyników.

Tensory

Kiedy mówisz ogólnie o tensorze, nie pisz słowa tensor wielką literą. Kiedy mówisz o konkretnym obiekcie dostarczanym lub zwracanym z operacji, powinieneś napisać wielką literę słowo Tensor i dodać wokół niego kreski, ponieważ mówisz o obiekcie Tensor .

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

Użyj słowa „ kształt” , aby szczegółowo opisać osie tensora i pokaż kształt w nawiasach kwadratowych z odstępami. 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 wyżej, jeśli mówimy o elementach kształtu Tensor , preferuj „oś” lub „indeks” zamiast „wymiaru”. W przeciwnym razie łatwo pomylić „wymiar” z wymiarem przestrzeni wektorowej. „Wektor trójwymiarowy” ma pojedynczą oś o długości 3.