Guida allo stile della documentazione di TensorFlow

Migliori pratiche

  • Concentrati sull'intento dell'utente e sul pubblico.
  • Usa le parole di tutti i giorni e mantieni le frasi brevi.
  • Usa la costruzione delle frasi, la formulazione e l'uso delle maiuscole coerenti.
  • Utilizza intestazioni ed elenchi per semplificare la scansione dei tuoi documenti.
  • La Guida allo stile di Documenti per sviluppatori Google è 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 il Markdown utilizzato per la documentazione di TensorFlow.

Scrivi sul codice

Menzioni in linea di codice

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

  • Nomi degli argomenti: `input` , `x` , `tensor`
  • Nomi dei tensori restituiti: `output` , `idx` , `out` 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

Usa 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
```

Usa i collegamenti relativi tra i file in un unico repository GitHub. Includere l'estensione del file.

Ad esempio, questo 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:

  • [Basics](../../guide/basics.ipynb) produce Nozioni di base .

Questo è l'approccio preferito perché in questo modo i collegamenti su tensorflow.org , GitHub e Colab funzionano tutti. 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 i collegamenti Markdown standard con l'URI completo. Preferisci collegarti all'URI tensorflow.org se è disponibile.

Per collegarti al codice sorgente, usa un collegamento che inizia con https://www.github.com/tensorflow/tensorflow/blob/master/ , seguito dal nome del file che inizia alla radice di GitHub.

Quando si effettua il collegamento da tensorflow.org , includere un {:.external} nel collegamento Markdown in modo che venga visualizzato il simbolo del "collegamento esterno".

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

Non includere i parametri di query URI nel collegamento:

  • Usa: <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 e invece aggiungere il team TensorFlow-Docs al tuo PR e chiedere loro di ospitare le immagini su tensorflow.org . Questo aiuta a ridurre le dimensioni del tuo repository.

Se invii immagini al tuo repository, tieni presente che alcuni sistemi non gestiscono 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 creare un collegamento alla pagina di riferimento dell'API di un simbolo, racchiudere il percorso del simbolo nei backtick:

I percorsi completi sono leggermente preferiti ad eccezione dei percorsi lunghi. I percorsi possono essere abbreviati eliminando i componenti del percorso iniziale. 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 delle API con i backtick. Per esempio:

Per i simboli con più alias di percorso c'è una leggera preferenza per il percorso che corrisponde alla pagina API su tensorflow.org . Tutti gli alias reindirizzeranno 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 esegue correttamente il rendering su tensorflow.org .
  • MathJax non esegue correttamente il rendering su GitHub.
  • Questa notazione può essere scoraggiante per gli sviluppatori sconosciuti.
  • Per coerenza tensorflow.org segue le stesse regole di Jupyter/Colab.

Usa $$ intorno a un isolato 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 \]

Avvolgi 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 inline: \( 2 \times 2 = 4 \)

\\( ... \\) i delimitatori funzionano anche per la matematica inline, ma il modulo $ a volte è più leggibile.

Stile in prosa

Se intendi 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 correttore ortografico o dispone di un plug-in per il controllo ortografico disponibile. Puoi anche incollare il testo in un documento Google o in un altro software per documenti per un controllo ortografico e grammaticale più affidabile.
  • Usa una voce disinvolta e amichevole. Scrivi la documentazione di TensorFlow come una conversazione, come se stessi parlando con un'altra persona uno contro uno. Usa un tono di supporto nell'articolo.
  • Evita disclaimer, opinioni e giudizi di valore. Parole come "facilmente", "giusto" e "semplice" sono cariche di presupposti. Qualcosa potrebbe sembrare facile per te, ma essere difficile per un'altra persona. Cerca di evitarli quando possibile.
  • Usa frasi semplici e puntuali senza un gergo complicato. Frasi composte, catene di clausole e modi di dire specifici della posizione possono rendere difficile la comprensione e la traduzione del testo. Se una frase può essere divisa in due, probabilmente dovrebbe. Evita il punto e virgola. Utilizzare elenchi puntati quando appropriato.
  • Fornisci contesto. Non usare abbreviazioni senza spiegarle. Non menzionare i progetti non TensorFlow senza collegarti 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, visualizzare il risultato invece di aggiungere un commento (se l'ultima espressione in una cella del taccuino non è assegnata a una variabile, viene visualizzata automaticamente).

Nella documentazione di riferimento API, i documenti preferiscono utilizzare doctest per mostrare i risultati.

Tensori

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

Non usare la parola Tensori (plurale) per descrivere più oggetti Tensor a meno che tu non stia davvero parlando di un oggetto Tensors . Dì invece "un elenco (o una raccolta) di oggetti Tensor ".

Usa la forma della parola per dettagliare gli assi di un tensore e mostra la forma tra parentesi quadre con backtick. 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" su "dimensione" quando parli degli elementi della forma di un Tensor . Altrimenti è facile confondere "dimensione" con la dimensione di uno spazio vettoriale. Un "vettore tridimensionale" ha un solo asse di lunghezza 3.