Guia de estilo de documentação do TensorFlow

Melhores práticas

  • Concentre-se na intenção e no público do usuário.
  • Use palavras do dia a dia e mantenha frases curtas.
  • Use construção, redação e letras maiúsculas consistentes.
  • Use títulos e listas para facilitar a digitalização dos seus documentos.
  • O Guia de estilo do Google Developer Docs é útil.

Remarcação

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 do GFM Markdown e o Markdown usado para a documentação do TensorFlow.

Escreva sobre código

Menções embutidas de código

Coloque `backticks` em torno dos seguintes símbolos quando usados ​​no texto:

  • Nomes de argumentos: `input` , `x` , `tensor`
  • Nomes de tensores retornados: `output` , `idx` , `out`
  • Tipos de dados: `int32` , `float` , `uint8`
  • Referência de outros nomes de operações no texto: `list_diff()` , `shuffle()`
  • Nomes de 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
```

Use links relativos entre arquivos em um único repositório 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 vincular a outros arquivos no mesmo repositório como este:

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

Esta é a abordagem preferida porque desta forma todos os links em tensorflow.org , GitHub e Colab funcionam. Além disso, o leitor permanece no mesmo site quando clica 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. Prefira vincular ao URI tensorflow.org se estiver disponível.

Para vincular ao código-fonte, use um link começando com https://www.github.com/tensorflow/tensorflow/blob/master/ , seguido pelo nome do arquivo começando na raiz do GitHub.

Ao vincular tensorflow.org , inclua um `` no link Markdown para que o símbolo de "link externo" seja mostrado.

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

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

  • Use: <a href="https://www.tensorflow.org/guide/data">https://www.tensorflow.org/guide/data</a>
  • Não: <a href="https://www.tensorflow.org/guide/data?hl=en">https://www.tensorflow.org/guide/data?hl=en</a>

Imagens

O conselho da seção anterior é para links para páginas. As imagens são tratadas de maneira diferente.

Geralmente, você não deve fazer check-in de imagens e, em vez disso, adicionar a equipe TensorFlow-Docs ao seu PR e pedir que hospedem as imagens em tensorflow.org . Isso ajuda a manter o tamanho do seu repositório baixo.

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

Os links da API são convertidos quando o site é publicado. Para vincular à página de referência da API de um símbolo, coloque o caminho do símbolo entre crases:

Caminhos completos são levemente preferidos, exceto para caminhos longos. Os caminhos podem ser abreviados eliminando os componentes principais do caminho. Caminhos parciais serão convertidos em links se:

  • Existe pelo menos um . no caminho, e
  • O caminho 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 vincular facilmente vários subprojetos a partir de um único arquivo agrupando os nomes da API com crases. Por exemplo:

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

Matemática em Markdown

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

  • MathJax é renderizado corretamente em tensorflow.org .
  • MathJax não é renderizado corretamente no GitHub.
  • Essa notação pode ser desanimadora para desenvolvedores desconhecidos.
  • Para consistência, 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 embutida, mas o formulário $ à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 do desenvolvedor do Google .

Princípios do bom estilo

  • Verifique a ortografia e a gramática de suas contribuições. A maioria dos editores inclui um corretor ortográfico ou tem um plugin de verificação ortográfica disponível. Você também pode colar seu texto em um Documento Google ou outro software de documento para uma verificação ortográfica e gramatical mais robusta.
  • Use uma voz casual e amigável. Escreva a documentação do TensorFlow como uma conversa, como se você estivesse conversando com outra pessoa individualmente. Use um tom de apoio no artigo.
  • Evite isenções de responsabilidade, opiniões e julgamentos de valor. Palavras como “facilmente”, “apenas” e “simples” estão carregadas de suposições. Algo pode parecer fácil para você, mas será difícil para outra pessoa. Tente evitá-los sempre que possível.
  • Use frases simples e diretas, sem jargões complicados. Frases compostas, cadeias de cláusulas e expressões idiomáticas específicas do local podem dificultar a compreensão e a tradução do texto. Se uma frase pode ser dividida em duas, provavelmente deveria. Evite ponto e vírgula. Use listas com marcadores quando apropriado.
  • Forneça contexto. Não use abreviaturas sem explicá-las. Não mencione projetos que não sejam do TensorFlow sem vincular a eles. Explique por que o código foi escrito dessa maneira.

Guia de uso

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 cadernos, exiba o resultado em vez de adicionar um comentário (se a última expressão em uma célula do caderno não for atribuída a uma variável, ela será exibida automaticamente).

Nos documentos de referência da API, prefira usar doctest para mostrar resultados.

Tensores

Quando você estiver falando sobre um tensor em geral, não coloque a palavra tensor em maiúscula. Ao falar sobre o objeto específico fornecido ou retornado de uma operação, você deve colocar a palavra Tensor em maiúscula e adicionar crases ao redor dela, porque está falando sobre um objeto Tensor .

Não use a palavra Tensores (plural) para descrever vários objetos Tensor , a menos que você realmente esteja falando sobre 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 acima, prefira "eixo" ou "índice" a "dimensão" ao falar sobre os 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 com comprimento 3.