Ruby on Rails 가이드 지침

이 가이드는 Ruby on Rails 가이드 작성을 위한 지침을 문서화합니다. 이 가이드는 자신을 우아하게 반복하며 예시로 제공됩니다.

이 가이드를 읽고 나면 다음을 알 수 있습니다:

Markdown

가이드는 GitHub Flavored Markdown으로 작성됩니다. Markdown에 대한 포괄적인 문서와 치트시트가 있습니다.

각 가이드는 맨 위에 동기부여 텍스트로 시작해야 합니다(파란색 영역의 작은 소개). 서문은 가이드의 내용과 학습 내용을 독자에게 알려줘야 합니다. Routing 가이드를 참고하세요.

모든 가이드의 제목은 h1 제목을 사용하고, 가이드 섹션은 h2 제목을, 하위 섹션은 h3 제목을 사용합니다. 생성된 HTML 출력에서는 <h2> 태그부터 사용됩니다.

가이드 제목
===========

섹션
-------

### 하위 섹션

제목을 작성할 때는 전치사, 접속사, 내부 관사, “to be” 동사형을 제외한 모든 단어를 대문자로 씁니다:

#### 구성 요소 내부의 어설션 및 테스트 작업
#### 미들웨어 스택은 배열입니다
#### 언제 객체가 저장되나요?

일반 텍스트와 같은 인라인 형식을 사용합니다:

##### `:content_type` 옵션

API(api.rubyonrails.org) 링크는 가이드 생성기에 의해 다음과 같이 처리됩니다:

릴리스 태그가 포함된 링크는 그대로 유지됩니다. 예를 들어

https://api.rubyonrails.org/v5.0.1/classes/ActiveRecord/Attributes/ClassMethods.html

은 수정되지 않습니다.

릴리스 노트에서는 이러한 링크를 사용하세요. 이 링크는 대상이 생성되는 버전을 가리켜야 합니다.

릴리스 태그가 포함되지 않은 링크이고 엣지 가이드가 생성되는 경우, 도메인이 edgeapi.rubyonrails.org로 대체됩니다. 예를 들어,

https://api.rubyonrails.org/classes/ActionDispatch/Response.html

은 다음과 같이 변경됩니다:

https://edgeapi.rubyonrails.org/classes/ActionDispatch/Response.html

릴리스 태그가 포함되지 않은 링크이고 릴리스 가이드가 생성되는 경우, Rails 버전이 삽입됩니다. 예를 들어 v5.1.0 가이드를 생성한다면 다음 링크:

https://api.rubyonrails.org/classes/ActionDispatch/Response.html

은 다음과 같이 변경됩니다:

https://api.rubyonrails.org/v5.1.0/classes/ActionDispatch/Response.html

edgeapi.rubyonrails.org에 수동으로 링크하지 마세요.

오래된 가이드는 열을 줄바꾸기 위해 다시 포맷하지 마세요. 하지만 새로운 섹션과 가이드는 80자에서 줄바꿈해야 합니다.

가이드와 API는 적절한 경우 일관성 있고 일치해야 합니다. 특히 API 문서화 지침의 다음 섹션이 가이드에도 적용됩니다:

가이드를 생성하기 전에 시스템에 최신 버전의 Bundler가 설치되어 있는지 확인하세요. 최신 버전의 Bundler를 설치하려면 gem install bundler를 실행하세요.

Bundler가 이미 설치되어 있다면 gem update bundler로 업데이트할 수 있습니다.

모든 가이드를 생성하려면 guides 디렉토리로 이동하여 bundle install을 실행한 후 다음을 실행하세요:

$ bundle exec rake guides:generate

또는

$ bundle exec rake guides:generate:html

생성된 HTML 파일은 ./output 디렉토리에서 찾을 수 있습니다.

my_guide.md만 처리하고 다른 것은 처리하지 않으려면 ONLY 환경 변수를 사용하세요:

$ touch my_guide.md
$ bundle exec rake guides:generate ONLY=my_guide

기본적으로 수정되지 않은 가이드는 처리되지 않으므로 ONLY는 실제로 거의 필요하지 않습니다.

모든 가이드를 강제로 처리하려면 ALL=1을 전달하세요.

영어 이외의 언어로 가이드를 생성하려면 source 디렉토리에 별도의 디렉토리(예: source/es)에 보관하고 GUIDES_LANGUAGE 환경 변수를 사용하세요:

$ bundle exec rake guides:generate GUIDES_LANGUAGE=es

생성 스크립트에서 사용할 수 있는 모든 환경 변수를 보려면 다음을 실행하세요:

$ rake

생성된 HTML을 다음으로 유효성을 검사하세요:

$ bundle exec rake guides:validate

특히 제목에는 내용에서 생성된 ID가 있는데, 이로 인해 중복이 자주 발생합니다.

Kindle용 가이드를 생성하려면 다음 rake 작업을 사용하세요:

$ bundle exec rake guides:generate:kindle