Guia de estilo de documentação do TensorFlow

Melhores práticas

  • Foque na intenção do usuário e no público-alvo.
  • Use palavras do dia a dia e escreva frases curtas.
  • Utilize consistência na construção das frases, na escolha das palavras e no uso de maiúsculas.
  • Use títulos e listas para facilitar a leitura dos seus documentos.
  • O Guia de Estilo da Documentação para Desenvolvedores do Google é útil.

Markdown

Com algumas exceções, o TensorFlow usa uma sintaxe Markdown semelhante ao GitHub Flavored Markdown (GFM). Esta seção explica as diferenças entre a sintaxe Markdown do GFM e o Markdown usado na documentação do TensorFlow.

Escreva sobre código

Menções de código em linha

Coloque `backticks` em torno dos seguintes símbolos quando os utilizar no texto:

  • Nomes dos argumentos: `input` , `x` , `tensor`
  • Nomes dos tensores retornados: `output` , `idx` , `out`
  • Tipos de dados: `int32` , `float` , `uint8`
  • Outras referências a nomes de operações no texto: `list_diff()` , `shuffle()`
  • Nomes das classes: `tf.Tensor` , `Strategy`
  • Nome do arquivo: `image_ops.py` , `/path_to_dir/file_name`
  • Expressões ou condições matemáticas: `-1-input.dims() <= dim <= input.dims()`

Blocos de código

Use três crases (`) para abrir e fechar um bloco de código. Opcionalmente, especifique a linguagem de programação após o primeiro grupo de crases, por exemplo:


```python
# some python code here
```

Utilize links relativos entre arquivos em um mesmo repositório do GitHub. Inclua a extensão do arquivo.

Por exemplo, este arquivo que você está lendo é do repositório https://github.com/tensorflow/docs . Portanto, ele pode usar caminhos relativos para criar links para outros arquivos no mesmo repositório, como neste exemplo:

  • [Basics](../../guide/basics.ipynb) produz Basics .

Essa é a abordagem preferida porque, dessa forma, os links em tensorflow.org , GitHub e Colab funcionam corretamente. Além disso, o leitor permanece no mesmo site ao clicar em um link.

Para links para arquivos que não estão no repositório atual, use links Markdown padrão com o URI completo. Dê preferência ao URI do tensorflow.org , se disponível.

Para criar um link para o código-fonte, use um link que comece com https://www.github.com/tensorflow/tensorflow/blob/master/ , seguido pelo nome do arquivo a partir da raiz do GitHub.

Ao criar links externos a partir de tensorflow.org , inclua um `` no link Markdown para que o símbolo de "link externo" seja exibido.

  • [GitHub](https://github.com/tensorflow/docs) produz GitHub

Não inclua parâmetros de consulta URI no link:

  • Utilize: https://www.tensorflow.org/guide/data
  • Nota: https://www.tensorflow.org/guide/data?hl=en

Imagens

As orientações da seção anterior referem-se a links para páginas. Imagens são tratadas de forma diferente.

Geralmente, você não deve incluir imagens no seu repositório. Em vez disso, adicione a equipe do TensorFlow-Docs ao seu PR e peça para que eles hospedem as imagens em tensorflow.org . Isso ajuda a manter o tamanho do seu repositório reduzido.

Se você enviar imagens para o seu repositório, observe que alguns sistemas não lidam com caminhos relativos para imagens. Prefira usar uma URL completa apontando para a localização final da imagem em tensorflow.org .

Os links da API são convertidos quando o site é publicado. Para criar um link para a página de referência da API de um símbolo, coloque o caminho do símbolo entre crases (`):

