O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Contribua com a documentação do TensorFlow

O TensorFlow agradece as contribuições da documentação - se você melhorar a documentação, estará aprimorando 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 TensorFlow:

Referência API

Para atualizar a documentação de referência, encontre o arquivo de origem e edite 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 Markdown .

Para obter a qualidade da documentação de referência e como se envolver com doc sprints e a comunidade, consulte o conselho do TensorFlow 2 API Docs .

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 rX.x tensorflow / tensorflow principal. 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 .

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

Construir 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 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. Notebooks podem ser executados em seu navegador usando o Google Colaboratory . Os documentos narrativos em tensorflow.org são construídos a partir do branch master tensorflow / docs . Versões mais antigas estão disponíveis no GitHub nas rX.x versão rX.x

Mudanças simples

A maneira mais fácil de fazer atualizações diretas na documentação dos arquivos Markdown é usar o editor de arquivos baseado na web do GitHub. Navegue pelo 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 de 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 seguintes etapas do Git são necessárias apenas na primeira vez que você configura um projeto local.

Bifurcação do repositório tensorflow / docs

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

Clone seu repo

Baixe uma cópia de seu repo de username de username / docs remoto para sua máquina local. Este é o diretório de trabalho onde você fará as 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 em sincronia com tensorflow/docs , adicione um remoto upstream para baixar as últimas mudanças.

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)

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 repo de tensorflow/docs , crie um novo branch a partir do branch master local:

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. Faça alterações

Edite arquivos em seu editor favorito e siga o guia de estilo de 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 o repositório GitHub remoto (github.com/ username / docs):

git push

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

4. Rever

Os mantenedores e outros colaboradores analisarão sua solicitação de pull. 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 do TensorFlow upstream.

Há uma etapa de publicação separada para atualizar tensorflow.org do repositório GitHub. Normalmente, as alterações são agrupadas 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, não é recomendado, pois um JSON malformado pode corromper o arquivo. Certifique-se de testar o notebook antes de enviar uma solicitação de pull.

O Google Colaboratory é um ambiente de notebook hospedado que facilita a edição - e a execução - da documentação do notebook. Notebooks no GitHub são carregados no Google Colab passando o caminho para o URL do Colab, por exemplo, o notebook localizado no GitHub aqui: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /classification.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 do Chrome que realiza essa substituição de URL ao navegar em um notebook no GitHub. Isso é útil ao abrir um notebook em sua bifurcação de repositório, porque os botões superiores sempre se vinculam ao branch master do TensorFlow Docs.

Formatação de notebook

Uma ferramenta de formatação de bloco de notas torna as diferenças de fonte do bloco de notas Jupyter consistentes e fáceis de revisar. Uma vez que os ambientes de criação de notebooks diferem em relação à saída de arquivo, indentação, metadados e outros campos não especificados; nbfmt usa padrões opinativos com preferência para o fluxo de trabalho Colab de documentos do TensorFlow. Para formatar um notebook, instale as ferramentas do TensorFlow docs notebook 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; cadernos com células de saída salvas são publicados no estado em que se encontram. 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 o texto e os blocos de código. As células de texto usam Markdown e devem seguir o guia de estilo de documentos do TensorFlow .

Baixe os arquivos do bloco de notas do Colab com Arquivo> Baixar .pynb . Faça commit desse arquivo em seu repositório Git local e envie uma solicitação pull.

Para criar um novo notebook, copie e edite o modelo de notebook 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 repo de username / docs bifurcado, use a IU da Web do GitHub para criar um novo branch .
  2. Navegue até o arquivo do bloco de notas para editar.
  3. Abra o notebook no Google Colab: use a troca de URL ou a extensão do Chrome Open in Colab .
  4. Edite o bloco de notas no Colab.
  5. Envie as alterações para o seu repo em Colab com Arquivo> Salvar uma cópia no GitHub .... A caixa de diálogo de salvamento deve ser vinculada ao repositório e ramificação apropriados. Adicione uma mensagem de confirmação significativa.
  6. Depois de salvar, navegue até seu repo ou tensorflow / docs repo, o GitHub deve solicitar que você crie uma solicitação pull.
  7. A solicitação de pull é revisada pelos mantenedores.

Traduções

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

Os documentos em inglês são a fonte da verdade e as traduções devem seguir esses guias o mais próximo possível. Dito isso, as traduções são escritas para as comunidades que atendem. Se a terminologia, frase, estilo ou tom em inglês não forem traduzidos para outro idioma, use uma tradução apropriada para o leitor.

O suporte ao idioma é determinado por vários fatores, incluindo - mas não se limitando a - 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 com suporte 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 suportado, você é bem-vindo para manter uma bifurcação da comunidade para contribuidores de código aberto. Eles não são publicados em tensorflow.org.