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:
- Referência da API — os documentos de referência da API são gerados 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 GitHub tensorflow/docs .
- Traduções da comunidade —São guias e tutoriais traduzidos pela comunidade. Todas as traduções da comunidade ficam no repositório tensorflow/docs .
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:
- Assista ao repositório GitHub tensorflow/docs .
- Siga a tag de documentos no fórum 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 reposgit 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 changesgit status
# See which files have changedgit diff
# See changes within filesgit 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:
- 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 .
- Navegue até o arquivo do notebook para editar.
- Abra o notebook no Google Colab: use a troca de URL ou a extensão Open in Colab Chrome.
- Edite o notebook no Colab.
- 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.
- 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.
- 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.