Contribua com a documentação da API TensorFlow

Strings de documentos testáveis

O TensorFlow usa o DocTest para testar trechos de código em docstrings do Python. O snippet deve ser um código Python executável. Para habilitar o teste, coloque a linha com >>> (três colchetes à esquerda). Por exemplo, aqui está um trecho da função tf.concat no arquivo de origem array_ops.py :

def concat(values, axis, name="concat"):
  """Concatenates tensors along one dimension.
  ...

  >>> t1 = [[1, 2, 3], [4, 5, 6]]
  >>> t2 = [[7, 8, 9], [10, 11, 12]]
  >>> concat([t1, t2], 0)
  <tf.Tensor: shape=(4, 3), dtype=int32, numpy=
  array([[ 1,  2,  3],
         [ 4,  5,  6],
         [ 7,  8,  9],
         [10, 11, 12]], dtype=int32)>

  <... more description or code snippets ...>

  Args:
    values: A list of `tf.Tensor` objects or a single `tf.Tensor`.
    axis: 0-D `int32` `Tensor`.  Dimension along which to concatenate. Must be
      in the range `[-rank(values), rank(values))`. As in Python, indexing for
      axis is 0-based. Positive axis in the rage of `[0, rank(values))` refers
      to `axis`-th dimension. And negative axis refers to `axis +
      rank(values)`-th dimension.
    name: A name for the operation (optional).

    Returns:
      A `tf.Tensor` resulting from concatenation of the input tensors.
  """

  <code here>

Para avaliar a qualidade da documentação de referência, consulte a seção de exemplo do conselho do TensorFlow 2 API Docs . (Esteja ciente de que o Task Tracker nesta folha não está mais em uso.)

Torne o código testável com DocTest

Atualmente, muitas docstrings usam acentos graves (```) para identificar o código. Para tornar o código testável com DocTest:

Remova os acentos graves (```) e use os colchetes esquerdos (>>>) na frente de cada linha. Use (...) na frente de linhas continuadas.
Adicione uma nova linha para separar os trechos do DocTest do texto Markdown para renderizar corretamente no tensorflow.org.

Personalizações

O TensorFlow usa algumas personalizações na lógica doctest integrada:

Ele não compara valores float como texto: Os valores float são extraídos do texto e comparados usando allclose com tolerâncias liberais atol e rtol . Isso permite :
- Documentos mais claros - Os autores não precisam incluir todas as casas decimais.
- Testes mais robustos - As alterações numéricas na implementação subjacente nunca devem causar a falha de um doctest.
Ele só verifica a saída se o autor incluir a saída de uma linha. Isso permite documentos mais claros porque os autores geralmente não precisam capturar valores intermediários irrelevantes para evitar que sejam impressos.

Considerações de Docstring

Geral : O objetivo do doctest é fornecer documentação e confirmar que a documentação funciona. Isso é diferente do teste de unidade. Então:
- Mantenha exemplos simples.
- Evite saídas longas ou complicadas.
- Use números redondos, se possível.
Formato de saída : a saída do snippet precisa estar diretamente abaixo do código que está gerando a saída. Além disso, a saída na docstring deve ser exatamente igual à saída após a execução do código. Veja o exemplo acima. Além disso, confira esta parte na documentação do DocTest. Se a saída exceder o limite de 80 linhas, você poderá colocar a saída extra na nova linha e o DocTest a reconhecerá. Por exemplo, veja os blocos de várias linhas abaixo.
Globals : Os `tf` , np e os estão sempre disponíveis no DocTest do TensorFlow.
Use símbolos : No DocTest você pode acessar diretamente os símbolos definidos no mesmo arquivo. Para usar um símbolo que não está definido no arquivo atual, use a API pública tf.xxx do tf.xxx em vez de xxx . Como você pode ver no exemplo abaixo, `random.normal` é acessado via `tf.random.normal` . Isso ocorre porque `random.normal` não é visível em NewLayer .
```
def NewLayer():
  """This layer does cool stuff.

  Example usage:

  >>> x = tf.random.normal((1, 28, 28, 3))
  >>> new_layer = NewLayer(x)
  >>> new_layer
  <tf.Tensor: shape=(1, 14, 14, 3), dtype=int32, numpy=...>
  """
```
Valores de ponto flutuante : o doctest do TensorFlow extrai valores flutuantes das strings de resultado e compara usando np.allclose com tolerâncias razoáveis ( atol=1e-6 , rtol=1e-6 ). Dessa forma, os autores não precisam se preocupar com docstrings excessivamente precisas causando falhas devido a problemas numéricos. Basta colar o valor esperado.

Saída não determinística : Use reticências( ... ) para as partes incertas e o DocTest ignorará essa substring.

x = tf.random.normal((1,))
print(x)
    <tf.Tensor: shape=(1,), dtype=float32, numpy=..., dtype=float32)>

Blocos de várias linhas : DocTest é rigoroso sobre a diferença entre uma instrução única e uma instrução de várias linhas. Observe o uso de (...) abaixo:
```
if x > 0:
  print("X is positive")
model.compile(
  loss="mse",
  optimizer="adam")
    
```

Exceções : os detalhes da exceção são ignorados, exceto a exceção que é gerada. Veja isto para mais detalhes.

np_var = np.array([1, 2])
tf.keras.backend.is_keras_tensor(np_var)
    Traceback (most recent call last):

    ValueError: Unexpectedly found an instance of type `<class 'numpy.ndarray'>`.

Use uma cópia local do projeto de tf-doctest.

Algumas APIs no TensorFlow vêm de um projeto externo:

tf.estimator (de tensorflow_estimator )
tf.summary tensorboard )
tf.keras.preprocessing (de keras-preprocessing )

Se você estiver trabalhando em um projeto externo ou em APIs do TensorFlow hospedadas em um projeto externo, essas instruções não funcionarão a menos que esse projeto tenha sua própria cópia local de tf_doctest e você use essa cópia em vez da do TensorFlow.

Por exemplo: tf_estimator_doctest.py .

Teste em sua máquina local

Existem duas maneiras de testar o código na docstring localmente:

Se você estiver apenas alterando a docstring de uma classe/função/método, poderá testá-la passando o caminho desse arquivo para tf_doctest.py . Por exemplo:
```
python tf_doctest.py --file=<file_path>
```
Isso o executará usando sua versão instalada do TensorFlow. Para ter certeza de que você está executando o mesmo código que está testando:
- Use uma instalação de pip tf-nightly atualizada pip install -U tf-nightly
- Rebase sua solicitação de pull em um pull recente do branch master do TensorFlow .
Se você estiver alterando o código e a docstring de uma classe/função/método, precisará compilar o TensorFlow a partir do código-fonte . Depois de configurar para compilar a partir do código-fonte, você pode executar os testes:
```
bazel run //tensorflow/tools/docs:tf_doctest
```
ou
```
bazel run //tensorflow/tools/docs:tf_doctest -- --module=ops.array_ops
```
O --module é relativo a tensorflow.python .