Milecia McGregor는 conducto의 개발자 애드보케이트입니다. conducto는 데이터 과학 파이프라인을 만들기 위한 플랫폼 기업입니다(정확히 뭘 하는 회사인지는 잘 모르겠습니다 ㅠㅠ https://www.conducto.com/ 를 참고하세요).
API 문서를 제공하는 경우 실제 동작하는 코드를 문서 내에 삽입하게 되고 개발자는 그 코드를 가져다가 확인하고 사용합니다. 하지만 코드가 동작하지 않는다면 전체 문서와 제품에 대한 신뢰를 잃어버릴 수 있죠. 그래서 코드를 테스트하는 것이 중요하다고 합니다.
문서 작성 시 개츠비를 사용하는데 개츠비 플러그인 중에서 별도 코드 파일을 마크다운 문서에서 가져와서 사용할 수 있는 플러그인이 있다고 하네요. 그래서 실제 동작하는 코드는 파일로 분리하고 단위 테스트를 진행할 수 있다고 합니다.
문서 빌드 시 코드 파일에 대한 단위 테스트 프로세스를 추가하고 문제가 없도록 유지하는 것이지요.
영상에서는 플러그인 이름을 언급하지 않았는데 아마 gatsby-remark-embed-snippet이 아닐까 싶습니다.
https://www.gatsbyjs.com/plugins/gatsby-remark-embed-snippet/
Front End Framework With The Speed To Delight | Gatsby
Gatsby provides development teams an open source frontend framework for creating rich, optimized websites and a cloud platform for delivering them on a blazing fast edge network.
www.gatsbyjs.com
문서 내에 코드를 작성하면 알아서 단위 테스트를 진행해주는 건 아니구요.
플러그인을 사용해서 파일을 분리하고 해당 언어에서 지원하는 단위 테스트를 진행한다는 이야기입니다.
나머지는 실제 단위 테스트를 진행할 때 주의할 몇 가지를 언급합니다.
코드 실행을 할 수 없는 코드 조각은 그냥 마크다운 문서 내에 포함시킵니다.
빌드 프로세스에 테스트를 포함하지만 병렬로 처리되도록 합니다. 단위 테스트가 실패하더라도 제품이나 문서 배포에는 영향이 없도록 합니다. 이 방법은 문서 유지 관리의 편의를 위한 방법이지 문서 배포 기준이 아니라서 그런 듯하네요.
그 외 좀 더 자세한 내용은 아래 링크를 참고하세요.
https://pronovix.com/event/api-docs-virtual-2020/milecia-mcgregor
Milecia McGregor - Unit Testing Your Docs
Presentation recap: Milecia McGregor - Unit Testing Your Docs. Presented at API The Docs Virtual 2020 event series on 23 September.
pronovix.com
