TensorFlow API 설명서에 기여하기

테스트 가능한 docstring

TensorFlow는 DocTest를 사용하여 Python docstring에서 코드 조각을 테스트합니다. 이 조각은 실행 가능한 Python 코드여야 합니다. 테스트가 가능하도록 >>>(세 개의 왼쪽 꺾쇠 괄호)가 들어간 줄을 추가하세요. 예를 들어, 다음은 array_ops.py 소스 파일의 tf.concat 함수에서 발췌한 내용입니다.

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>

참고: TensorFlow DocTest는 TensorFlow 2 및 Python 3을 사용합니다.

DocTest로 코드를 테스트 가능하게 만들기

현재, 많은 docstring에서 백틱 (```)을 사용하여 코드를 식별합니다. DocTest로 코드를 테스트할 수 있게 하려면 다음과 같이 합니다.

  • 백틱(```)을 제거하고 각 줄 앞에 왼쪽 꺾쇠 괄호(>>>)를 사용합니다. 연속된 줄 앞에 (...)를 사용합니다.
  • tensorflow.org에서 올바르게 렌더링하려면 Markdown 텍스트와 DocTest 조각을 구분하는 새로운 줄을 추가합니다.

사용자 정의

TensorFlow는 내장된 doctest 로직에 몇 가지 사용자 정의를 사용합니다.

  • 부동 소수점 값을 텍스트로 비교하지 않습니다. 부동 소수점 값은 liberal atolrtol tolerences와 함께 allclose를 사용하여 텍스트에서 추출하고 비교합니다. 그러면 다음과 같은 장점이 있습니다.
    • 더 명확한 문서 - 작성자가 소수 자릿수를 모두 포함할 필요가 없습니다.
    • 보다 강력한 테스트 - 기본 구현의 수치적 변경으로 인해 doctest가 실패하지 않습니다.
  • 작성자가 줄에 대한 출력을 포함하는 경우에만 출력을 확인합니다. 따라서 작성자는 일반적으로 인쇄되지 않도록 관련 없는 중간 값을 캡처할 필요가 없으므로 보다 명확한 문서를 작성할 수 있습니다.

Docstring 고려 사항

  • 전체: doctest의 목표는 문서를 제공하고 문서가 작동하는지 확인하는 것입니다. 이것은 단위 테스트와 다릅니다. 따라서 다음이 권장됩니다.

    • 예제를 간단하게 유지합니다.
    • 길거나 복잡한 출력을 피합니다.
    • 가능하면 올림 숫자를 사용합니다.
  • 출력 형식: 조각의 출력은 출력을 생성하는 코드 바로 아래에 있어야 합니다. 또한 docstring의 출력은 코드가 실행된 후의 출력과 정확히 같아야 합니다. 위의 예를 참조하세요. 또한 DocTest 설명서에서 이 부분을 확인하세요. 출력이 80줄 제한을 초과하면 추가 출력을 새 줄에 넣을 수 있으며 DocTest는 이를 인식합니다. 예를 들어 아래의 여러 줄 블록을 참조하세요.

  • 글로벌: tf, npos 모듈은 TensorFlow의 DocTest에서 항상 사용할 수 있습니다.

  • 기호 사용: DocTest에서 같은 파일에 정의된 기호에 직접 액세스할 수 있습니다. 현재 파일에 정의되지 않은 기호를 사용하려면 xxx 대신 TensorFlow의 공용 API tf.xxx를 사용합니다. 아래 예에서 볼 수 있는 바와 같이 random.normaltf.random.normal을 통해 액세스할 수 있습니다. 그 이유는 random.normalNewLayer에서 보이지 않기 때문입니다.

    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=...>
      “””
    
  • 부동 소수점 값: TensorFlow doctest는 결과 문자열에서 부동 소수점 값을 추출하고 합리적인 허용 오차(atol=1e-6 , rtol=1e-6)로 np.allclose를 사용하여 비교를 수행합니다. 이런 식으로 작성자는 docstring이 지나치게 정밀해 수치 문제로 실패가 발생하는 상황을 걱정할 필요가 없습니다. 간단히 예상 값을 붙여넣기만 하면 됩니다.

  • 비결정적 출력: 불확실한 부분에 생략 부호(...)를 사용하면 DocTest가 해당 하위 문자열을 무시합니다.

    x = tf.random.normal((1,))
    print(x)
        <tf.Tensor: shape=(1,), dtype=float32, numpy=..., dtype=float32)>
        
  • 여러 줄 블록: DocTest는 한 줄과 여러 줄이 있는 문의 차이에 대해 엄격합니다. 아래의 (...) 사용법에 유의하세요.

    if x > 0:
      print("X is positive")
    model.compile(
      loss="mse",
      optimizer="adam")
        
  • 예외: 발생한 예외를 제외하고 예외 세부 사항은 무시됩니다. 자세한 내용은 이 내용을 참조하세요.

    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 &#x27;numpy.ndarray&#x27;>`.
        

로컬 머신에서 테스트하기

docstring에서 코드를 로컬로 테스트하는 방법에는 두 가지가 있습니다.

  • 클래스/함수/메서드의 docstring만 변경하는 경우 해당 파일의 경로를 tf_doctest.py에 전달하여 테스트할 수 있습니다. 예를 들면 다음과 같습니다.

    python tf_doctest.py --file=

    설치된 버전의 TensorFlow를 사용하여 실행이 이루어집니다. 다음과 같이 테스트 중인 코드와 같은 코드가 실행되도록 합니다.

    • 최신 tf-nightly pip install -U tf-nightly를 사용합니다.
    • 풀 요청의 기반을 TensorFlow 마스터 분기의 최근 풀로 재지정합니다.
  • 클래스/함수/메서드의 코드와 docstring을 변경하는 경우, 소스에서 TensorFlow를 빌드해야 합니다. 소스에서 빌드할 준비가 되면 테스트를 실행할 수 있습니다.

    bazel run //tensorflow/tools/docs:tf_doctest

    또는

    bazel run //tensorflow/tools/docs:tf_doctest -- --module=ops.array_ops

    --moduletensorflow.python에 상대적입니다.