docs.md

TensorFlow 문서에 기여하기

TensorFlow는 문서 기여를 환영합니다. 문서를 개선하면 TensorFlow 라이브러리 자체도 개선됩니다. tensorflow.org의 문서는 다음 범주로 분류됩니다.

• API 참조 — API 참조 문서는 TensorFlow source code에 있는 docstrings로 부터 시작되었습니다.

• 설명 문서 -TensorFlow 코드의 일부가 아닌 튜토리얼 , 가이드 및 기타 글입니다. 이 문서는 tensorflow / docs GitHub 저장소에 있습니다.

• 커뮤니티 번역 — 커뮤니타에서 번역한 가이드와 튜토리얼입니다. 모든 커뮤니티 번역은 tensorflow/docs 리포지토리에 있습니다.

일부 TensorFlow 프로젝트 는 일반적으로 docs/ 디렉토리에있는 코드 근처 별도의 저장소에 문서 소스 파일을 보관합니다. 기여하기 위해서는 프로젝트의 CONTRIBUTING.md 파일을 보거나 관리자에게 연락하십시오.

TensorFlow 문서 커뮤니티에 참여하려면 다음과 같이 합니다.

• tensorflow / docs GitHub 저장소를 확인하세요.

• TensorFlow 포럼에서 설명서 태그를 따라가세요.

API 참조

자세한 내용은 TensorFlow API 설명서 기여자 가이드를 참조하세요. 소스 파일을 찾고 심볼의 독스트링을 편집하는 방법을 보여줍니다. ​tensorflow.org의 많은 API 참조 페이지에는 기호가 정의 된 소스 파일에 대한 링크가 포함되어 있습니다. 독스트링은 Markdown을 지원하며 Markdown 미리 보기 프로그램을 사용하여 (대략적으로) 미리 볼 수 있습니다.

버전과 분기

사이트의 API 참조 버전은 기본적으로 안정적인 최신 바이너리로 설정됩니다. 이는 pip install tensorflow 설치된 패키지와 일치합니다.

기본 TensorFlow package는 tensorflow/tensorflow 저장소의 안전한 분기 rX.x로 부터 만들어집니다. 참조 문서는 소스 코드의 Python, C++, and Java를 위한 코드 주석과 독 스트링으로 부터 시작됩니다.

TensorFlow 문서의 이전 버전은 TensorFlow Docs 저장소에서 rX.x 분기 로 제공됩니다. 이러한 분기는 새 버전이 출시 될 때 추가됩니다.

API 문서 빌드하기

참고 :이 단계는 API 독 스트링을 편집하거나 미리 보는 데 필요하지 않으며 tensorflow.org에서 사용되는 HTML을 생성하는 데만 필요합니다.

Python 참조

tensorflow_docs 패키지에는 Python API 참조 문서 용 생성기가 포함되어 있습니다. 설치:

pip install git+https://github.com/tensorflow/docs

TensorFlow 2 참조 문서를 생성하려면 tensorflow/tools/docs/generate2.py 스크립트를 사용하세요.

git clone https://github.com/tensorflow/tensorflow tensorflow
cd tensorflow/tensorflow/tools/docs
pip install tensorflow
python generate2.py --output_dir=/tmp/out

참고 :이 스크립트는 설치된 TensorFlow 패키지를 사용하여 문서를 생성하고 TensorFlow 2.x에서만 작동합니다.

서술 문서

TensorFlow 가이드 및 가이드 는 Markdown 파일 및 대화 형 Jupyter 노트북으로 작성됩니다. Google Colaboratory를 사용하여 브라우저에서 노트북을 실행할 수 있습니다. tensorflow.org 의 내러티브 문서는 tensorflow / docs master 브랜치에서 빌드됩니다. 이전 버전은 rX.x 릴리스 브랜치의 GitHub에서 사용할 수 있습니다.

간단한 변경

Markdown 파일에 대한 간단한 문서 업데이트를 만드는 가장 쉬운 방법은 GitHub의 웹 기반 파일 편집기를 사용하는 것 입니다. 찾아보기 tensorflow / 문서 저장소 약은에 해당하는 마크 다운을 찾을 수 tensorflow.org의 URL 구조. 파일보기의 오른쪽 상단에서 연필 아이콘을 클릭합니다. 파일 편집기를 엽니 다. 파일을 편집 한 다음 새 풀 요청을 제출하십시오.

로컬 Git 리포지토리 설정하기

다중 파일 편집 또는 더 복잡한 업데이트의 경우 로컬 Git 워크 플로를 사용하여 풀 요청을 만드는 것이 좋습니다.

참고 : Git 은 소스 코드의 변경 사항을 추적하는 데 사용되는 오픈 소스 버전 제어 시스템 (VCS)입니다. GitHub 는 Git에서 작동하는 협업 도구를 제공하는 온라인 서비스입니다. GitHub 계정을 설정하고 시작하려면 GitHub 도움말 을 참조하십시오.

