최근 'docexp'라는 새로운 오픈소스 도구가 공개되어 개발자 커뮤니티의 주목을 받고 있습니다. 이 도구는 마크다운 문서에 포함된 코드 블록을 실행하고, 그 실행 결과를 다시 마크다운 파일 내에 삽입하는 기능을 제공합니다. 이는 주피터 노트북(Jupyter Notebook)처럼 복잡한 환경 설정 없이도, 순수한 마크다운 파일에서 코드 실행 결과를 직접 볼 수 있게 해주는 간결한 문서화 방식입니다.
docexp는 마크다운 파일 내의 특정 코드 블록을 파싱(parsing)하여 JSON 객체로 변환합니다. 예를 들어, SQL 쿼리 코드 블록이 있다면, docexp는 해당 쿼리 내용을 추출하고 파일 내 위치, 언어, 제목 계층 구조 등의 메타데이터를 함께 제공합니다. 사용자는 이 JSON 데이터를 입력으로 받아 실제 코드를 실행하고 그 결과를 JSON 형태로 반환하는 '확장 스크립트(expander script)'를 직접 작성해야 합니다. 이 스크립트는 파이썬(Python) 등 어떤 언어로든 구현할 수 있으며, 데이터베이스 쿼리 실행이나 셸(shell) 명령어 실행 등 다양한 작업을 수행할 수 있습니다. docexp는 이 스크립트가 반환한 실행 결과를 원본 마크다운 파일의 해당 코드 블록 아래에 HTML 주석 태그(<!-- <docexp> -->)로 감싸 삽입합니다.
이 도구의 가장 큰 장점은 문서의 간결성과 유연성입니다. 주피터 노트북처럼 특정 파일 형식이나 무거운 실행 환경에 얽매이지 않고, 일반 마크다운 파일에서 코드 실행 결과를 관리할 수 있습니다. 이는 문서의 버전 관리(VCS)를 용이하게 하고, 특정 도구에 대한 종속성을 줄여줍니다. 또한, 확장 스크립트를 통해 코드 실행 환경을 사용자가 직접 제어할 수 있어, 보안 샌드박스(sandbox) 적용이나 특정 컨테이너 환경에서 코드 실행 등 고도의 맞춤 설정이 가능합니다. 아직 베타(BETA) 버전이지만, 복잡한 문서화 도구에 대한 대안을 찾는 개발자들에게 유용할 것으로 보입니다.