6.2 GitHub

GitHub 페이지 (https://pages.github.com)를 통해 무료로 GitHub에 책을 호스팅할 수 있습니다. GitHub는 정적 웹 사이트 빌더인 Jekyll (http://jekyllrb.com)을 지원하여 Markdown 파일에서 웹 사이트를 구축합니다. 이는 GitHub 페이지의 더 일반적인 사용 사례 일 수 있지만 GitHub는 임의의 정적 HTML 파일도 지원하므로 GitHub에서 책의 HTML 출력 파일을 호스팅할 수 있습니다. 핵심은 bookdown HTML 출력이 이미 독립형 웹 사이트이므로 GitHub에 웹 사이트가 Jekyll을 통해 빌드되지 않는다는 것을 알려주는 숨겨진 파일 .nojekyll을 만드는 것입니다.

# assume you have initialized the git repository,
# and are under the directory of the book repository now

# create a hidden file .nojekyll
touch .nojekyll
# add to git here because will not show up in RStudio
git add .nojekyll

Windows를 사용하는 경우 touch 명령이 없을 수 있으며 file.create('.nojekyll')를 사용하여 R에서 파일을 만들 수 있습니다.

한 가지 방법은 GitHub 도움말에 설명된대로 master 브랜치의 /docs 폴더에서 책을 GitHub 페이지 사이트로 게시하는 것입니다. 먼저 출력 디렉토리를 설정합니다. 구성 파일 _bookdown.yml에 output_dir: "docs"줄을 추가하여 책의 /docs가 되도록 합니다. 그런 다음 변경 사항을 GitHub에 푸시한 후 저장소 설정으로 이동하여 “GitHub 페이지”에서 “소스”를 ’master branch/docs 폴더’로 변경합니다. 이 경우 .nojekyll 파일은 /docs 폴더에 있어야 합니다.

다른 방법은 저장소에 gh-pages 브랜치를 만들고 책을 만들어 이 브랜치에 HTML 출력 (이미지, CSS, 자바 스크립트 파일과 같은 모든 외부 리소스 포함)을 넣은 다음 브랜치를 원격 저장소로 푸시하는 것입니다. 책 저장소에gh-pages 브랜치가 없는 경우 다음 명령을 사용하여 만들 수 있습니다.

# assume you have initialized the git repository,
# and are under the directory of the book repository now

# create a branch named gh-pages and clean up everything
git checkout --orphan gh-pages
git rm -rf .

# create a hidden file .nojekyll
touch .nojekyll
git add .nojekyll

git commit -m"Initial commit"
git push origin gh-pages

GIT를 설정 한 후에는 스크립트 (기본 설정에 따라 쉘, R 또는 Makefile)를 통해 나머지 작업을 자동화할 수 있습니다. 기본적으로 책을 HTML로 컴파일한 다음 git 명령을 실행하여 파일을 GitHub에 푸시하지만 수동 및 로컬에서 이 작업을 반복하고 싶지 않을 것입니다. 클라우드에서 출판 프로세스를 완전히 자동화하는 것은 매우 편리할 수 있으므로 올바르게 설정되면 책을 작성하고 Rmd 소스 파일을 GitHub에 푸시하기만 하면 책이 항상 자동으로 빌드되어 서버 측에 출판이 됩니다.

활용할 수 있는 서비스 중 하나는 Travis CI (https://travis-ci.org)입니다. GitHub의 공용 저장소에 대해 무료이며 소프트웨어 패키지의 CI (지속적 통합, continuous integration)를 위해 설계되었습니다. Travis CI는 GitHub에 푸시할 때마다 최신 버전의 저장소에서 특정 명령/스크립트를 실행하도록 Travis를 트리거할 수 있다는 점에서 GitHub에 연결할 수 있습니다 ^[먼저 GitHub에서 저장소에 대한 Travis CI 서비스를 승인해야합니다.

Travis CI를 시작하는 방법은 https://docs.travis-ci.com/user/getting-started/를 참조하십시오.]. 이 명령은 저장소의 루트 디렉토리에있는.travis.yml이라는 YAML 파일에 지정되며 일반적으로 소프트웨어 테스트 목적이지만 실제로는 상당히 개방적입니다. 즉, Travis (가상) 컴퓨터에서 임의의 명령을 실행할 수 있습니다. 즉, Travis에서 책을 만들기 위해 자신의 스크립트를 확실히 실행할 수 있습니다. Travis는 현재 Ubuntu 및 Mac OS X 만 지원하므로 Linux/Unix 명령에 대한 기본 지식이 있어야합니다.

다음 질문은 Travis를 기반으로 한 책을 GitHub에 게시하는 방법입니다. 기본적으로 Travis에게 GitHub 저장소에 대한 쓰기 액세스 권한을 부여해야 합니다. 이 인증은 여러 가지 방법으로 수행 할 수 있으며 초보자에게 가장 쉬운 방법은 개인 액세스 토큰일 수 있습니다. 수행해야 하는 단계는 다음과 같습니다.

  1. GitHub에서 계정에 대한 개인 액세스 토큰을 만듭니다 (이 토큰을 사용하여 GitHub 저장소에 쓸 수 있도록 “repo”범위를 활성화해야 합니다).

  2. travis encrypt 명령 줄을 통해 환경 변수 GITHUB_PAT에 암호화하고 .travis.yml에 저장합니다 (예 :travis encrypt GITHUB_PAT = TOKEN). Travis 명령 줄 도구를 설치하거나 사용하는 방법을 모르는 경우 https://travis-ci.org/user/repo/settings를 통해 이 환경 변수를 저장하기만 하면 됩니다. 여기서 user는 GitHub ID이고 repo는 저장소의 이름입니다.

  3. GitHub 토큰을 사용하여 Travis에서 이 gh-pages 브랜치를 복제하고 R Markdown에서 HTML 출력 파일을 추가하고 (그림과 CSS 스타일 파일도 추가하는 것을 잊지 마세요) 원격 저장소로 푸시할 수 있습니다.

지금 (Rmd 소스 파일을 넣은) master 브랜치에 있고 책을 _book 디렉토리에 컴파일했다고 가정하자. Travis에서 다음으로 할 수 있는 작업은 다음과 같습니다.

# configure your name and email if you have not done so
git config --global user.email "you@example.com"
git config --global user.name "Your Name"

# clone the repository to the book-output directory
git clone -b gh-pages \
  https://${GITHUB_PAT}@github.com/${TRAVIS_REPO_SLUG}.git \
  book-output
cd book-output
git rm -rf *
cp -r ../_book/* ./
git add --all *
git commit -m"Update the book"
git push -q origin gh-pages

변수 이름 GITHUB_PAT와 디렉토리 이름 book-output은 임의적이며 이름이 기존 환경 변수 이름 또는 디렉토리 이름과 충돌하지 않는 한 원하는 이름을 사용할 수 있습니다. 이 스크립트는 섹션 5.1에서 언급한 빌드 스크립트와 함께 master 셸 스크립트로 분기합니다. 예를 들어 _build.sh와 _deploy.sh로 이름을 지정할 수 있습니다. 그러면 .travis.yml이 다음과 같이 보일 수 있습니다.

language: r
pandoc_version: 1.19.2.1

env:
  global:
    - secure: A_LONG_ENCRYPTED_STRING

before_script:
  - chmod +x ./_build.sh
  - chmod +x ./_deploy.sh

script:
  - ./_build.sh
  - ./_deploy.sh

language 키는 Travis에게 R이 설치된 가상 머신을 사용하도록 지시합니다. secure 키는 암호화된 개인 액세스 토큰입니다. 명령 줄 도구인 travis encrypt 대신 Travis의 웹 인터페이스를 사용하여 GITHUB_PAT 변수를 이미 저장한 경우이 키를 생략할 수 있습니다.

이 Travis 서비스는 주로 R 패키지를 확인하기 위한 것이므로 책 저장소가 R 패키지인 것처럼 (가짜) DESCRIPTION 파일도 필요합니다. 이 파일에서 정말로 중요한 것은 종속성(dependencies)의 사양입니다. 모든 종속성은 devtools 패키지를 통해 설치됩니다. 종속성이 CRAN 또는 BioConductor에 있는 경우 DESCRIPTION 파일의 Imports 필드에 간단히 나열할 수 있습니다. GitHub에 있는 경우Remotes 필드를 사용하여 저장소 이름을 나열할 수 있습니다. 다음은 하나의 예입니다.

Package: placeholder
Type: Book
Title: Does not matter.
Version: 0.0.1
Imports: bookdown, ggplot2
Remotes: rstudio/bookdown

Travis에서 컨테이너 기반 인프라를 사용하는 경우 .travis.yml에 sudo: false를 사용하여 캐싱을 활성화할 수 있습니다. 일반적으로 Figure 디렉토리 (예 :_main_files)와 캐시 디렉토리 (예 :_main_cache)의 두 가지 유형 이상의 디렉토리를 캐시해야 합니다. knitr 청크 옵션 fig.path와 cache.path를 지정한 경우에도 이러한 디렉토리 이름이 다를 수 있지만 이러한 옵션을 변경하지 않는 것이 좋습니다. 그림과 캐시 디렉토리는 책 루트 디렉토리의 _bookdown_files 디렉토리에 저장됩니다. knitr 그림과 캐시 디렉토리의 캐싱을 활성화한 .travis.yml 파일에는 다음과 같은 추가 구성 sudo와 cache가 있을 수 있습니다.

sudo: false

cache:
  packages: yes
  directories:
    - $TRAVIS_BUILD_DIR/_bookdown_files

책을 만드는 데 시간이 많이 걸리는 경우 Travis에서 위의 구성을 사용하여 시간을 절약 할 수 있습니다. packages: yes는 Travis에 설치된 R 패키지도 캐시됨을 의미합니다.

위의 모든 스크립트와 구성은 bookdown-demo 저장소(https://github.com/rstudio/bookdown-demo/)에서 찾을 수 있습니다. 자신의 저장소에 복사하는 경우 자신의 암호화된 변수 GITHUB_PAT를 사용하여 .travis.yml의 secure 키를 변경해야 합니다.

GitHub와 Travis CI가 책을 만들고 출판하는 유일한 선택은 아닙니다. 자신의 서버에 책을 자유롭게 저장하고 출판할 수도 있습니다.