Guida allo stile della documentazione di TensorFlow

migliori prassi

  • Concentrati sull'intento dell'utente e sul pubblico di riferimento.
  • Utilizza parole di uso comune e frasi brevi.
  • Utilizza una struttura delle frasi, una formulazione e un uso delle maiuscole coerenti.
  • Utilizza titoli ed elenchi per rendere i tuoi documenti più facili da consultare.
  • La guida di stile per la documentazione degli sviluppatori di Google è utile.

Sconto

Salvo alcune eccezioni, TensorFlow utilizza una sintassi Markdown simile a quella di GitHub Flavored Markdown (GFM). Questa sezione illustra le differenze tra la sintassi Markdown di GFM e quella utilizzata per la documentazione di TensorFlow.

Scrivi del codice

Menzioni inline del codice

Quando utilizzati nel testo, racchiudete i seguenti simboli tra `backticks` :

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

Blocchi di codice

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


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

Utilizza collegamenti relativi tra i file all'interno di un singolo repository GitHub. Includi 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 preferibile perché in questo modo i link su tensorflow.org , GitHub e Colab funzionano tutti. Inoltre, il lettore rimane sullo stesso sito quando clicca su un link.

Per i collegamenti a file non presenti nel repository corrente, utilizzare i collegamenti Markdown standard con l'URI completo. Se disponibile, è preferibile utilizzare l'URI di tensorflow.org .

Per collegarsi al codice sorgente, utilizzare un link che inizi con https://www.github.com/tensorflow/tensorflow/blob/master/ , seguito dal nome del file a partire dalla directory principale di GitHub.

Quando si crea un collegamento da tensorflow.org , includere un `` nel collegamento Markdown in modo che venga visualizzato il simbolo "collegamento esterno".

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

Non includere i parametri di query URI nel link:

  • Utilizzo: https://www.tensorflow.org/guide/data
  • Non: https://www.tensorflow.org/guide/data?hl=en

Immagini

I consigli nella sezione precedente si riferiscono ai link alle pagine. Le immagini vengono gestite in modo diverso.

In genere, è meglio non includere le immagini nel repository, ma aggiungere il team TensorFlow-Docs alla pull request e chiedere loro di ospitare le immagini su tensorflow.org . Questo contribuisce a mantenere ridotte le dimensioni del repository.

Se caricate immagini nel vostro repository, tenete presente che alcuni sistemi non gestiscono i percorsi relativi alle immagini. È preferibile utilizzare un URL completo che punti alla posizione finale dell'immagine su tensorflow.org .

I link API vengono convertiti al momento della pubblicazione del sito. Per creare un link alla pagina di riferimento API di un simbolo, racchiudere il percorso del simbolo tra apici inversi:

I percorsi completi sono leggermente preferiti, ad eccezione di quelli lunghi. I percorsi possono essere abbreviati omettendo i componenti iniziali. I percorsi parziali verranno convertiti in collegamenti se:

  • C'è almeno un . 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 . È possibile creare facilmente collegamenti a più sottoprogetti da un singolo file racchiudendo i nomi delle API tra apici inversi. Ad esempio:

Per i simboli con più alias di percorso, viene data una leggera preferenza al percorso che corrisponde alla pagina API su tensorflow.org . Tutti gli alias reindirizzeranno alla pagina corretta.

Matematica in Markdown

È possibile utilizzare MathJax all'interno di TensorFlow durante la modifica di file Markdown, ma si prega di tenere presente quanto segue:

  • MathJax viene visualizzato correttamente su tensorflow.org .
  • MathJax non viene visualizzato correttamente su GitHub.
  • Questa notazione può risultare scoraggiante per gli sviluppatori che non la conoscono.
  • Per garantire la coerenza, tensorflow.org segue le stesse regole di Jupyter/Colab.

Utilizzare $$ 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 \]

Racchiudere le espressioni MathJax inline tra $ ... $ :


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

Questo è un esempio di espressione MathJax inline: \( 2 \times 2 = 4 \)

Anche i delimitatori \\( ... \\) funzionano per le formule matematiche in linea, ma la forma $ a volte risulta più leggibile.

Stile in prosa

Se intendi scrivere o modificare parti sostanziali della documentazione narrativa, ti preghiamo di leggere la Guida di stile per la documentazione degli sviluppatori di Google .

Principi di buon stile

  • Controlla l'ortografia e la grammatica dei tuoi contributi. La maggior parte degli editor include un correttore ortografico o offre un plugin per la correzione ortografica. Puoi anche incollare il testo in un documento Google o in un altro software di elaborazione testi per un controllo ortografico e grammaticale più accurato.
  • Utilizza un tono informale e amichevole. Scrivi la documentazione di TensorFlow come se stessi parlando con un'altra persona a tu per tu. Mantieni un tono di supporto nell'articolo.
  • Evitate esclusioni di responsabilità, opinioni e giudizi di valore. Parole come "facilmente", "solo" e "semplice" sono cariche di presupposti. Qualcosa può sembrare facile a voi, ma essere difficile per un'altra persona. Cercate di evitarle quando possibile.
  • Utilizza frasi semplici e concise, senza gergo complicato. Frasi composte, sequenze di proposizioni e idiomi specifici di un determinato luogo possono rendere il testo difficile da comprendere e tradurre. Se una frase può essere divisa in due, è consigliabile farlo. Evita i punti e virgola. Utilizza elenchi puntati quando opportuno.
  • Fornisci il contesto necessario. Non usare abbreviazioni senza spiegarne il significato. Non menzionare progetti non basati su TensorFlow senza fornire i relativi link. Spiega perché il codice è scritto in quel modo.

Guida all'uso

Operazioni

Nei file Markdown, usa # ⇒ invece di un singolo segno di uguale quando vuoi mostrare il valore restituito da un'operazione.

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

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

Nella documentazione di riferimento delle API si preferisce utilizzare doctest per mostrare i risultati.

Tensori

Quando si parla di un tensore in generale, non si scrive la parola "tensore" con la maiuscola. Quando invece ci si riferisce allo specifico oggetto fornito a un'operazione o restituito da essa, allora si deve scrivere la parola "tensore" con la maiuscola e racchiuderla tra apici inversi, perché ci si riferisce a un oggetto Tensor .

Non usare il termine "tensori " (plurale) per descrivere più oggetti Tensor a meno che tu non ti riferisca effettivamente a un singolo oggetto Tensors . Piuttosto, usa l'espressione "un elenco (o una collezione) di oggetti Tensor ".

Utilizza il termine "forma" per descrivere gli assi di un tensore e indica la forma tra parentesi quadre con apici inversi. Ad 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 indicato sopra, è preferibile utilizzare "asse" o "indice" anziché "dimensione" quando si parla degli elementi della forma di un Tensor . Altrimenti è facile confondere "dimensione" con la dimensione di uno spazio vettoriale. Un "vettore tridimensionale" ha un singolo asse di lunghezza 3.