Contribuisci alla documentazione di TensorFlow

TensorFlow accoglie con favore i contributi alla documentazione: se migliori la documentazione, migliori la libreria TensorFlow stessa. La documentazione su tensorflow.org rientra nelle seguenti categorie:

Alcuni progetti TensorFlow mantengono i file sorgente della documentazione vicino al codice in un repository separato, solitamente in una directory docs/ . Vedi il file CONTRIBUTING.md del progetto o contatta il manutentore per contribuire.

Per partecipare alla community dei documenti TensorFlow:

Riferimento API

Per maggiori dettagli, utilizza la guida per collaboratori alla documentazione dell'API TensorFlow . Questo mostra come trovare il file sorgente e modificare la docstring del simbolo. Molte pagine di riferimento API su tensorflow.org includono un collegamento al file sorgente in cui è definito il simbolo. Le docstring supportano Markdown e possono essere (approssimativamente) visualizzate in anteprima utilizzando qualsiasi visualizzatore di anteprima Markdown .

Versioni e rami

Per impostazione predefinita, la versione di riferimento dell'API del sito è l'ultimo binario stabile: corrisponde al pacchetto installato con pip install tensorflow .

Il pacchetto TensorFlow predefinito è creato dal ramo stabile rX.x nel repository tensorflow/tensorflow principale. La documentazione di riferimento viene generata da commenti di codice e docstring nel codice sorgente per Python , C++ e Java .

Le versioni precedenti della documentazione di TensorFlow sono disponibili come rami rX.x nel repository TensorFlow Docs. Questi rami vengono aggiunti quando viene rilasciata una nuova versione.

Crea documenti API

Riferimento Python

Il pacchetto tensorflow_docs include il generatore per i documenti di riferimento dell'API Python . Per installare:

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

Per generare i documenti di riferimento di TensorFlow 2, utilizzare 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

Documentazione narrativa

Le guide e i tutorial di TensorFlow sono scritti come file Markdown e notebook Jupyter interattivi. I notebook possono essere eseguiti nel tuo browser utilizzando Google Colaboratory . I documenti narrativi su tensorflow.org sono creati dal ramo master tensorflow/docs . Le versioni precedenti sono disponibili in GitHub nei rami della versione rX.x

Cambiamenti semplici

Il modo più semplice per apportare semplici aggiornamenti alla documentazione dei file Markdown è utilizzare l'editor di file basato sul Web di GitHub. Sfoglia il repository tensorflow/docs per trovare il Markdown che corrisponde approssimativamente alla struttura dell'URL tensorflow.org . Nell'angolo in alto a destra della visualizzazione del file, fai clic sull'icona della matita per aprire l'editor di file. Modifica il file e quindi invia una nuova richiesta pull.

Configura un repository Git locale

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

I seguenti passaggi Git sono richiesti solo la prima volta che configuri un progetto locale.

Effettua il fork del repository tensorflow/docs

Nella pagina GitHub tensorflow/docs , fare clic sul pulsante Fork per creare la tua copia repository nel tuo account GitHub. Una volta effettuato il fork, sei responsabile di mantenere aggiornata la copia del repository con il repository TensorFlow upstream.

Clona il tuo repository

Scarica una copia del repository username /documenti remoto sul computer locale. Questa è la directory di lavoro in cui apporterai le modifiche:

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

Aggiungi un repository upstream per rimanere aggiornato (facoltativo)

Per mantenere il tuo repository locale sincronizzato con tensorflow/docs , aggiungi un telecomando upstream per scaricare le modifiche più recenti.

Aggiungi un telecomando:

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)

Per aggiornare:

git checkout master
git pull upstream master

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

Flusso di lavoro GitHub

1. Crea una nuova filiale

Dopo aver aggiornato il repository da tensorflow/docs , crea un nuovo ramo dal ramo master locale:

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. Apportare modifiche

Modifica i file nel tuo editor preferito e segui la guida di stile della documentazione di TensorFlow .

Conferma la modifica del file:

# 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."

Aggiungi altri commit, se necessario.

3. Creare una richiesta pull

Carica il tuo ramo locale sul tuo repository GitHub remoto ( username ):

git push

Al termine del push, un messaggio potrebbe visualizzare un URL per inviare automaticamente una richiesta pull al repository upstream. In caso contrario, vai al repository tensorflow/docs , o al tuo repository, e GitHub ti chiederà di creare una richiesta pull.

4. Revisione

I manutentori e gli altri contributori esamineranno la tua richiesta di pull. Partecipa alla discussione e apporta le modifiche richieste. Quando la richiesta pull viene approvata, verrà unita al repository di documenti TensorFlow upstream.

È previsto un passaggio di pubblicazione separato per aggiornare tensorflow.org dal repository GitHub. In genere, le modifiche vengono raggruppate e il sito viene aggiornato a cadenza regolare.

