Contribua com a documentação do TensorFlow

O TensorFlow aceita contribuições de documentação. Se você melhorar a documentação, você melhorará a própria biblioteca do TensorFlow. A documentação em tensorflow.org se enquadra nas seguintes categorias:

Alguns projetos do TensorFlow mantêm os arquivos de origem da documentação próximos ao código em um repositório separado, geralmente em um diretório docs/ . Veja o arquivo CONTRIBUTING.md do projeto ou entre em contato com o mantenedor para contribuir.

Para participar da comunidade de documentos do TensorFlow:

Referência da API

Para obter detalhes, use o guia do contribuidor de documentos da API do TensorFlow . Isso mostra como encontrar o arquivo de origem e editar a docstring do símbolo. Muitas páginas de referência da API em tensorflow.org incluem um link para o arquivo de origem onde o símbolo é definido. Docstrings suportam Markdown e podem ser (aproximadamente) visualizados usando qualquer visualizador de Markdown .

Versões e ramificações

A versão de referência da API do site é padronizada para o binário estável mais recente - isso corresponde ao pacote instalado com pip install tensorflow .

O pacote TensorFlow padrão é criado a partir do branch estável rX.x no repositório principal tensorflow/tensorflow . A documentação de referência é gerada a partir de comentários de código e docstrings no código-fonte para Python , C++ e Java .

Versões anteriores da documentação do TensorFlow estão disponíveis como ramificações rX.x no repositório do TensorFlow Docs. Essas ramificações são adicionadas quando uma nova versão é lançada.

Crie documentos de API

Referência Python

O pacote tensorflow_docs inclui o gerador para os documentos de referência da API Python . Para instalar:

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

Para gerar os documentos de referência do TensorFlow 2, use o 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

Documentação narrativa

Os guias e tutoriais do TensorFlow são escritos como arquivos Markdown e notebooks Jupyter interativos. Os notebooks podem ser executados em seu navegador usando o Google Colaboratory . Os documentos narrativos em tensorflow.org são construídos a partir do ramo master tensorflow/docs . Versões mais antigas estão disponíveis no GitHub nas ramificações de lançamento rX.x

Mudanças simples

A maneira mais fácil de fazer atualizações diretas de documentação em arquivos Markdown é usar o editor de arquivos baseado na web do GitHub. Navegue no repositório tensorflow/docs para encontrar o Markdown que corresponde aproximadamente à estrutura de URL tensorflow.org . No canto superior direito da visualização do arquivo, clique no ícone de lápis para abrir o editor de arquivos. Edite o arquivo e envie uma nova solicitação pull.

Configure um repositório Git local

Para edições de vários arquivos ou atualizações mais complexas, é melhor usar um fluxo de trabalho Git local para criar uma solicitação pull.

As etapas do Git a seguir são necessárias apenas na primeira vez que você configura um projeto local.

Bifurque o repositório tensorflow/docs

Na página tensorflow/docs GitHub, clique no botão Fork para criar sua própria cópia do repositório em sua conta GitHub. Uma vez bifurcado, você será responsável por manter sua cópia do repositório atualizada com o repositório upstream do TensorFlow.

Clone seu repositório

Baixe uma cópia do seu repositório username remoto/docs para sua máquina local. Este é o diretório de trabalho onde você fará alterações: 

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

Adicione um repositório upstream para se manter atualizado (opcional)

Para manter seu repositório local sincronizado com tensorflow/docs , adicione um controle remoto upstream para baixar as alterações mais recentes.

Adicione um controle 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)

Para atualizar: 

git checkout master
git pull upstream master

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

Fluxo de trabalho do GitHub

1. Crie uma nova filial

Depois de atualizar seu repositório de tensorflow/docs , crie uma nova ramificação a partir da ramificação master local: 

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. Faça alterações

Edite os arquivos em seu editor favorito e siga o guia de estilo da documentação do TensorFlow .

Confirme a alteração do seu arquivo:

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

Adicione mais commits, conforme necessário.

3. Crie uma solicitação pull

Faça upload de sua filial local para seu repositório GitHub remoto ( username ):

git push

Após a conclusão do push, uma mensagem pode exibir um URL para enviar automaticamente uma solicitação pull ao repositório upstream. Caso contrário, acesse o repositório tensorflow/docs — ou seu próprio repositório — e o GitHub solicitará que você crie uma solicitação pull.

4. Revisão

Os mantenedores e outros colaboradores revisarão sua solicitação pull. Por favor, participe da discussão e faça as alterações solicitadas. Quando sua solicitação pull for aprovada, ela será mesclada no repositório de documentos upstream do TensorFlow.

