Contribuire alla documentazione TensorFlow

TensorFlow accoglie contributi alla documentazione—se migliorate la documentazione, migliorate la libreria TensorFlow in se. La documentazione tensorflow.org ricade nelle seguenti categorie:

Alcuni progetti TensorFlow tengono i file sorgenti della documentazione vicino al codice in un repository separato, di solito in una directory docs/. Vedere il file del progetto CONTRIBUTING.md o contattare il responsabile della manutenzione per contribuire.

Per partecipare alla comunità docs di TensorFlow:

API reference

Per modificare la documentazione di riferimento, trovare il file sorgente e cambiare le docstring dei simboli. Molte pagine di riferimento per le API in tensorflow.org sono collegate al codice sorgente ove è definito un simbolo. I docstring supportano il Markdown e possono essere visti (approssimativamente) in anteprima usando un qualsiasi Markdown previewer.

Per la qualità della documentazione di riferimento e come essere coinvolti nella comunità degli sprint di Docs, vedere gli avvisi di Docs per le API TensorFlow 2.

Versioni e rami

La versione del sito API reference punta, per default, all'ultima versione stabile del codice binario—che corrisponde al pacchetto installato con pip install tensorflow.

Il pacchetto di default di TensorFlow è compilato dal ramo stabile rX.x del repository principale tensorflow/tensorflow. La documentazione di riferimento è generata dai commenti del codice e dalle docstring nel codice sorgente per Python, C++, e Java.

Versioni precedenti della documentazione TensorFlow sono disponibili come nel repository Docs di tensorFlow come rami rX.x. Questi rami vengono aggiunti ogni volta che viene rilasciata una nuova versione.

Compilare la documentazione sulle API

Nota: Questo passaggio non è richiesto per modificare o vedere in anteprima le docstring delle API, ma solo per generare l'HTML usato su tensorflow.org.

Python reference

Il pacchetto tensorflow_docs include il generatore per la documentazione di riferimento per le PI Python. Per installarla usare:

pip install git+https://github.com/tensorflow/docs

Per generare la documentazione di riferimento TensorFlow 2, usare lo script: tensorflow/tools/docs/generate2.py

git clone https://github.com/tensorflow/tensorflow tensorflow
cd tensorflow/tensorflow/tools/docs
pip install tensorflow
python generate2.py --output_dir=/tmp/out

Nota: Questo script usa il pacchetto TensorFlow installato per generare i documenti e funziona solo per TensorFlow 2.x.

Documentazione discorsiva

Le guide ed i tutorial TensorFlow sono scritti come file Markdown e notebook Jupyter interattivi. I notebook possono essere eseguiti nel vostro browser usando Google Colaboratory. I documenti discorsivi su tensorflow.org sono compilati dal ramo master tensorflow/docs. Le versioni più vecchie sono disponibili in GitHub sui rami dei rilasci rX.x.

Modifiche semplici

Il modo più facile per fare aggiornamenti diretti e correzioni è usare l' editor di file di GitHub via web. Navigate il repository tensorflow/docs per localizzare il file Markdown o il notebook che corrisponde sommariamente alla struttura dell' URL tensorflow.org. Nell'angolo in alto a destra della pagina, cliccate sull'icona della matita per aprire l'editor di file. Modificate il file, e fate una nuova richiesta di pull.

Inizializzare un repository Git locale

Per modifiche a più file o aggiornamenti più complessi, è meglio lavorare su un Git locale per creare una richiesta di pull.

Nota: Git è un sistema di controllo delle versioni (VCS) a codice aperto, usato per tracciare le modifiche al codice sorgente. GitHub è un servizio online che fornisce strumenti collaborativi per lavorare con Git. Vedere l' Aiuto GitHub per inizializzare il vostro account GitHub e iniziare.

I passi seguenti su Git sono necessari solo la prima volta che inizializzate il vostro progetto locale.

Fare un fork del repository tensorflow/docs

