Guia de estilo de documentação do TensorFlow

Melhores Práticas

  • Concentre-se na intenção do usuário e no público.
  • Use palavras do dia-a-dia e mantenha as frases curtas.
  • Use construção consistente de frases, redação e uso de maiúsculas.
  • Use títulos e listas para facilitar a verificação de 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 o código

Menções inline de código

Coloque `backticks` ao redor dos seguintes símbolos quando usados ​​no texto:

  • Nomes dos argumentos: `input` , `x` , `tensor`
  • Nomes de tensores retornados: `output` , `idx` , `out`
  • Tipos de dados: `int32` , `float` , `uint8`
  • Outros nomes de operações referenciados no texto: `list_diff()` , `shuffle()`
  • Nomes de classe: `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 acentos graves para abrir e fechar um bloco de código. Opcionalmente, especifique a linguagem de programação após o primeiro grupo de acentos graves, por exemplo:


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

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

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

Esta é a abordagem preferida porque desta forma 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 fora de tensorflow.org , inclua um {:.external} no link Markdown para que o símbolo de "link externo" seja mostrado.

  • [GitHub](https://github.com/tensorflow/docs){:.external} produz o GitHub

Não inclua parâmetros de consulta de 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 na seção anterior é para links para páginas. As imagens são tratadas de forma diferente.

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

Se você enviar imagens para 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 eventual 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 acentos graves:

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

  • Há 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 a vários subprojetos a partir de um único arquivo envolvendo os nomes da API com acentos graves. 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 o MathJax no TensorFlow ao editar arquivos Markdown, mas observe o seguinte:

  • MathJax renderiza 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 inline com $ ... $ :


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

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

Os delimitadores \\( ... \\) também funcionam para matemática embutida, 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 da documentação do desenvolvedor do Google .

Princípios do bom estilo

  • Verifique a ortografia e gramática em suas contribuições. A maioria dos editores inclui um corretor ortográfico ou tem um plug-in de verificação ortográfica disponível. Você também pode colar seu texto em um Google Doc ou outro software de documentos 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 estivesse conversando com outra pessoa pessoalmente. Use um tom de apoio no artigo.
  • Evite isenções de responsabilidade, opiniões e julgamentos de valor. Palavras como "facilmente", "apenas" e "simples" sã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ão complicado. 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 de 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 vincular a eles. Explique por que o código está escrito do jeito que está.

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]

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

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

Tensores

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

Não use a palavra tensores (plural) para descrever vários objetos Tensors , a menos que você realmente esteja falando sobre um objeto Tensor . 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 acentos graves. 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" em vez de "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" tem um único eixo com comprimento 3.