Guida allo stile della documentazione di TensorFlow

Migliori pratiche

  • Concentrati sulle intenzioni e sul pubblico dell'utente.
  • Usa parole di tutti i giorni e mantieni le frasi brevi.
  • Utilizza una costruzione, una formulazione e una capitalizzazione della frase coerenti.
  • Utilizza intestazioni ed elenchi per semplificare la scansione dei tuoi documenti.
  • La Guida allo stile di Google Developer Docs è utile.

Ribasso

Con poche eccezioni, TensorFlow utilizza una sintassi Markdown simile a GitHub Flavored Markdown (GFM). Questa sezione spiega le differenze tra la sintassi GFM Markdown e Markdown utilizzata per la documentazione di TensorFlow.

Scrivere di codice

Menzioni in linea del codice

Inserisci `backticks` attorno ai seguenti simboli quando vengono utilizzati nel testo:

  • Nomi degli argomenti: `input` , `x` , `tensor`
  • Nomi dei tensori restituiti: `output` , `idx` , `out`
  • Tipi di dati: `int32` , `float` , `uint8`
  • Altri riferimenti ai nomi delle operazioni nel testo: `list_diff()` , `shuffle()`
  • Nomi delle classi: `tf.Tensor` , `Strategy`
  • Nome file: `image_ops.py` , `/path_to_dir/file_name`
  • Espressioni o condizioni matematiche: `-1-input.dims() <= dim <= input.dims()`

Blocchi di codice

Utilizza tre backtick per aprire e chiudere un blocco di codice. Facoltativamente, specificare il linguaggio di programmazione dopo il primo gruppo di backtick, ad esempio:


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

Utilizza collegamenti relativi tra file in un singolo repository GitHub. Includere l'estensione del file.

Ad esempio, il file che stai leggendo proviene dal repository https://github.com/tensorflow/docs . Pertanto, può utilizzare percorsi relativi per collegarsi ad altri file nello stesso repository in questo modo:

Questo è l'approccio preferito perché in questo modo funzionano tutti i collegamenti su tensorflow.org , GitHub e Colab . Inoltre, il lettore rimane nello stesso sito quando fa clic su un collegamento.

Per i collegamenti a file che non si trovano nel repository corrente, utilizzare collegamenti Markdown standard con l'URI completo. Preferisci collegarti all'URI tensorflow.org se disponibile.

Per collegarsi al codice sorgente, utilizzare un collegamento che inizia con https://www.github.com/tensorflow/tensorflow/blob/master/ , seguito dal nome del file che inizia nella radice GitHub.

Quando ti colleghi a tensorflow.org , includi un `` sul collegamento Markdown in modo che venga mostrato il simbolo del "collegamento esterno".

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

Non includere parametri di query URI nel collegamento:

  • Utilizzo: <a href="https://www.tensorflow.org/guide/data">https://www.tensorflow.org/guide/data</a>
  • Non: <a href="https://www.tensorflow.org/guide/data?hl=en">https://www.tensorflow.org/guide/data?hl=en</a>

Immagini

Il consiglio nella sezione precedente riguarda i collegamenti alle pagine. Le immagini vengono gestite in modo diverso.

In genere, non dovresti archiviare le immagini, ma aggiungere invece il team TensorFlow-Docs al tuo PR e chiedere loro di ospitare le immagini su tensorflow.org . Ciò aiuta a ridurre le dimensioni del repository.

Se invii immagini al tuo repository, tieni presente che alcuni sistemi non gestiscono i percorsi relativi alle immagini. Preferisci utilizzare un URL completo che punti all'eventuale posizione dell'immagine su tensorflow.org .

I collegamenti API vengono convertiti quando il sito viene pubblicato. Per collegarsi alla pagina di riferimento dell'API di un simbolo, racchiudere il percorso del simbolo tra apici inversi:

I percorsi completi sono leggermente preferiti, ad eccezione dei percorsi lunghi. I percorsi possono essere abbreviati eliminando i componenti principali del percorso. I percorsi parziali verranno convertiti in collegamenti se:

  • Ce n'è almeno uno . nel percorso, e
  • Il percorso parziale è unico all'interno del progetto.

