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 nomi di operazioni fanno riferimento 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 apice inverso, 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 {:.external} sul collegamento Markdown in modo che venga mostrato il simbolo del "collegamento esterno".

  • [GitHub](https://github.com/tensorflow/docs){:.external} 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 indirizzi 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 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 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 disclaimer, 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 in maiuscolo la parola tensore . 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.