TensorFlow 문서 스타일 가이드

모범 사례

  • 사용자 의도와 청중에 초점을 맞춥니다.
  • 일상적인 단어를 사용하고 문장은 짧게 유지하세요.
  • 일관된 문장 구성, 표현, 대문자 사용을 사용하세요.
  • 제목과 목록을 사용하면 문서를 더 쉽게 스캔할 수 있습니다.
  • Google 개발자 문서 스타일 가이드가 도움이 됩니다.

가격 인하

몇 가지 예외를 제외하고 TensorFlow는 GFM( GitHub Flavored Markdown )과 유사한 Markdown 구문을 사용합니다. 이 섹션에서는 GFM Markdown 구문과 TensorFlow 문서에 사용되는 Markdown 간의 차이점을 설명합니다.

코드에 대해 쓰기

코드의 인라인 언급

텍스트에 사용될 때 다음 기호 주위에 `backticks` 넣으세요.

  • 인수 이름: `input` , `x` , `tensor`
  • 반환된 텐서 이름: `output` , `idx` , `out`
  • 데이터 유형: `int32` , `float` , `uint8`
  • 텍스트의 다른 작업 이름 참조: `list_diff()` , `shuffle()`
  • 클래스 이름: `tf.Tensor` , `Strategy`
  • 파일 이름: `image_ops.py` , `/path_to_dir/file_name`
  • 수학 표현식 또는 조건: `-1-input.dims() <= dim <= input.dims()`

코드 블록

세 개의 백틱을 사용하여 코드 블록을 열고 닫습니다. 선택적으로 첫 번째 역따옴표 그룹 뒤에 프로그래밍 언어를 지정합니다. 예를 들면 다음과 같습니다.


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

단일 GitHub 저장소에 있는 파일 간의 상대 링크를 사용합니다. 파일 확장자를 포함합니다.

예를 들어, 읽고 있는 이 파일은 https://github.com/tensorflow/docs 저장소에서 가져온 것입니다. 따라서 다음과 같이 상대 경로를 사용하여 동일한 저장소에 있는 다른 파일에 연결할 수 있습니다.

  • [Basics](../../guide/basics.ipynb) 기본 을 생성합니다.

이는 tensorflow.org , GitHub 및 Colab 의 링크가 모두 작동하기 때문에 선호되는 접근 방식입니다. 또한 독자가 링크를 클릭하면 동일한 사이트에 유지됩니다.

현재 저장소에 없는 파일에 대한 링크의 경우 전체 URI가 포함된 표준 Markdown 링크를 사용하세요. 가능하다면 tensorflow.org URI에 연결하는 것이 좋습니다.

소스 코드에 연결하려면 https://www.github.com/tensorflow/tensorflow/blob/master/ 로 시작하는 링크와 GitHub 루트에서 시작하는 파일 이름을 사용하세요.

tensorflow.org 에서 링크할 때 "외부 링크" 기호가 표시되도록 Markdown 링크에 ``를 포함하세요.

  • [GitHub](https://github.com/tensorflow/docs) GitHub를 생성합니다.

링크에 URI 쿼리 매개변수를 포함하지 마세요.

  • 사용: <a href="https://www.tensorflow.org/guide/data">https://www.tensorflow.org/guide/data</a>
  • 아님: <a href="https://www.tensorflow.org/guide/data?hl=en">https://www.tensorflow.org/guide/data?hl=en</a>

이미지

이전 섹션의 조언은 페이지 링크에 대한 것입니다. 이미지는 다르게 처리됩니다.

일반적으로 이미지를 체크인하지 말고 대신 TensorFlow-Docs 팀을 PR에 추가하고 tensorflow.org 에서 이미지를 호스팅하도록 요청해야 합니다. 이렇게 하면 저장소 크기를 줄이는 데 도움이 됩니다.

저장소에 이미지를 제출하는 경우 일부 시스템에서는 이미지에 대한 상대 경로를 처리하지 않는다는 점에 유의하세요. tensorflow.org 에서 이미지의 최종 위치를 가리키는 전체 URL을 사용하는 것이 좋습니다.

API 링크는 사이트가 게시될 때 변환됩니다. 기호의 API 참조 페이지에 연결하려면 기호 경로를 백틱으로 묶습니다.

긴 경로를 제외하면 전체 경로가 약간 선호됩니다. 선행 경로 구성 요소를 삭제하여 경로를 축약할 수 있습니다. 다음과 같은 경우 부분 경로가 링크로 변환됩니다.

  • 가 하나 이상 있습니다 . 경로에서, 그리고
  • 부분 경로는 프로젝트 내에서 고유합니다.

API 경로는 tensorflow.org 에 게시된 Python API를 사용하여 모든 프로젝트에 연결됩니다. API 이름을 백틱으로 묶어 단일 파일에서 여러 하위 프로젝트에 쉽게 연결할 수 있습니다. 예를 들어:

여러 경로 별칭이 있는 기호의 경우 tensorflow.org 의 API 페이지와 일치하는 경로가 약간 선호됩니다. 모든 별칭은 올바른 페이지로 리디렉션됩니다.

마크다운의 수학

Markdown 파일을 편집할 때 TensorFlow 내에서 MathJax를 사용할 수 있지만 다음 사항에 유의하세요.

  • MathJax는 tensorflow.org 에서 올바르게 렌더링됩니다.
  • MathJax는 GitHub에서 제대로 렌더링되지 않습니다.
  • 이 표기법은 익숙하지 않은 개발자에게는 불쾌할 수 있습니다.
  • 일관성을 위해 tensorflow.org는 Jupyter/Colab과 동일한 규칙을 따릅니다.

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 \]

