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
```
Links em Markdown e notebooks
Links entre arquivos em um repositório
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.
links externos
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 .
Links para a documentação da API
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:
-
`tf.data.Dataset`
produztf.data.Dataset
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:
-
`tf.metrics`
,`tf_agents.metrics`
,`text.metrics`
produz:tf.metrics
,tf_agents.metrics
,text.metrics
.
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.