docs.md

Contribua com a documentação do TensorFlow

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

• Referência da API — a documentação de referência da API é gerada a partir de docstrings no código-fonte do TensorFlow.

• Documentação narrativa: são tutoriais, guias e outros textos que não fazem parte do código do TensorFlow. Esta documentação está no repositório tensorflow/docs no GitHub.

• Traduções da comunidade —São guias e tutoriais traduzidos pela comunidade. Todas as traduções da comunidade residem no repositório tensorflow/docs.

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

Para participar da comunidade de documentação do TensorFlow:

• Monitore o repositório GitHub tensorflow/docs.

• Siga a tag docs no Fórum do TensorFlow.

Referência da API

Para mais detalhes, use o guia do contribuidor de documentação da API do TensorFlow. Ele vai mostrar como encontrar o arquivo-fonte e como editar a docstring do símbolo. Muitas páginas de referência da API em tensorflow.org incluem um link para o arquivo-fonte onde o símbolo é definido. Docstrings suportam Markdown e podem ser visualizados (de forma aproximada) usando qualquer visualizador de Markdown.

Versões e branches

A versão da Referência da API do site refere-se ao binário estável mais recente, o que 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++ eJava.

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

Geração dos documentos da API

Observação: esta etapa não é necessária para editar ou visualizar documentos da API, apenas para gerar o HTML usado em tensorflow.org.

Referência Python

O pacote tensorflow_docs inclui o gerador para a documentação de referência da API Python. Para instalar:

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

Para gerar a documentação 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

Observação: este script usa o pacote TensorFlow instalado para gerar documentação e funciona apenas para o TensorFlow 2.x.

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. A documentação narrativa em tensorflow.org é construída a partir do branch master de tensorflow/docs. Versões mais antigas estão disponíveis no GitHub nos branches de lançamento rX.x

Alterações simples

A maneira mais fácil de fazer atualizações na 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 da 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 submeta um novo pull request.

Instale um repositório Git local

Para edições em múltiplos arquivos ou atualizações mais complexas, é melhor usar um workflow Git local para criar um pull request.

Observação: O Git é o sistema de controle de versão (VCS) de código aberto usado para rastrear alterações em código-fonte. O GitHub é um serviço online que fornece ferramentas de colaboração que funcionam com Git. Consulte a Ajuda do GitHub para configurar sua conta GitHub e começar.

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

Faça um fork do 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 na sua conta GitHub. Uma vez feito o fork, você será responsável por manter sua cópia do repositório em dia com o repositório upstream do TensorFlow.

Clone seu repositório

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

git clone [email protected]:<var>username</var>/docs
cd ./docs

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

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

Observação: não deixe de atualizar seu repositório local antes de iniciar uma contribuição. As sincronizações regulares com o repositório upstream reduzem a chance de um conflito de merge quando você envia seu pull request.

Adicione um repositório remoto:

<code class="devsite-terminal">git remote add upstream [email protected]:tensorflow/docs.git</code>

# View remote repos
<code class="devsite-terminal">git remote -v</code>
origin    [email protected]:<var>username</var>/docs.git (fetch)
origin    [email protected]:<var>username</var>/docs.git (push)
upstream  [email protected]:tensorflow/docs.git (fetch)
upstream  [email protected]:tensorflow/docs.git (push)

Para atualizar:

<code class="devsite-terminal">git checkout master</code>
<code class="devsite-terminal">git pull upstream master</code>

<code class="devsite-terminal">git push</code>  # Push changes to your GitHub account (defaults to origin)

Workflow do GitHub

1. Crie um novo branch

Depois de atualizar seu repositório a partir de tensorflow/docs, crie um novo branch a partir do branch master local:

<code class="devsite-terminal">git checkout -b <var>feature-name</var></code>

<code class="devsite-terminal">git branch</code>  # List local branches
  master
* <var>feature-name</var>

2. Faça alterações

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

Faça commit da alteração do seu arquivo:

# View changes
<code class="devsite-terminal">git status</code>  # See which files have changed
<code class="devsite-terminal">git diff</code>    # See changes within files

<code class="devsite-terminal">git add <var>path/to/file.md</var></code>
<code class="devsite-terminal">git commit -m "Your meaningful commit message for the change."</code>

Adicione mais commits, conforme necessário.

3. Crie um pull request

Faça upload do seu branch local para seu repositório GitHub remoto ( github.com/nome_de_usuário/docs):

git push

Após a conclusão do push, uma mensagem poderá exibir uma URL para enviar automaticamente um pull request 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 um pull request.

4. Revise

Mantenedores e outros colaboradores revisarão seu pull requesst. Por favor, participe da discussão e faça as alterações solicitadas. Quando seu pull request for aprovado, será feito o merge dele com o repositório upstream do TensorFlow docs.

Sucesso: suas alterações foram aceitas na documentação 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 numa cadência regular.

Notebooks interativos

Embora seja possível editar o arquivo JSON do notebook com o editor de arquivos baseado na web do GitHub, isto não é recomendado, pois JSON malformado pode corromper o arquivo. Certifique-se de testar o notebook antes de enviar um pull request.

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

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

Formatação dos notebooks

Uma ferramenta de formatação de notebooks deixa os diffs das fontes do notebook Jupyter consistentes e mais fáceis de revisar. Como os ambientes de autoria de notebooks 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 workflow do Colab de documentação do TensorFlow. Para formatar um notebook, instale as ferramentas de notebook para documentação 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 documentação 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. 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 para documentação do TensorFlow.

Edição no Colab

Dentro do ambiente do Google Colab, dê um duplo clique nas células para editar blocos de texto e código. Células de texto usam Markdown e devem seguir o guia de estilo para documentação do TensorFlow.

Baixe arquivos de notebook do Colab com File > Download .pynb. Faça um commit desse arquivo para seu repositório Git local e envie um pull request.

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

Workflow Colab-GitHub

Em vez de baixar um arquivo de notebook e usar um workflow de Git local, você pode editar e atualizar o fork do seu repositório GitHub diretamente no Google Colab:

1. No seu fork do repositório nome_de_usuário/docs, use a interface 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 Chrome Open in Colab.

4. Edite o notebook no Colab.

5. Faça commit das alterações no seu repositório do Colab com File > Save a copy in GitHub.... A caixa de diálogo salvar deve conter um link para o repositório e branch apropriados. Adicione uma mensagem de commit significativa.

6. Depois de salvar, navegue até seu repositório ou até o repositório tensorflow/docs, o GitHub deve solicitar que você crie um pull request.

7. O pull request será revisado pelos mantenedores.

Sucesso: suas alterações foram aceitas na documentação do TensorFlow.

Traduções

A equipe do TensorFlow trabalha com a comunidade e fornecedores para fornecer traduções para o site tensorflow.org. As traduções de notebooks e outros conteúdos técnicos estão localizadas no repositório tensorflow/docs-l10n no GitHub. Por favor, envie pull requests através do projeto TensorFlow GitLocalize.

A documentação em inglês é a fonte da verdade e as traduções devem seguir esstes 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 traduzir bem para outro idioma, por favor use uma tradução apropriada para o leitor.

O suporte a outros idiomas é 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ências do público e outros indicadores. Como cada idioma suportado incorre em um custo, os idiomas que não são mantidos são removidos. O suporte a 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. Esses forks não são publicados no site tensorflow.org.