README 코드 스니펫의 정확성 보장

문제

개발자가 라이브러리와 갖게 되는 첫 번째 상호 작용입니다. 그들은 다양한 방법을 통해 라이브러리에 대해 듣지만 어느 시점에서 모두 README로 끝납니다. 첫인상이 좋은 것이 중요하며 실제로 작동하지 않는 README의 예제 코드 블록보다 개발자가 라이브러리를 끌 수 있는 것은 없습니다.

Markdown 자체는 우리에게 많은 도움이 되지 않습니다. Markdown은 우리가 만들고 있는 라이브러리에 대해 아무것도 모르는 단순한 마크업 언어이며 우리가 만든 코드 스니펫 내에서 코드를 컴파일할 수 없습니다.

일반적으로 두 가지 옵션이 있습니다.

우리는 코드를 마크다운에 직접 작성하고 괜찮을 것이라고 손가락질합니다

라이브러리에 대해 테스트할 수 있는 별도의 파일에 코드를 작성하고 마크다운 문서

에 복사하여 붙여넣습니다.

두 옵션 모두 실수할 여지가 많습니다. 첫 번째 경우에는 코드가 유효하지 않을 수도 있습니다! 두 번째에는 업데이트해야 할 파일이 많이 있으며 콘텐츠를 복사하여 붙여넣어야 합니다.

두 경우 모두 나중에 라이브러리에 주요 변경 사항을 도입하고 문서 업데이트를 완전히 잊은 다음 최악의 시나리오에 처하게 됩니다. 문서에 라이브러리가 반영되지 않습니다.

나는 오픈 소스에 약간 기여했으며 이러한 모든 사례를 접할 수 있었고 결국에는 선택되었지만 상당히 부끄럽습니다.

해결책

이러한 성가심에 싫증이 나서 소스 코드 스니펫에서 README 업데이트를 관리하는 프로세스를 자동화하기로 결정했습니다. 나는 README(및 다른 마크다운 문서도!)를 유지 관리하는 번거로움을 없애주는 작은 nodejs 명령줄 유틸리티를 만들었습니다.

nodejs가 설치되어 있다고 가정하면 간단히 실행할 수 있습니다.

npx embedme README.md

이제 처음에는 매우 유용한 출력을 얻지 못할 것입니다. embedme가 삽입할 적절한 파일을 찾을 수 있도록 코드 블록에 주석을 달아야 합니다.

예를 들어 살펴보겠습니다.

다음 README.md가 있다고 가정합니다.


embedme로 수행할 수 있는 작업은 코드 블록의 첫 번째 줄에 주석을 삽입하는 것입니다.



이제 다음을 실행하면 다음과 같습니다.



코드 블록을 찾은 위치와 코드 블록으로 수행한 작업(즉, 이 경우 path/to/example-usage.ts 에서 콘텐츠 삽입)을 나타내는 라이브러리의 출력이 표시됩니다.

다음으로 라이브러리의 유용성을 증명하기 위해 소스 코드를 변경합니다.

import { hello } from 'my-amazing-library';

console.log('An update here!');
hello(); // outputs Hello World!

그런 다음 embedme를 다시 실행합니다.


readme 파일이 업데이트된 것을 볼 수 있습니다.


이제 본 것처럼 예제 코드가 README 외부에 있지만 간단한 유틸리티를 사용하여 최신 상태로 유지할 수 있는 상황에 처해 있습니다. 뿐만 아니라 라이브러리에 대해 이 예제 코드를 단위 테스트할 수 있습니다(해야 합니다!). 이를 통해 라이브러리에 주요 변경 사항이 발생하는 경우 문서가 올바른 코드 스니펫으로 최신 상태로 유지되도록 보장할 수 있습니다. .

Embedme에는 다음과 같은 다양한 기능이 있습니다.

특정 라인 추출 ( //path/to/your/file.ts#L10-L20 )

--verify 실제로 파일에 쓰지는 않지만 변경 사항이 없는지 확인하는 플래그(CI 스크립트에 유용함!)

--stdout 다른 파일로 리디렉션하기 위해 변경 사항을 stdout으로 출력하는 플래그

코드 블록 내에 주석을 삽입할 필요 없이 마크다운 주석 구문을 사용하여 코드 블록을 정의합니다. ( <!-- embedme path/to/your/file.ts --> )

및 기타 몇 가지 편리한 기능...

자세한 내용은 라이브러리https://github.com/zakhenry/embedme를 확인하고 자동화된 작업 흐름에 추가하여 즐겁게 작성하고 유효함을 보장하는 문서를 얻으시기 바랍니다.


_{Photo by Andrea Sonda on Unsplash}