인라인 MathJax 표현식을 $ ... $ 로 래핑합니다.


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

이것은 인라인 MathJax 표현식의 예입니다: \( 2 \times 2 = 4 \)

\\( ... \\) 구분 기호는 인라인 수학에서도 작동하지만 $ 형식이 더 읽기 쉬운 경우도 있습니다.

산문 스타일

설명 문서의 상당 부분을 작성하거나 편집하려면 Google 개발자 문서 스타일 가이드를 읽어보세요.

좋은 스타일의 원칙

  • 기여한 내용의 철자와 문법을 확인하세요. 대부분의 편집기에는 맞춤법 검사기가 포함되어 있거나 사용 가능한 맞춤법 검사 플러그인이 있습니다. 더욱 강력한 철자법 및 문법 검사를 위해 텍스트를 Google Docs나 기타 문서 소프트웨어에 붙여넣을 수도 있습니다.
  • 편안하고 친근한 목소리를 사용하세요. 마치 다른 사람과 일대일로 대화하는 것처럼 대화처럼 TensorFlow 문서를 작성하세요. 기사에서 지지적인 어조를 사용하십시오.
  • 면책 조항, 의견, 가치 판단을 피하십시오. "쉽게", "그냥", "단순"과 같은 단어에는 가정이 포함되어 있습니다. 당신에게는 쉬운 일이 다른 사람에게는 어려울 수도 있습니다. 가능할 때마다 이러한 것을 피하십시오.
  • 복잡한 전문 용어 없이 간단하고 요점이 분명한 문장을 사용하세요. 복합 문장, 일련의 절, 위치별 관용구는 텍스트를 이해하고 번역하기 어렵게 만들 수 있습니다. 문장을 두 개로 나눌 수 있다면 아마도 그래야 할 것입니다. 세미콜론을 피하세요. 적절한 경우 글머리 기호 목록을 사용하십시오.
  • 맥락을 제공하세요. 설명하지 않고 약어를 사용하지 마십시오. TensorFlow가 아닌 ​​프로젝트에 연결하지 않고 언급하지 마세요. 코드가 왜 이렇게 작성되었는지 설명해보세요.

이용안내

운영

마크다운 파일에서 작업이 반환하는 내용을 표시하려면 단일 등호 대신 # ⇒ 사용하세요.

# 'input' is a tensor of shape [2, 3, 5]
tf.expand_dims(input, 0)  # ⇒ [1, 2, 3, 5]

노트북에서 코멘트를 추가하는 대신 결과를 표시합니다. (노트북 셀의 마지막 표현식이 변수에 할당되지 않은 경우 자동으로 표시됩니다.)

API 참조 문서에서는 결과를 표시하기 위해 doctest를 사용하는 것을 선호합니다.

텐서

일반적으로 텐서에 대해 이야기할 때 텐서 라는 단어를 대문자로 쓰지 마십시오. 작업에 제공되거나 작업에서 반환되는 특정 개체에 대해 이야기할 때는 Tensor 라는 단어를 대문자로 쓰고 그 주위에 백틱을 추가해야 합니다. 왜냐하면 Tensor 개체에 대해 이야기하고 있기 때문입니다.

실제로 Tensors 객체에 대해 이야기하는 것이 아니라면 여러 Tensor 객체를 설명하기 위해 Tensor (복수형)라는 단어를 사용하지 마세요. 대신 " Tensor 객체 목록(또는 컬렉션)"이라고 말하세요.

텐서의 축을 자세히 설명하려면 모양이라는 단어를 사용하고 백틱과 함께 대괄호 안에 모양을 표시하세요. 예를 들어:


If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.

위와 같이 Tensor 도형의 요소에 관해 말할 때 "차원"보다 "축"이나 "인덱스"를 선호하세요. 그렇지 않으면 "차원"을 벡터 공간의 차원과 혼동하기 쉽습니다. "3차원 벡터"는 길이가 3인 단일 축을 갖습니다.