다음 Git 단계는 로컬 프로젝트를 처음 설정할 때만 필요합니다.

tensorflow/docs 리포지토리 포크하기

tensorflow / docs GitHub 페이지에서 Fork 버튼을 클릭합니다. GitHub 계정에서 자신의 저장소 사본을 만들 수 있습니다. 분기 된 후에는 업스트림 TensorFlow 저장소를 사용하여 저장소 사본을 최신 상태로 유지할 책임이 있습니다.

리포지토리 복제하기

당신의 원격 리포지토리 username/docs 에서 당신의 로컬 기기로 다운로드 하십시오. 이 곳이 당신이 작얼할 디렉토리 입니다.

git clone [email protected]:<var>username</var>/docs
cd ./docs

최신 상태로 유지하려면 업스트림 리포지토리 추가 (선택 사항)

로컬 리포지토리를 tensorflow/docs 와 동기화 상태로 유지하려면 업스트림 원격을 추가하여 최신 변경 사항을 다운로드하세요.

참고: 기여 전에 당신의 로컬 리포지토리 업데이트를 확인하십시오. 업스트림에 대한 정기적 싱크는 풀 요청시 merge conflict를 줄여줍니다.

다음과 같이 리모트를 추가합니다.

<code class="devsite-terminal">git remote add upstream [email protected]:tensorflow/docs.git</code>

# View remote repos
<code class="devsite-terminal">git remote -v</code>
origin    [email protected]:<var>username</var>/docs.git (fetch)
origin    [email protected]:<var>username</var>/docs.git (push)
upstream  [email protected]:tensorflow/docs.git (fetch)
upstream  [email protected]:tensorflow/docs.git (push)

업데이트하려면 다음과 같이 합니다.

<code class="devsite-terminal">git checkout master</code>
<code class="devsite-terminal">git pull upstream master</code>

<code class="devsite-terminal">git push</code>  # Push changes to your GitHub account (defaults to origin)

GitHub 워크플로

1. 새로운 분기를 만듭니다.

tensorflow/docs 에서 리포지토리를 업데이트 한 후 로컬 마스터 브랜치에서 새 브랜치를 만듭니다.

<code class="devsite-terminal">git checkout -b <var>feature-name</var></code>

<code class="devsite-terminal">git branch</code>  # List local branches
  master
* <var>feature-name</var>

2. 변경을 수행합니다.

좋아하는 편집기에서 파일을 편집하고 TensorFlow 문서 스타일 가이드 를 따르세요.

파일 변경 사항을 커밋합니다.

# View changes
<code class="devsite-terminal">git status</code>  # See which files have changed
<code class="devsite-terminal">git diff</code>    # See changes within files

<code class="devsite-terminal">git add <var>path/to/file.md</var></code>
<code class="devsite-terminal">git commit -m "Your meaningful commit message for the change."</code>

필요에 따라 더 많은 커밋을 추가합니다.

3. 풀 요청을 생성합니다.

로컬 브랜치를 원격 GitHub 저장소 (github.com/ username / docs)에 업로드합니다.

git push

push가 완료된 후, 업스트림 리포지토리에 대한 풀 요청을 자동 제출하는 URL 메세지가 보일것입니다. 그렇지 않다면 tensorflow/docs 리포지토리 혹은 당신의 리포지토리, 깃허브는 당신에게 풀 요청을 해야한다는 것을 알려줄 것입니다.

4. 검토하기

유지 관리자 및 기타 기여자가 귀하의 풀 요청을 검토 할 것입니다. 토론에 참여하고 요청 된 사항을 변경하십시오. 풀 요청이 승인되면 업스트림 TensorFlow 문서 리포지토리에 병합됩니다.

성공: TensorFlow 문서에 대한 변경 사항이 승인되었습니다.

GitHub 리포지토리에서 tensorflow.org 를 업데이트하는 별도의 게시 단계가 있습니다. 일반적으로 변경 사항은 일괄 처리되고 사이트는 정기적으로 업데이트됩니다.

대화형 노트북

GitHub의 웹 기반 파일 편집기를 사용 하여 노트북 JSON 파일을 편집 할 수 있지만 잘못된 JSON으로 인해 파일이 손상 될 수 있으므로 권장하지 않습니다. 풀 요청을 제출하기 전에 노트북을 테스트해야합니다.

Google Colaboratory 작성과 실행이 편한 는 노트북 환경을 만들었습니다. 노트북의 GitHub는 다음의 Colab URL을 통해 노트북에 로딩됩니다.https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb
can be loaded into Google Colab at this URL: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