Caminhos completos são ligeiramente preferidos, exceto para caminhos longos. Os caminhos podem ser abreviados removendo os componentes iniciais. Caminhos parciais serão convertidos em links se:

  • Existe pelo menos um ponto ( . no caminho, e
  • O percurso parcial é único dentro do projeto.

Os caminhos da API são vinculados para cada projeto com uma API Python publicada em tensorflow.org . Você pode facilmente criar links para vários subprojetos a partir de um único arquivo, envolvendo os nomes da API com crases (`). Por exemplo:

Para símbolos com múltiplos aliases de caminho, há uma ligeira preferência pelo caminho que corresponde à página da API em tensorflow.org . Todos os aliases redirecionarão para a página correta.

Matemática em Markdown

Você pode usar o MathJax no TensorFlow ao editar arquivos Markdown, mas observe o seguinte:

  • O MathJax é renderizado corretamente em tensorflow.org .
  • O MathJax não é exibido corretamente no GitHub.
  • Essa notação pode ser intimidante para desenvolvedores não familiarizados.
  • Para manter a consistência, o tensorflow.org segue as mesmas regras do Jupyter/Colab.

Use $$ em torno de um bloco de MathJax:

$$
E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2
$$

\[ E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2 \]

Envolva expressões MathJax embutidas com $ ... $ :


This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $

Este é um exemplo de uma expressão MathJax embutida: \( 2 \times 2 = 4 \)

Os delimitadores \\( ... \\) também funcionam para matemática em linha, mas a forma $ às vezes é mais legível.

Estilo de prosa

Se você for escrever ou editar partes substanciais da documentação narrativa, leia o Guia de Estilo de Documentação para Desenvolvedores do Google .

Princípios de um bom estilo

  • Verifique a ortografia e a gramática das suas contribuições. A maioria dos editores inclui um corretor ortográfico ou disponibiliza um plugin de verificação ortográfica. Você também pode colar seu texto em um documento do Google ou outro software de edição de texto para uma verificação ortográfica e gramatical mais completa.
  • Use uma linguagem informal e amigável. Escreva a documentação do TensorFlow como se estivesse conversando com outra pessoa individualmente. Adote um tom acolhedor no artigo.
  • Evite ressalvas, opiniões e julgamentos de valor. Palavras como "facilmente", "apenas" e "simples" carregam pressupostos. Algo pode parecer fácil para você, mas ser difícil para outra pessoa. Tente evitá-las sempre que possível.
  • Use frases simples e diretas, sem jargões complicados. Frases compostas, cadeias de orações e expressões idiomáticas específicas de cada local podem dificultar a compreensão e a tradução do texto. Se uma frase puder ser dividida em duas, provavelmente deve ser. Evite ponto e vírgula. Use listas com marcadores quando apropriado.
  • Forneça contexto. Não use abreviações sem explicá-las. Não mencione projetos que não sejam do TensorFlow sem fornecer links para eles. Explique por que o código foi escrito dessa forma.

Guia de utilização

Operações

Em arquivos Markdown, use # ⇒ em vez de um único sinal de igual quando quiser mostrar o que uma operação retorna.

# 'input' is a tensor of shape [2, 3, 5]
tf.expand_dims(input, 0)  # ⇒ [1, 2, 3, 5]

Nos notebooks, exiba o resultado em vez de adicionar um comentário (se a última expressão em uma célula do notebook não estiver atribuída a uma variável, ela será exibida automaticamente).

Na documentação de referência da API, prefira usar o doctest para exibir os resultados.

Tensores

Quando você estiver falando sobre um tensor em geral, não use letra maiúscula na palavra "tensor" . Quando estiver falando sobre o objeto específico que é fornecido ou retornado por uma operação, então você deve usar letra maiúscula na palavra "Tensor" e adicionar crases ao redor dela, porque você está se referindo a um objeto Tensor .

Não use a palavra "Tensores " (plural) para descrever múltiplos objetos Tensor , a menos que você esteja realmente se referindo a um objeto Tensors . Em vez disso, diga "uma lista (ou coleção) de objetos Tensor ".

Use a palavra " forma" para detalhar os eixos de um tensor e mostre a forma entre colchetes com crases (`). Por exemplo:


If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.

Como mencionado acima, prefira "eixo" ou "índice" a "dimensão" ao se referir aos elementos da forma de um Tensor . Caso contrário, é fácil confundir "dimensão" com a dimensão de um espaço vetorial. Um "vetor tridimensional" possui um único eixo de comprimento 3.