Contribuire alla documentazione di TensorFlow

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

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

Per partecipare alla community dei documenti di TensorFlow:

Riferimento API

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

Versioni e rami

La versione di riferimento dell'API del sito è predefinita sull'ultimo binario stabile, che 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 è 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 branch 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 . Installare:

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

Per generare i documenti di riferimento di TensorFlow 2, utilizzare lo 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 taccuini Jupyter interattivi. I taccuini possono essere eseguiti nel tuo browser utilizzando Google Colaboratory . I documenti narrativi su tensorflow.org sono costruiti dal ramo master tensorflow/docs . Le versioni precedenti sono disponibili in GitHub sui rami di rilascio di rX.x

Semplici cambiamenti

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

Configura un repository Git locale

Per modifiche a 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.

Eseguire il fork del repository tensorflow/docs

Nella pagina Tensorflow/docs GitHub, fai clic sul pulsante Fork per creare la tua copia del repository con il tuo account GitHub. Una volta eseguito il fork, sei responsabile di mantenere aggiornata la copia del repository con il repository TensorFlow a monte.

Clona il tuo repository

Scarica una copia del tuo username remoto /docs repository sul tuo 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 tenerti aggiornato (opzionale)

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

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)

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 un nuovo ramo

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

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. Apporta modifiche

Modifica i file nel tuo editor preferito e segui la guida allo 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 più commit, se necessario.

3. Crea 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 altri contributori esamineranno la tua richiesta pull. Si prega di partecipare alla discussione e apportare le modifiche richieste. Quando la tua richiesta pull viene approvata, verrà unita al repository di documenti TensorFlow a monte.

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

Quaderni interattivi

Sebbene sia possibile modificare il file JSON del notebook con l' editor di file basato sul Web di GitHub, non è consigliabile poiché un JSON non corretto può corrompere 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 Chrome che esegue questa sostituzione dell'URL durante la navigazione in 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 output di file, indentazione, metadati e altri campi non specificati; nbfmt utilizza impostazioni predefinite supponenti con una preferenza per il flusso di lavoro TensorFlow docs Colab. 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 TensorFlow docs, i notebook senza celle di output vengono eseguiti e testati; i taccuini con le 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 di TensorFlow docs .

Modifica in Colab

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

Scarica i file del notebook da Colab con File > Download .pynb . Invia questo file al 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 tuo repository GitHub fork direttamente da Google Colab:

  1. Nel tuo username biforcato /docs repository, usa l'interfaccia utente web di GitHub per creare un nuovo ramo .
  2. Passare al file del taccuino da modificare.
  3. Apri il taccuino in Google Colab: utilizza lo scambio di URL o l'estensione Apri in Colab Chrome.
  4. Modifica il taccuino in Colab.
  5. Conferma le modifiche al tuo repository da Colab con File > Salva una copia in GitHub... . La finestra di dialogo di salvataggio dovrebbe collegarsi al repository e al ramo appropriati. Aggiungi un messaggio di commit significativo.
  6. Dopo aver salvato, vai al tuo 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ù vicino possibile. Detto questo, le traduzioni sono scritte per le comunità che servono. Se la terminologia, il fraseggio, lo stile o il tono inglese non si traducono in un'altra lingua, utilizzare una traduzione appropriata per il lettore.

Il supporto linguistico è determinato da una serie di fattori inclusi, ma non limitati a, metriche e domanda del sito, supporto della comunità, conoscenza della lingua inglese , preferenza del pubblico e altri indicatori. Poiché ogni lingua supportata comporta un costo, le lingue non mantenute vengono rimosse. Il supporto per le nuove lingue sarà annunciato sul blog di 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.