Per creare la vostra copia del repository, all'interno del vostro account GitHub, cliccate il pulsante Fork sulla pagina GitHub tensorflow/docs. Una volta eseguito il fork, voi siete responsabili di tenere aggiornata la vostra copia rispetto al repository TensorFlow originale.

Fare un clone del vostro repository

Scaricate una copia del vostro repository di documentazione username/docs remoto, sulla vostra macchina locale. Questa è la directory di lavoro dove farete i cambiamenti:

git clone git@github.com:username/docs
cd ./docs

Aggiungere un repository origine (upstream n.d.t.) per rimanere aggiornati (opzionale)

Per mantenere sincronizzato il vostro repository locale con tensorflow/docs, aggiungete un' origine remota per scaricare gli aggiornamenti più recenti.

Nota: Accertatevi di aggiornare il vostro repository locale prima di iniziare un contributo. Sincronizzazioni regolari con l'origine riducono la probabilità di un conflitto di merge quando inoltrate la vostra richiesta di pull.

Aggiungere un repository remoto:

git remote add upstream git@github.com:tensorflow/docs.git

# View remote repos
git remote -v
origin    git@github.com:username/docs.git (fetch)
origin    git@github.com:username/docs.git (push)
upstream  git@github.com:tensorflow/docs.git (fetch)
upstream  git@github.com:tensorflow/docs.git (push)

Aggiornare:

git checkout master
git pull upstream master

git push  # Push changes to your GitHub account (defaults to origin)

Modalità di lavoro su GitHub

1. Creare un nuovo ramo

Dopo che avete aggiornato il vostro repository da tensorflow/docs, create un nuovo ramo dal rano master locale:

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. Apportare i cambiamenti

Modificate i file con il vostro editor preferito e seguite le guide di stile TensorFlow.

Fate commit delle vostre modifiche:

# View changes
git status  # See which files have changed
git diff    # See changes within files

git add path/to/file.md
git commit -m "Your meaningful commit message for the change."

Se necessario, aggiungete altri commit.

3. Create una richiesta di pull

Caricate il vostro ramo locale sul vostro repository GitHub remoto (github.com/username/docs):

git push

Dopo aver completato il push, un messaggio potrebbe presentare un URL per sottomettere automaticamente una richiesta di pull al repository origine. Se ciò non accade, andate sul repository tensorflow/docs —o sul vostro repository—e GitHub vi proporrà di creare una nuova richiesta di pull.

4. Revisioni

I manutentori ed altri contributori revisioneranno la vostra richiesta di pull. Partecipate alla discussione e fate i cambiamenti che vi vengono richiesti. quando la vostra richiesta di pull sarà approvata, sarà inserita nel repository della documentazione TensorFlow originale.

Successo: I vostri cambiamenti sono stati accettati nella documentazione TensorFlow.

Per aggiornare il repository tensorflow.org da quello GitHub c'è un passo di pubblicazione diverso. Di solito, i cambiamenti sono accorpati, ed il sito è aggiornato con cadenza regolare.

Notebook interattivi

Non è raccomandato modificare il file JSON dei notebook
l'editor web di GitHub, perché, benché sia possibile, il JSON malformato può danneggiare il file stesso. Quindi, provate un notebook, prima di sottomettere una richiesta di pull.

Google Colaboratory è un ambiente di esecuzione di notebook che rende facile modificare ed eseguire notebook di documentazione. I notebook, in GitHub, sono caricati in Google Colab passando il loro percorso all'URL di Colab, per esempio, il notebook che in GitHub si trova qui: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb
può essere caricato in Google Colab con questo URL: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

C'è un'estensione di Chrome Apri in Colab che realizza questa sostituzione di URL quando sta navigando un notebook in GitHub. Ciò è utile quando state aprendo un notebook nel vostro fork di repository, perché il bottone in alto punte sempre al ramo master di TensorFlow Docs.

Modificare in Colab

All'interno dell'ambiente Google Colab, fate doppio click sulle celle per modificare il testo ed i blocchi di codice. Le celle di testo usano Markdown e dovrebbero seguire le linee guida di stile di TensorFlow.

