5분 안에 Typescript 프로젝트 문서화 - typedoc

소개

typedoc는 설치가 매우 간단하고 쉬운 라이브러리이며 코드베이스를 문서화하는 방법에 이점이 있습니다. 라이브러리 자체도 매우 인기가 있으며 주석을 추가하는 명령은 매우 간단합니다. 대부분의 유형 추론은 유형 스크립트 자체에 의해 수행되므로 걱정할 것이 적습니다.

공식 문서

이 기사 대신 또는 추가로 공식 웹 사이트(적극 권장)click here를 방문하고 싶다면

설치

typedoc 패키지를 설치하려면:

npm install typedoc --save-dev

다음을 통해 작동하는지 확인할 수 있습니다.

$ npx typedoc --version

TypeDoc 0.20.0
Using TypeScript 4.1.2 from /home/gerrit/typedoc/node_modules/typescript/lib

용법

이제 라이브러리를 설치했으므로 작동 방식의 요지를 얻을 수 있는 문서를 생성할 수 있습니다.

일을 단순하게 유지하려면 다음 사항에 주의해야 합니다.

생성된 문서를 출력해야 하는 위치

사용해야 하는 소스 파일

--out 매개 변수 뒤에 출력 디렉터리 경로를 사용하여 출력 디렉터리를 지정합니다.
플래그 'eg, --out' 없이 선언된 모든 항목은 소스 파일로 취급되며 문서 생성을 위해 구문 분석됩니다.
이 명령을 실행하여 문서를 생성할 수 있습니다.

$ typedoc --out docs/ src/app/

src/app/폴더 대신 애플리케이션 진입점을 가리킬 수도 있습니다. 반응 프로젝트의 경우 src/index.ts 파일이 됩니다. Typedoc은 파일과 폴더 위치를 다르게 취급합니다. 폴더를 가리키면 해당 폴더 내의 모든 파일을 개별 진입점으로 취급합니다. typedoc이 애플리케이션 진입점이어야 한다고 말하는 파일을 가리키면 파일이 내보내는 모듈에 대한 문서가 생성됩니다.

생성된 문서가 내 프로젝트를 찾는 방법은 다음과 같습니다.

When you open the index.html file for your documentation, this is what is displayed, if your project has a readme.md, you'll be greeted to a preview of it. The explorer menu on the right lists all the modules typedoc found and generated documentation for in your project.

내 프로젝트 진입점으로 간주되는 항목을 가리킬 때 문서를 생성하는 데 문제가 발생했습니다. 나는 이것을 생성하는 프로젝트가 Angular 프로젝트라는 사실 때문일 수 있다고 생각합니다. Angular에서 진입점이 다르게 취급되기 때문에 진입점 파일 대신 소스 폴더를 사용하고 있습니다. 대신 Angular는 고정 진입점 대신 파일 컴파일을 제공합니다. see here .

문서가 표시되는 방식

이 부분은 매우 간단하며 예제 구성 요소를 사용하여 잘 설명되어 있지 않습니다.

This is a preview of the documentation typedoc will generate for just 1 component, which in this case is an example-component I created with some basic properties and methods.

나는 아무 것도 언급하지 않았지만 운 좋게도 typedoc는 우리 기능에 대한 기본 문서도 생성합니다.

All of this has been generated by typedoc automatically!

문서 주석 추가

이제 작동 방식에 대한 아이디어를 얻었으므로 마지막 섹션으로 이동하여 주석을 추가하고 기본 typedoc 태그, 즉 @param 및 @return 를 활용합니다.
인사말 기능에 약간의 멋진 설명을 추가하겠습니다.

설명서를 다시 생성하는 명령을 실행합니다.

$ npx typedoc --out docs src/app/

예제 구성 요소로 다시 이동하면 업데이트된 문서를 볼 수 있습니다.

Isn't this great? that's all it took to generate a pretty-ish but useful documentation.

typedoc은 문서를 생성하기 위해 마크다운을 사용하므로 원하는 경우 주석에 표제 태그를 추가하고 다음을 얻을 수도 있습니다.

결론

이제 typedoc이 작동하는 방식, 기본 문서를 생성하는 방법 및 자신의 코드 주석을 추가하는 방법에 대해 어느 정도 이해했을 것입니다. 그러나 그 이상으로 나는 이것이 당신이 당신의 코드베이스에 문서를 추가할 의향이 있기를 바랍니다.