Contribuir para a documentação do TensorFlow

O TensorFlow agradece as contribuições de documentação — se você melhorar a documentação, melhorará a própria biblioteca do TensorFlow. A documentação no 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 no 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 .

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 padrão do TensorFlow é construído 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 .

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

Criar documentos da 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 ramificações de lançamento do rX.x

Mudanças simples

A maneira mais fácil de fazer atualizações de documentação diretas 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.

Configurar 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.

Fork o repositório tensorflow/docs

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

Clone seu repositório

Faça o download de uma cópia do repositório /docs do seu nome de username 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 manter-se 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)

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 ramificação

Depois de atualizar seu repositório de tensorflow/docs , crie uma nova ramificação da ramificação mestre 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

Carregue sua ramificação local para seu repositório GitHub remoto ( username ):

git push

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

4. Revisão

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

Há uma etapa de publicação separada para atualizar o 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 o 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. 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 bloco de anotações em sua bifurcação de repositório, porque os botões superiores sempre são vinculados à ramificação master do TensorFlow Docs.

Formatação do bloco de anotações

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 do 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 TensorFlow docs Colab. Para formatar um notebook, instale as ferramentas de notebook do TensorFlow docs 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 do TensorFlow .

Editar no Colab

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

Baixe arquivos de notebook do Colab com Arquivo > Baixar .pynb . Confirme este arquivo em seu repositório Git local e envie uma solicitação de pull.

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

Fluxo de trabalho do 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 bifurcado do GitHub diretamente do Google Colab:

  1. Em seu repositório /docs de nome de username bifurcado, use a interface do usuário 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 notebook no Colab.
  5. Confirme as alterações em seu repositório do Colab com File > Save a copy in GitHub... . A caixa de diálogo salvar deve ser vinculada ao repositório e à ramificação apropriados. Adicione uma mensagem de confirmação significativa.
  6. Depois de salvar, navegue até seu repositório ou o repositório tensorflow/docs , o GitHub deve solicitar que você crie uma solicitação pull.
  7. O pull request é revisado pelos mantenedores.

Traduções

A equipe do TensorFlow trabalha com a comunidade e os fornecedores para fornecer traduções para o tensorflow.org. Traduções de notebooks e outros conteúdos técnicos estão localizados no repositório GitHub tensorflow/docs-l10n . 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 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 ao idioma é determinado por vários fatores, incluindo, mas não limitado 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 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 suportado, você pode manter um fork da comunidade para contribuidores de código aberto. Eles não são publicados no tensorflow.org.