ROR Lab. Working Group

공식 루비온레일스 프로젝트는 문서화를 위해 별도의 branch을 운영하고 있습니다. 이것을 docrails라고 하는데 누구나가 docrails 문서를 수정/보완할 수 있는 권한이 주어집니다.

docrails의 원본 저장소는 http://gihub.com/lifo/docrails 에 위치합니다.

한글번역 작업을 위해 이 저장소를 fork하여 rorlab계정에 저장소를 만들었습니다. 따라서, ROR Lab.에서 진행하는 레일스 가이드 한글번역 작업에 참여를 원하는 분은 본인의 로컬 머신에서 git@github.com:rorlab/docrails.git 저장소를 git clone하여 아래에 소개하는 순서에 따라 번역 작업을 하면 됩니다.

중복 작업을 피하기 위해서 참여자마다 작업범위를 할당하게 될 것입니다.

본인의 작업내용을 다른 분도 볼 수 있도록 하기 위해서는 git push 명령으로 rorlab/docrails.git 저장소로 푸시하면 됩니다.

이렇게 참여자들이 번역한 내용들이 rorlab/docrails.git 저장소로 모이게 되면, 또는 중간에 결과를 온라인으로 확인하기 위해서는 작업 관리자(rorlab@gmail.com)가 아래와 같은 작업을 통해서 가이드 웹페이지로 렌더링하게 됩니다.

$ docrails > cd guides
$ docrails/guides > rake guides:generate_guides
$ docrails/guides > rake guides:publish

docrails/guides 디렉토리에서 사용할 수 있는 rake 작업 목록을 보기 위해서는 아래와 같이 rake -T 명령을 실행하면 됩니다.

$ docrails/guides > rake -T
rake guides:generate         # Generate guides (for authors), use ONLY=foo to process just "foo.md"
rake guides:generate:html    # Generate HTML guides
rake guides:generate:kindle  # Generate .mobi file. The kindlegen executable must be in your PATH. You can get...
rake guides:generate_guides  # Generate guides using GUIDES_LANGUAGE=ko EDGE=1 ALL=1
rake guides:help             # Show help
rake guides:publish          # Publish the guides to shared/rg
rake guides:validate         # Validate guides, use ONLY=foo to process just "foo.html"

이 때 사용할 수 있는 옵션에 대한 설명은 아래와 같습니다.

WARNINGS=1 : 소스파일내의 링크(anchors)를 체크하고 중복된 HTML 태그 ID도 알아내도록 한다. ALL=1 : 모든 파일을 강제로 렌더링하도록 한다. ONLY=name : 하나 또는 그 이상의 파일을 생성하고자 할 때 파일명을 지정할 수 있도록 한다. 예를 들어, association_basics.html 파일만을 렌더링하고자 할 경우에는 ONLY=assoc 와 같이 저정해 주고, 복수개의 파일에 대해서 콤마로 구분해 준다. ONLY=assoc,migrations GUIDE_LANGUAGE : source 디렉토리 아래에 만들게 되는 국가별 디렉토리명(대개는 알파벳 2문자, 여기서는 ko로 지정함)을 지정하여 docrails/guides/source/ko 디렉토리에 있는 번역물이 생성되도록 한다. EDGE=1 : 최종 렌더링된 레일스 가이드 웹페이지에 "edge" 표시가 보이도록 한다.

참고로 아래에, docrails/guides/RakeFile 파일에 정의되어 있는 generate_guides 작업 내용을 보면 이해하는데 도움이 될 것입니다.

  desc 'Generate guides using GUIDES_LANGUAGE=ko EDGE=1 ALL=1'
  task :generate_guides do
    ENV["WARN_BROKEN_LINKS"] = "1" # authors can't disable this
    ENV["GUIDES_LANGUAGE"] = "ko"
    ENV["EDGE"] = "1"
    # ENV["ALL"] = "1"
    ruby "rails_guides.rb"
  end

한글소스 렌더링 작업을 쉽게 할 수 있도록 원복 RakeFile을 약간 수정하였습니다. 즉,

$ docrails/source > rake guides:generate_guides

와 같이 옵션 없이 작업을 실행하면 변경된 파일들만 렌더링될 것입니다. 그러나 전체 파일을 모두 렌더링하고자 할 경우에는, 위에서와 같이 주석처리된 #ENV["ALL"] = "1" 부분에서 주석기호를 없애주거나 ALL=1 옵션을 추가해서 작업을 하면 됩니다.

자, 이렇게 해서 번역된 내용이 docrails/guides/outputs 디렉토리로 렌더링되고 나면, 다음으로는 서버로의 publish 작업이 필요합니다. 이를 위해서는 위에서 언급한 바와 같이

$ docrails/source > rake guides:publish

명령을 실행합니다. 참고로 RakeFile의 :publish 작업내용을 보면 아래와 같습니다.

  desc "Publish the guides to shared/rg"
  task :publish => :generate_guides do
    require 'rake/contrib/sshpublisher'
    mkdir_p 'pkg'
    `tar -czf pkg/guides_ko.gz output/ko`
    Rake::SshFilePublisher.new("user@rorlab.org", "/home/user/apps/project/shared", "pkg", "guides_ko.gz").upload
    `ssh user@rorlab.org 'cd /home/user/apps/project/shared/ && tar -xvzf guides_ko.gz && rm -rf rg && mkdir rg && mv -f output/ko/* rg && rm -rf output && rm guides_ko.gz'`
  end

:publish 작업을 수행하면, 제일 먼저 :generate_guides 작업을 하게 되고, pkg 라는 디렉토리를 만든 후에 output/ko 디렉토리에 생성된 파일들을 guides_ko.gz라는 파일로 압축하여 만들게 됩니다. 그 다음에 pkg/guides_ko.gz 파일을 배포권한 있는 유저계정을 이용하여 ssh로 서버로 업로드하고 압축을 풀면 되는 것입니다.

이상은 한글번역 작업을 하여 특정 서버에 배포하는 과정을 설명한 것입니다.

그러나 영문 문서의 내용 중 오류를 수정하거나 보완한 경우에는 publish 과정을 하지 않고, 아래에 설명하는 순서에 따라 문서작업을 하고 최종 pull request하면 guide author가 검토후에 lifo/docrails의 master branch로 머지합니다. 이렇게 머지된 문서는 http://edgeguides/rubyonrails.org 에서 온라인으로 확인할 수 있으며, 루비온레일스의 공식 릴리스시에 루비온레일스의 master branch에 최종 머지되어 배포되고 이 내용이 최종 http://guides.rubyonrails.org 에 반영되는 것입니다.

ROR Lab.에서는, 격주로 진행되는 오프라인 강의 참석자 중에서 지원자에 한하여, http://github.com/lifo/docrails 저장소의 내용을 fork 하여 만들어진 http://github.com/rorlab/docrails 의 내용을 git clone하고 git push하는 식으로 한글 번역본을 지속적으로 작업하고 최신상태로 관리유지하고자 합니다.

ROR Lab.에서 진행하는 루비온레일스 가이드 공동번역 작업에 참여을 원하시는 분은 본인의 SSH 공개키(~/.ssh/id_rsa.pub) 파일을 운영자(rorlab@gmail.com)에게 이메일로 첨부하여 보내 주시면 git@github.com:rorlab/docrails.git 파일에 대한 접근권한을 드리도록 하겠습니다.

뜻 있는 분들의 많은 참여를 바랍니다. 감사합니다.

ROR Lab. 운영자 올림.