Há uma etapa de publicação separada para atualizar o tensorflow.org do repositório GitHub. Normalmente, as alterações são agrupadas em lote e o site é atualizado em uma cadência regular.

Cadernos interativos

Embora seja possível editar o arquivo JSON do notebook com o editor de arquivos baseado na Web do GitHub, isso não é recomendado, pois JSON malformado pode corromper o arquivo. Certifique-se de testar o notebook antes de enviar uma solicitação pull.

O Google Colaboratory é um ambiente de notebook hospedado que facilita a edição e a execução da documentação do notebook. Os notebooks no GitHub são carregados no Google Colab passando o caminho para a URL do Colab, por exemplo, o notebook localizado no GitHub aqui: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /classificação.ipynb
pode ser carregado no Google Colab neste URL: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

Existe uma extensão Open in Colab Chrome que realiza essa substituição de URL ao navegar em um notebook no GitHub. Isso é útil ao abrir um notebook na bifurcação do repositório, porque os botões superiores sempre vinculam ao branch master do TensorFlow Docs.

Formatação de caderno

Uma ferramenta de formatação de notebook torna as diferenças de origem do notebook Jupyter consistentes e mais fáceis de revisar. Como os ambientes de autoria de notebook diferem em relação à saída do arquivo, recuo, metadados e outros campos não especificados; nbfmt usa padrões opinativos com preferência para o fluxo de trabalho do Colab de documentos do TensorFlow. Para formatar um notebook, instale as ferramentas de notebook de documentos do TensorFlow e execute a ferramenta 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 [...]

Para projetos de documentos do TensorFlow, notebooks sem células de saída são executados e testados; notebooks com células de saída salvas são publicados como estão. nbfmt respeita o estado do notebook e usa a opção --remove_outputs para remover explicitamente as células de saída.

Para criar um novo notebook, copie e edite o modelo de notebook de documentos do TensorFlow .

Editar no Colab

No ambiente do Google Colab, clique duas vezes nas células para editar blocos de texto e código. As células de texto usam Markdown e devem seguir o guia de estilo dos documentos do TensorFlow .

Baixe arquivos de notebook do Colab com File > Download .pynb . Envie este arquivo para seu repositório Git local e envie uma solicitação pull.

Para criar um novo notebook, copie e edite o modelo de notebook do TensorFlow .

Fluxo de trabalho Colab-GitHub

Em vez de baixar um arquivo de notebook e usar um fluxo de trabalho Git local, você pode editar e atualizar seu repositório GitHub bifurcado diretamente do Google Colab:

  1. Em seu repositório bifurcado username /docs, use a UI da web do GitHub para criar um novo branch .
  2. Navegue até o arquivo do notebook para editar.
  3. Abra o notebook no Google Colab: use a troca de URL ou a extensão Open in Colab Chrome.
  4. Edite o caderno no Colab.
  5. Confirme as alterações em seu repositório do Colab com Arquivo > Salvar uma cópia no GitHub... . A caixa de diálogo salvar deve vincular ao repositório e ramificação apropriados. Adicione uma mensagem de commit significativa.
  6. Depois de salvar, navegue até seu repositório ou repositório tensorflow/docs , o GitHub deve solicitar que você crie uma solicitação pull.
  7. A solicitação pull é revisada pelos mantenedores.

Traduções

A equipe do TensorFlow trabalha com a comunidade e os fornecedores para fornecer traduções para tensorflow.org. As traduções de notebooks e outros conteúdos técnicos estão localizadas no repositório tensorflow/docs-l10n GitHub. Envie solicitações pull por meio do projeto TensorFlow GitLocalize .

Os documentos em inglês são a fonte da verdade e as traduções devem seguir estes guias o mais fielmente possível. Dito isto, as traduções são escritas para as comunidades que servem. Se a terminologia, fraseado, estilo ou tom em inglês não for traduzido para outro idioma, use uma tradução apropriada para o leitor.

O suporte linguístico é determinado por uma série de fatores, incluindo, entre outros, métricas e demanda do site, suporte da comunidade, proficiência em inglês , preferência do público e outros indicadores. Como cada idioma suportado incorre em um custo, os idiomas não mantidos são removidos. O suporte para novos idiomas será anunciado no blog do TensorFlow ou no Twitter .

Se o seu idioma preferido não for compatível, você pode manter um fork da comunidade para contribuidores de código aberto. Eles não são publicados em tensorflow.org.