GitHub에서 노트북을 검색 할 때이 URL 대체를 수행하는 Open in Colab Chrome 확장 프로그램이 있습니다. 상단 버튼은 항상 TensorFlow Docs master 브랜치에 연결되므로 저장소 포크에서 노트북을 열 때 유용합니다.

노트북 형식 지정하기

노트북 서식 도구를 사용하면 Jupyter 노트북 소스 차이를 일관되고 쉽게 검토할 수 있습니다. 노트북 작성 환경은 파일 출력, 들여쓰기, 메타데이터 및 기타 지정되지 않은 필드와 관련하여 차이가 있기 때문입니다. nbfmt는 TensorFlow 문서 Colab 워크플로에 대한 환경 설정과 함께 독자적인 기본값을 사용합니다. 노트북 형식을 지정하려면 TensorFlow 문서 노트북 도구를 설치하고 nbfmt 도구를 실행하세요.

# Install the tensorflow-docs package:
$ python3 -m pip install -U [--user] git+https://github.com/tensorflow/docs

$ python3 -m tensorflow_docs.tools.nbfmt [options] notebook.ipynb [...]

TensorFlow 문서 프로젝트의 경우, 출력 셀이 없는 노트북이 실행되고 테스트됩니다. 저장된 출력 셀이 있는 노트북은 그대로 게시됩니다. nbfmt는 노트북 상태를 유지하고 --remove_outputs 옵션을 사용하여 명시적으로 출력 셀을 제거합니다.

새 노트북을 작성하려면 TensorFlow 문서 노트북 템플릿을 복사하고 편집하세요.

Colab에서 편집하기

Google Colab 환경에서 셀을 두 번 클릭하여 텍스트 및 코드 블록을 편집하십시오. 텍스트 셀은 마크 다운을 사용하며 TensorFlow 문서 스타일 가이드를 따라야합니다.

Colab에서 File > Download .pynb를 이용해 노트북 파일을 다운로드합니다. 이 파일을 자신의 local Git repo에 커밋하고 풀 요청을 보냅니다.

새 노트북을 작성하려면 TensorFlow 노트북 템플리트를 복사하고 편집하십시오.

Colab-GitHub 워크플로

노트북 파일을 다운로드하고 로컬 Git 워크플로를 사용하는 대신 Google Colab에서 직접 분기된 GitHub 리포지토리를 편집하고 업데이트할 수 있습니다.

1. 당신의 Fork username/docs 리포지토리는 새 브랜치 만들기를 위해 GitHub 웹의 UI를 사용합니다.

2. 편집할 노트북 파일로 이동합니다.

3. Google Colab에서 노트북을 엽니 다. URL 스왑 또는 Open in Colab Chrome 확장 프로그램을 사용합니다.

4. Colab에서 노트북을 편집합니다.

5. *File > Save a copy in GitHub...*을 사용하여 Colab에서 리포지토리로 변경 사항을 커밋합니다. 저장 대화 상자는 해당 리포지토리 및 분기에 연결됩니다. 의미 있는 커밋 메시지를 추가합니다.

6. 저장 후, 당신의 리포지토리 혹은tensorflow/docs 리포지토리를 찾기 위해, GitHub는 새로운 풀 요청을 할 것을 알려줍니다.

7. 풀 요청은 관리자가 검토합니다.

성공: TensorFlow 문서에 대한 변경 사항이 승인되었습니다.

번역

TensorFlow 팀은 tensorflow.org에 대한 번역을 제공하기위해 커뮤니티나 업체와 함께합니다. 노트북에 대한 번역이나 다른 기술적인 내용은 tensorflow/docs-l10n GitHub 리포지토리에 있습니다. TensorFlow GitLocalize project를 통해 풀 요청을 제출하시기 바랍니다.

영어 문서는 source-of-truth이며 번역된 문서는 가이드를 따라 최대한 가깝게 작성되어야 합니다. 즉, 번역은 텐서플로우를 사용하는 커뮤니티를 위해 작성되어야 합니다. 만약 영어의 술어, 문단, 스타일, 톤이 다른 언어로 바뀌지 않는다면 읽는 이 에게 적절하도록 번역을 해야합니다.

언어 지원은 사이트 지표 및 수요, 커뮤니티 지원, 영어 능력 , 청중 선호도 및 기타 지표를 포함하되 이에 국한되지 않는 여러 요인에 의해 결정됩니다. 지원되는 각 언어에는 비용이 발생하므로 관리되지 않는 언어는 제거됩니다. 새로운 언어에 대한 지원은 TensorFlow 블로그 또는 Twitter 에서 발표됩니다.

선호하는 언어가 지원되지 않는 경우 오픈 소스 기여자를위한 커뮤니티 포크를 유지하는 것을 환영합니다. 이들은 tensorflow.org에 게시되지 않습니다.