dart doc 명령어: API 문서 생성하기

dart doc 명령어: API 문서 생성하기

dart doc 명령어는 Dart 소스 코드의 HTML 참조 문서를 생성해요. 코드에 단 문서 주석을 HTML 문서로 변환해 주는 거예요.

출처: dart doc

본문

문서 작성하기

생성된 문서에 참조 텍스트와 예시를 추가하려면 Markdown 서식을 사용하는 문서 주석(documentation comments)을 이용해요. 문서 주석 작성에 대한 지침은 Effective Dart: Documentation 가이드를 참고하세요.

API 문서 생성하기

패키지 문서를 생성하려면 패키지 루트 디렉터리에서 dart doc .를 실행해요. 예를 들어 my_package 패키지의 API 문서를 생성하면 다음과 같을 수 있어요.

$ cd my_package
$ dart pub get
$ dart doc .
Documenting my_package...
...
Success! Docs generated into /Users/me/projects/my_package/doc/api

기본적으로 dart doc은 생성된 문서와 지원 파일을 doc/api 디렉터리에 넣어요. 출력 디렉터리를 바꾸려면 --output 플래그로 경로를 지정해요.

$ dart doc --output=api_docs .

패키지 설정이나 문서 주석에 문제가 있으면 dart doc이 이를 오류나 경고로 출력해요. 생성된 문서를 저장하지 않고 문제만 확인하고 싶다면 --dry-run 플래그를 추가하세요.

$ dart doc --dry-run .

생성 방식 설정하기

dart doc이 문서를 생성하는 방식을 설정하려면 패키지 루트 디렉터리에 dartdoc_options.yaml이라는 파일을 만들어요.

파일 형식과 지원되는 설정 옵션에 대해 더 알아보려면 dart.dev/go/dartdoc-options-file을 확인하세요.

생성된 문서 보기

dart doc으로 생성된 문서는 다양한 방법으로 볼 수 있어요.

로컬 문서 보기

dart doc으로 생성했거나 온라인에서 다운로드한 API 문서를 보려면 HTTP 서버로 문서를 로드해야 해요.

파일을 서빙하려면 아무 HTTP 서버나 사용해요. pub.dev의 package:dhttpd 사용을 고려해 보세요.

package:dhttpd를 사용하려면 전역으로 설치한 뒤, 생성된 문서 경로를 지정해 실행해요. 다음 명령어는 패키지를 설치한 다음 doc/api에 있는 API 문서를 서빙해요.

$ dart install dhttpd
$ dhttpd --path doc/api

그런 다음 생성된 문서를 브라우저에서 읽으려면 dhttpd가 출력하는 링크(보통 http://localhost:8080)를 열어요.

호스팅된 문서 보기

정적 웹 콘텐츠를 지원하는 아무 호스팅 서비스로도 생성된 API 문서를 온라인에 호스팅할 수 있어요. 흔한 두 가지 옵션은 Firebase hosting과 GitHub pages예요.

패키지 문서 보기

pub.dev 사이트는 업로드된 패키지의 공개 라이브러리에 대한 문서를 생성하고 호스팅해요.

패키지의 생성된 문서를 보려면 그 페이지로 이동해 오른쪽 정보 상자에서 API reference 링크를 열면 돼요. 예를 들어 package:http의 API 문서를 pub.dev/documentation/http에서 찾을 수 있어요.

코어 라이브러리 문서 보기

dart doc은 Dart 코어 라이브러리의 API 참조 문서를 생성하는 데도 사용돼요.

Dart SDK 참조 문서를 보려면, 개발 중인 Dart 릴리스 채널에 해당하는 api.dart.dev 링크를 방문해요.

브랜치 생성된 문서
stable api.dart.dev/stable
beta api.dart.dev/beta
dev api.dart.dev/dev
main api.dart.dev/main

문제 해결

dart doc으로 생성한 문서에서 흔히 겪는 문제를 찾고 해결하려면 다음 참조 섹션을 확인해요.

검색 바가 로드되지 않을 때

생성된 문서의 검색 바가 동작하지 않거나 "Failed to initialize search" 같은 텍스트가 보인다면, 다음 시나리오 중 하나일 수 있어요.

  • 파일 시스템에서 문서에 직접 접근하고 있는데, HTTP 서버로 서빙·로드되지 않고 있어요. 로컬 API 문서를 서빙하는 방법은 로컬에서 생성된 문서 보기를 참고하세요.
  • dart doc이 생성한 index.json 파일이 문서 디렉터리나 호스팅 웹 서버에서 없거나 접근할 수 없어요. 문서를 다시 생성하고 호스팅 설정을 검증해 보세요.

사이드바가 로드되지 않을 때

생성된 문서의 사이드바가 없거나 "Failed to load sidebar" 같은 텍스트가 보인다면, 다음 시나리오 중 하나일 수 있어요.

  • 파일 시스템에서 문서에 직접 접근하고 있는데, HTTP 서버로 서빙·로드되지 않고 있어요. 로컬 API 문서를 서빙하는 방법은 로컬 문서 보기를 참고하세요.
  • 생성된 문서의 base-href 동작이 설정되어 있어요. 이 설정 옵션은 더 이상 사용되지 않으니(deprecated) 쓰지 말아야 해요. 옵션을 제거하고 dart doc의 기본 동작을 사용해 보세요. 기본 동작이 생성된 문서의 링크를 깨뜨린다면 이슈를 올려 주세요.

API 문서가 없을 때

문서가 있어야 한다고 예상한 API의 생성된 문서를 찾거나 접근할 수 없다면, 다음 시나리오 중 하나일 수 있어요.

  • 패키지가 찾고 있는 API를 공개 API로 노출하지 않고 있어요. dart doc은 다른 패키지가 import해서 사용할 수 있도록 노출된 공개 라이브러리와 멤버에 대해서만 문서를 생성해요. 패키지의 공개 라이브러리 설정에 대해 더 알아보려면 공개 라이브러리에 대한 패키지 레이아웃 가이드를 참고하세요.
  • 접근하려는 URL의 대문자 표기가 틀렸어요. 기본적으로 dart doc은 대소문자를 구분하고, 해당 소스 선언과 일치하며, .html 확장자를 가진 파일 이름을 생성해요. URL이 이러한 기대와 일치하는지 확인해 보세요.

아이콘이 있어야 할 자리에 텍스트가 보일 때

메뉴나 테마 버튼 같은 아이콘 대신 텍스트가 보인다면, 브라우저가 Material Symbols 폰트를 로드하지 못했을 가능성이 커요. 해결 방법은 다음과 같아요.

  • Google Fonts 서버에 접근할 수 있는 프록시를 사용해 보세요.
  • 생성된 페이지를 업데이트해서 폰트의 로컬 버전을 사용하세요.

더 알아보기