Quaderni interattivi

Anche se è possibile modificare il file JSON del notebook con l'editor di file basato sul Web di GitHub, non è consigliabile poiché un formato JSON non valido può danneggiare il file. Assicurati di testare il notebook prima di inviare una richiesta pull.

Google Colaboratory è un ambiente notebook ospitato che semplifica la modifica e l'esecuzione della documentazione del notebook. I notebook in GitHub vengono caricati in Google Colab passando il percorso all'URL Colab, ad esempio, il notebook che si trova in GitHub qui: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /classificazione.ipynb
può essere caricato in Google Colab a questo URL: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

Esiste un'estensione Open in Colab di Chrome che esegue questa sostituzione dell'URL durante l'esplorazione di un notebook su GitHub. Ciò è utile quando si apre un notebook nel fork del repository, poiché i pulsanti in alto si collegano sempre al ramo master di TensorFlow Docs.

Formattazione del taccuino

Uno strumento di formattazione del notebook rende le differenze di origine del notebook Jupyter coerenti e più facili da rivedere. Poiché gli ambienti di creazione dei notebook differiscono per quanto riguarda l'output del file, il rientro, i metadati e altri campi non specificati; nbfmt utilizza impostazioni predefinite supponenti con una preferenza per il flusso di lavoro Colab dei documenti TensorFlow. Per formattare un notebook, installa gli strumenti del notebook TensorFlow docs ed esegui lo strumento nbfmt :

# Install the tensorflow-docs package:
$ python3 -m pip install -U [--user] git+https://github.com/tensorflow/docs

$ python3 -m tensorflow_docs.tools.nbfmt [options] notebook.ipynb [...]

Per i progetti di documenti TensorFlow, i notebook senza celle di output vengono eseguiti e testati; i notebook con celle di output salvate vengono pubblicati così come sono. nbfmt rispetta lo stato del notebook e utilizza l'opzione --remove_outputs per rimuovere esplicitamente le celle di output.

Per creare un nuovo taccuino, copia e modifica il modello di taccuino dei documenti TensorFlow .

Modifica in Colab

Nell'ambiente Google Colab, fai doppio clic sulle celle per modificare testo e blocchi di codice. Le celle di testo utilizzano Markdown e devono seguire la guida di stile dei documenti TensorFlow .

Scaricare i file del notebook da Colab con File > Download .pynb . Salva questo file nel repository Git locale e invia una richiesta pull.

Per creare un nuovo taccuino, copia e modifica il modello di taccuino TensorFlow .

Flusso di lavoro Colab-GitHub

Invece di scaricare un file notebook e utilizzare un flusso di lavoro Git locale, puoi modificare e aggiornare il repository GitHub biforcato direttamente da Google Colab:

  1. Nel repository username /docs biforcato, utilizza l'interfaccia utente web di GitHub per creare un nuovo ramo .
  2. Passare al file del notebook da modificare.
  3. Apri il blocco note in Google Colab: utilizza lo scambio URL o l'estensione Apri in Colab Chrome.
  4. Modifica il taccuino in Colab.
  5. Applica le modifiche al tuo repository da Colab con File > Save a copy in GitHub... . La finestra di dialogo di salvataggio dovrebbe collegarsi al repository e al ramo appropriati. Aggiungi un messaggio di commit significativo.
  6. Dopo il salvataggio, vai al repository o al repository tensorflow/docs , GitHub dovrebbe chiederti di creare una richiesta pull.
  7. La richiesta pull viene esaminata dai manutentori.

Traduzioni

Il team di TensorFlow collabora con la comunità e i fornitori per fornire traduzioni per tensorflow.org. Le traduzioni di notebook e altri contenuti tecnici si trovano nel repository GitHub tensorflow/docs-l10n . Invia richieste pull tramite il progetto TensorFlow GitLocalize .

I documenti in inglese sono la fonte della verità e le traduzioni dovrebbero seguire queste guide il più fedelmente possibile. Detto questo, le traduzioni vengono scritte per le comunità in cui operano. Se la terminologia, la frase, lo stile o il tono inglese non sono traducibili in un'altra lingua, utilizzare una traduzione appropriata per il lettore.

Il supporto linguistico è determinato da una serie di fattori tra cui, a titolo esemplificativo, parametri e domanda del sito, supporto della comunità, conoscenza dell'inglese , preferenza del pubblico e altri indicatori. Poiché ogni lingua supportata comporta un costo, le lingue non gestite vengono rimosse. Il supporto per le nuove lingue verrà annunciato sul blog TensorFlow o su Twitter .

Se la tua lingua preferita non è supportata, puoi mantenere un fork della community per i contributori open source. Questi non sono pubblicati su tensorflow.org.