TensorFlow 문서에 기여

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

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

TensorFlow 문서 커뮤니티에 참여하려면:

API 참조

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

버전 및 분기

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

기본 TensorFlow 패키지는 기본 tensorflow/tensorflow 저장소의 안정적인 분기 rX.x 에서 빌드됩니다. 참조 문서는 Python , C++ 및 Java 용 소스 코드의 코드 주석 및 독스트링에서 생성됩니다.

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

API 문서 구축

파이썬 참조

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 가이드 와 튜토리얼은 Markdown 파일과 대화형 Jupyter 노트북으로 작성되었습니다. Google Colaboratory를 사용하여 브라우저에서 노트북을 실행할 수 있습니다. tensorflow.org 의 내러티브 문서는 tensorflow/docs master 브랜치에서 구축되었습니다. 이전 버전은 GitHub의 rX.x 릴리스 분기에서 사용할 수 있습니다.

간단한 변경

Markdown 파일에 대한 간단한 문서 업데이트를 수행하는 가장 쉬운 방법은 GitHub의 웹 기반 파일 편집기를 사용하는 것입니다. tensorflow.org URL 구조와 대략적으로 일치하는 Markdown을 찾으려면 tensorflow/docs 저장소를 탐색하세요. 파일 보기 오른쪽 상단에 있는 연필 아이콘을 클릭하세요. 파일 편집기를 엽니다. 파일을 편집한 다음 새 끌어오기 요청을 제출하세요.

로컬 Git 저장소 설정

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

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

tensorflow/docs 저장소 포크

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

저장소 복제

원격 username /docs 저장소의 복사본을 로컬 컴퓨터에 다운로드합니다. 변경할 작업 디렉터리는 다음과 같습니다. 

git clone git@github.com:username/docs
cd ./docs

최신 상태를 유지하기 위해 업스트림 저장소 추가(선택 사항)

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

리모컨 추가:

git remote add upstream git@github.com:tensorflow/docs.git

# View remote repos
git remote -v
origin    git@github.com:username/docs.git (fetch)
origin    git@github.com:username/docs.git (push)
upstream  git@github.com:tensorflow/docs.git (fetch)
upstream  git@github.com:tensorflow/docs.git (push)

업데이트하려면: 

git checkout master
git pull upstream master

git push  # Push changes to your GitHub account (defaults to origin)

GitHub 워크플로

1. 새 지점 만들기

tensorflow/docs 에서 저장소를 업데이트한 후 로컬 마스터 분기에서 새 분기를 만듭니다. 

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. 변경하기

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

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

# View changes
git status  # See which files have changed
git diff    # See changes within files

git add path/to/file.md
git commit -m "Your meaningful commit message for the change."

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

3. 끌어오기 요청 만들기

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

git push

푸시가 완료되면 업스트림 저장소에 풀 요청을 자동으로 제출하기 위한 URL이 메시지에 표시될 수 있습니다. 그렇지 않은 경우 tensorflow/docs 저장소 또는 자신의 저장소로 이동하면 GitHub에서 끌어오기 요청을 생성하라는 메시지를 표시합니다.

4. 검토

유지관리자 및 기타 기여자가 귀하의 풀 요청을 검토합니다. 토론에 참여하여 요청된 사항을 변경하시기 바랍니다. 풀 요청이 승인되면 업스트림 TensorFlow 문서 저장소에 병합됩니다.

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

대화형 노트북

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

Google Colaboratory 는 노트북 문서를 쉽게 편집하고 실행할 수 있는 호스팅된 노트북 환경입니다. GitHub의 노트북은 Colab URL에 대한 경로를 전달하여 Google Colab에 로드됩니다. 예를 들어 GitHub에 있는 노트북은 https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras 입니다. /classification.ipynb
다음 URL에서 Google Colab에 로드할 수 있습니다: 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 docs 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 환경 내에서 셀을 두 번 클릭하여 텍스트 및 코드 블록을 편집합니다. 텍스트 셀은 Markdown을 사용하며 TensorFlow 문서 스타일 가이드를 따라야 합니다.

파일 > .pynb 다운로드를 사용하여 Colab에서 노트북 파일을 다운로드하세요. 이 파일을 로컬 Git 저장소 에 커밋하고 끌어오기 요청을 보냅니다.

새 노트북을 만들려면 TensorFlow 노트북 템플릿을 복사하고 편집하세요.

Colab-GitHub 워크플로

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

  1. 분기된 username /docs 저장소에서 GitHub 웹 UI를 사용하여 새 분기를 만듭니다 .
  2. 편집할 노트북 파일로 이동합니다.
  3. Google Colab에서 노트북을 엽니다. URL 교환이나 Colab Chrome 확장 프로그램에서 열기를 사용하세요.
  4. Colab에서 노트북을 편집합니다.
  5. 파일 > GitHub에 복사본 저장...을 사용하여 Colab에서 저장소에 대한 변경 사항을 커밋합니다. 저장 대화 상자는 적절한 저장소 및 분기에 연결되어야 합니다. 의미 있는 커밋 메시지를 추가하세요.
  6. 저장한 후 저장소 또는 tensorflow/docs 저장소로 이동하면 GitHub에서 끌어오기 요청을 생성하라는 메시지를 표시해야 합니다.
  7. 끌어오기 요청은 관리자가 검토합니다.

번역

TensorFlow 팀은 커뮤니티 및 공급업체와 협력하여 tensorflow.org에 대한 번역을 제공합니다. 노트북 및 기타 기술 콘텐츠의 번역은 tensorflow/docs-l10n GitHub 저장소에 있습니다. TensorFlow GitLocalize 프로젝트를 통해 풀 요청을 제출하세요.

영어 문서는 진실의 원천 이며 번역은 이 가이드를 최대한 따라야 합니다. 즉, 번역은 그들이 봉사하는 커뮤니티를 위해 작성되었습니다. 영어 용어, 어법, 문체, 어조가 다른 언어로 번역되지 않는 경우 독자에게 적합한 번역을 사용하십시오.

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

선호하는 언어가 지원되지 않는 경우 오픈 소스 기여자를 위한 커뮤니티 포크를 유지 관리하실 수 있습니다. 이는 tensorflow.org에 게시되지 않습니다.