Scaricate i file notebook da Colab con File > Download .pynb. Fate commit nel vostro repository Git locale e mandate una richiesta di pull.

Per creare un nuovo notebook, copiate e modificate il template di notebook TensorFlow.

Modalità di lavoro Colab-GitHub

Invece di scaricare un file notebook ed usare Git locale, potete modificare ed aggiornare la vostra copia di repository GitHub direttamente con Google Colab:

  1. Nel vostro repository, ottenuto tramite fork, in username/docs, usate l'interfaccia web di GitHub per creare un nuovo ramo.
  2. Spostatevi sul file notebook per modificarlo.
  3. Aprite il notebook in Google Colab: usando la conversione di URL o l'estensione Chrome: Apri in Colab.
  4. Modificate il notebook in Colab.
  5. Fate commit dei cambiamenti al vostro repository da Colab con File > Save a copy in GitHub..., con cui la finestra di dialogo di salvataggio dovrebbe collegarsi al ramo del repository appropriato, ed aggiungete un messaggio di commit significativo.
  6. Dopo il salvataggio, andate al vostro repository o sul repository tensorflow/docs, e GitHub dovrebbe chiedervi di creare la richiesta di pull.
  7. La richiesta di pull è revisionata dai manutentori.

Successo: I vostri cambiamenti sono stati accettati nella documentazione TensorFlow.

Traduzioni della comunità

Le traduzioni della comunità sono un modo fantastico di rendere accessibile TensorFlow in tutto il mondo. Per fare una traduzione, trovate o aggiungete un file alla directory delle lingue che abbia la stessa struttura della directory en/. I documenti in Inglese sono la fonte originale e le traduzioni dovrebbero seguirli il più fedelmente possibile. Ciò detto, le traduzioni sono scritte dalle comunità a cui servono. Se la terminologia Inglese, la struttura delle frasi, lo stile, o il tono, non sono traducibili in un'altra lingua, usate una traduzione appropriata per il lettore.

Nota: la documentazione di riferimento per le API non viene tradotta per tensorflow.org.

Questi sono i gruppi di documentazione specifici per lingua che rendono facile organizzarsi ai contributori delle traduzioni. Iscrivetevi se siete un autore, un revisore, o semplicemente una persona interessata a rendere disponibile il contenuto TensorFlow.org content per la comunità:

Notifiche di revisione

Tutte le modifiche alla documentazione devono essere revisionate. Per collaborare in modo effciente con la comunità di traduzione di TensorFlow, qui ci sono alcuni modi per rimanere aggiornati sulle attività per una lingua in particolare:

  • Aggregatevi ad uno dei gruppi di lingua elencati sopra per ricevere un'email per ogni richiesta di pull creata che faccia riferimento alla directory site/lang relativa alla lingua.
  • Aggiungete il vostro nome utente GitHub al file site/<lang>/REVIEWERS per essere etichettati per commenti in una richiesta di pull. Quando siete etichettati per commenti, per ogni modifica o discussione relativa alla richiesta di pull, GitHub vi manderà una notifica.

Mantenere aggiornato il codice nelle traduzioni

Per un progetto open source come TensorFlow, è arduo mantenere aggiornata la documentazione. Dopo aver parlato con la comunità, i lettori di contenuti tradotti tollereranno un testo leggermente arretrato, ma il codice arretrato è frustrante. Per rendere più facile mantenere aggiornato il codice, usare il tool nb-code-sync sui notebook tradotti:

./tools/nb_code_sync.py [--lang=en] site/lang/notebook.ipynb

Questo script legge le celle di codice di un notebook e le controlla a fronte della versione Inglese. Dopo aver sezionato il contenuto, confronta i blocchi di codice ed aggiorna il linguaggio del notebook se diverso. Questo strumento è particolarmente utile in una modalità di lavoro Git interattiva per aggiungere selettivamente porzioni di file al commit usando: git add --patch site/lang/notebook.ipynb