I percorsi API sono collegati per ogni progetto con un'API Python pubblicata su tensorflow.org . Puoi facilmente collegarti a più sottoprogetti da un singolo file racchiudendo i nomi API con apici inversi. Per esempio:

Per i simboli con più alias di percorso esiste una leggera preferenza per il percorso che corrisponde alla pagina API su tensorflow.org . Tutti gli alias verranno reindirizzati alla pagina corretta.

Matematica in Markdown

Puoi utilizzare MathJax all'interno di TensorFlow durante la modifica dei file Markdown, ma tieni presente quanto segue:

  • MathJax viene visualizzato correttamente su tensorflow.org .
  • MathJax non viene visualizzato correttamente su GitHub.
  • Questa notazione può essere scoraggiante per gli sviluppatori non familiari.
  • Per coerenza tensorflow.org segue le stesse regole di Jupyter/Colab.

Usa $$ attorno a un blocco di 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 \]

Racchiudi le espressioni MathJax in linea con $ ... $ :


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

Questo è un esempio di un'espressione MathJax in linea: \( 2 \times 2 = 4 \)

I delimitatori \\( ... \\) funzionano anche per la matematica in linea, ma la forma $ a volte è più leggibile.

Stile di prosa

Se hai intenzione di scrivere o modificare parti sostanziali della documentazione narrativa, leggi la Guida allo stile della documentazione per gli sviluppatori di Google .

Principi di buon stile

  • Controlla l'ortografia e la grammatica nei tuoi contributi. La maggior parte degli editor include un controllo ortografico o dispone di un plug-in per il controllo ortografico. Puoi anche incollare il testo in un documento Google o in un altro software per documenti per un controllo ortografico e grammaticale più approfondito.
  • Usa una voce informale e amichevole. Scrivi la documentazione di TensorFlow come una conversazione, come se stessi parlando faccia a faccia con un'altra persona. Usa un tono di sostegno nell'articolo.
  • Evita dichiarazioni di non responsabilità, opinioni e giudizi di valore. Parole come "facilmente", "giusto" e "semplice" sono piene di supposizioni. Qualcosa potrebbe sembrare facile per te, ma essere difficile per un'altra persona. Cerca di evitarli quando possibile.
  • Usa frasi semplici e mirate senza un gergo complicato. Frasi composte, catene di proposizioni e modi di dire specifici della posizione possono rendere il testo difficile da comprendere e tradurre. Se una frase può essere divisa in due, probabilmente dovrebbe farlo. Evitare il punto e virgola. Utilizza gli elenchi puntati quando appropriato.
  • Fornire contesto. Non usare abbreviazioni senza spiegarle. Non menzionare progetti non TensorFlow senza collegarsi ad essi. Spiega perché il codice è scritto così com'è.

Guida all'uso

Op

Nei file markdown, usa # ⇒ invece di un singolo segno di uguale quando vuoi mostrare cosa restituisce un'operazione.

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

Nei taccuini, visualizza il risultato invece di aggiungere un commento (se l'ultima espressione in una cella del taccuino non è assegnata a una variabile, viene visualizzata automaticamente).

Nei documenti di riferimento API preferiscono utilizzare doctest per mostrare i risultati.

Tensori

Quando parli di un tensore in generale, non scrivere la parola tensore in maiuscolo. Quando parli dell'oggetto specifico fornito o restituito da un'operazione, dovresti scrivere in maiuscolo la parola Tensore e aggiungere apici inversi attorno ad essa perché stai parlando di un oggetto Tensor .

Non usare la parola Tensori (plurale) per descrivere più oggetti Tensor a meno che non si stia realmente parlando di un oggetto Tensors . Invece, dì "un elenco (o raccolta) di oggetti Tensor ".

Usa la parola forma per dettagliare gli assi di un tensore e mostra la forma tra parentesi quadre con apici inversi. Per esempio:


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

Come sopra, preferisci "asse" o "indice" a "dimensione" quando parli degli elementi della forma di un Tensor . Altrimenti è facile confondere la "dimensione" con la dimensione di uno spazio vettoriale. Un "vettore tridimensionale" ha un unico asse di lunghezza 3.