문서 빌드하기

이 장에서는 표준 라이브러리(std)나 컴파일러(rustc)와 같은 툴체인 구성 요소의 문서를 빌드하는 방법을 설명합니다.

• 모든 것 문서화하기

  이 방법은 베타 툴체인의 rustdoc을 사용하므로, rustdoc이 활발히 개발 중인 관계로 stage 1 rustdoc과는 (약간) 다른 출력을 생성합니다.

  ./x doc
  

  문서가 CI에서와 동일하게 보이도록 확실히 하려면 다음과 같이 하십시오.

  ./x doc --stage 1
  

  이렇게 하면 (현재의) rustdoc이 먼저 빌드되고, 그 rustdoc을 사용하여 구성 요소를 문서화합니다.

• 개별 테스트를 실행하거나 특정 구성 요소를 빌드하는 것과 마찬가지로, 원하는 문서만 빌드할 수 있습니다.

  ./x doc src/doc/book
  ./x doc src/doc/nomicon
  ./x doc compiler library
  

  전체 책 목록은 nightly 문서 색인 페이지를 참고하십시오.

• rustc 내부 항목 문서화하기

  컴파일러 문서는 기본적으로 빌드되지 않습니다. x doc으로 기본적으로 생성되도록 하려면 bootstrap.toml을 수정하십시오.

  build.compiler-docs = true
  

  이 옵션을 활성화하면 컴파일러 내부 항목에 대한 문서도 함께 빌드된다는 점에 유의하십시오.

  참고: 컴파일러 문서는 이 링크에서 찾을 수 있습니다.

문서에 기여하기

문서 개선은 언제나 환영합니다. doc.rust-lang.org의 소스는 트리 내의 src/doc에 있으며, 표준 API 문서는 소스 코드 자체(예: library/std/src/lib.rs)에서 생성됩니다. 문서 관련 풀 리퀘스트도 다른 풀 리퀘스트와 같은 방식으로 함수처럼 동작합니다.

문서 관련 이슈를 찾으려면 A-docs 레이블을 사용하십시오.

문서 스타일 가이드라인은 RFC 1574에서 확인할 수 있습니다.

표준 라이브러리 문서를 빌드하려면 x doc --stage 1 library --open을 사용하십시오. 책(예: unstable book)의 문서를 빌드하려면 x doc src/doc/unstable-book을 사용하십시오. 결과물은 build/host/doc에 생성되며, 기본 브라우저에서도 자동으로 열립니다. 자세한 내용은 문서 빌드하기를 참고하십시오.

작은 수정 사항을 확인할 때는 rustdoc을 직접 사용할 수도 있습니다. 예를 들어, rustdoc src/doc/reference.md는 reference를 doc/reference.html로 렌더링합니다. CSS가 깨질 수는 있지만, HTML이 올바른지는 확인할 수 있습니다.

내부 문서에 대한 타이포그래피/맞춤법 수정은 대개 변경으로 인한 부담이나 리뷰 시간을 들일 만한 가치가 없으므로 받지 않는다는 점에 유의하십시오. 내부 문서의 예로는 코드 주석과 rustc API 문서가 있습니다. 다만 같은 PR에서 다른 개선 사항과 함께 수정하는 경우라면 얼마든지 수정하셔도 됩니다.