TensorFlow 문서 스타일 가이드

모범 사례

  • 사용자 의도와 대상 고객에 집중하세요.
  • 일상적인 단어를 사용하고 문장을 간결하게 하세요.
  • 문장 구조, 단어 선택, 대문자 사용에 일관성을 유지하십시오.
  • 제목과 목록을 사용하여 문서를 더 쉽게 훑어볼 수 있도록 하세요.
  • Google 개발자 문서 스타일 가이드가 도움이 됩니다.

가격 인하

몇 가지 예외를 제외하고, TensorFlow는 GitHub Flavored Markdown (GFM)과 유사한 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) Basics를 생성합니다.

이 방법이 선호되는 이유는 tensorflow.org , GitHub 및 Colab 의 링크가 모두 제대로 작동하기 때문입니다. 또한, 사용자는 링크를 클릭해도 같은 사이트에 머무르게 됩니다.

현재 저장소에 없는 파일에 대한 링크의 경우, 전체 URI를 사용하는 표준 마크다운 링크를 사용하십시오. 가능하면 tensorflow.org URI로 링크하는 것이 좋습니다.

소스 코드에 연결하려면 https://www.github.com/tensorflow/tensorflow/blob/master/ 로 시작하는 링크 뒤에 GitHub 루트 디렉토리부터 시작하는 파일 이름을 입력하세요.

tensorflow.org 에서 외부 링크로 연결할 때는 마크다운 링크에 ``를 포함하여 "외부 링크" 기호가 표시되도록 하세요.

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

링크에 URI 쿼리 매개변수를 포함하지 마십시오.

  • 다음 링크를 참조하세요: https://www.tensorflow.org/guide/data
  • 참고: https://www.tensorflow.org/guide/data?hl=en

이미지

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

일반적으로 이미지를 커밋하지 말고, 대신 TensorFlow-Docs 팀을 PR에 추가하여 tensorflow.org 에 이미지를 호스팅하도록 요청하는 것이 좋습니다. 이렇게 하면 저장소 크기를 줄이는 데 도움이 됩니다.

저장소에 이미지를 제출할 경우, 일부 시스템에서는 이미지에 대한 상대 경로를 지원하지 않으므로, tensorflow.org 에서 이미지가 최종적으로 위치할 곳을 가리키는 전체 URL을 사용하는 것이 좋습니다.

사이트가 게시될 때 API 링크가 변환됩니다. 심볼의 API 참조 페이지로 연결하려면 심볼 경로를 백틱(`)으로 묶으세요.

긴 경로를 제외하고는 전체 경로가 약간 더 선호됩니다. 경로의 앞부분을 생략하면 경로를 축약할 수 있습니다. 다음과 같은 경우 부분 경로는 링크로 변환됩니다.

  • 경로에는 적어도 하나의 마침표(.)가 있습니다 .
  • 해당 부분 경로는 프로젝트 내에서 유일합니다.

tensorflow.org 에 게시된 Python API를 사용하는 모든 프로젝트에 대해 API 경로가 링크되어 있습니다. API 이름을 백틱(`)으로 묶으면 하나의 파일에서 여러 하위 프로젝트에 쉽게 링크할 수 있습니다. 예를 들면 다음과 같습니다.

경로 별칭이 여러 개인 심볼의 경우, tensorflow.org 의 API 페이지와 일치하는 경로가 약간 우선적으로 사용됩니다. 모든 별칭은 올바른 페이지로 리디렉션됩니다.

Markdown에서 수학

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'라는 단어를 대문자로 쓰고 백틱(`)으로 묶어야 합니다. 이는 해당 객체 Tensor 객체임을 나타내기 때문입니다.

여러 개의 Tensor 객체를 설명할 때, 실제로 하나의 Tensors 객체를 가리키는 경우가 아니라면 "Tensors "(복수형)라는 단어를 사용하지 마세요. 대신 " Tensor 객체들의 목록(또는 컬렉션)"이라고 표현하세요.

텐서의 축을 자세히 설명할 때는 ' shape' 라는 단어를 사용하고, 그 모양을 대괄호 안에 백틱(`)으로 묶어 표시하세요. 예를 들면 다음과 같습니다.


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인 단일 축을 가집니다.