doxybook2 – Doxygen XML to Markdown (or JSON)

다양한 출력 형식 지원

doxybook2는 기본적으로 마크다운 파일을 생성하지만, --json 플래그를 사용하면 마크다운 대신 JSON 형식으로만 출력할 수 있습니다. 이 JSON 출력에는 brief 및 상세 설명과 같은 부분적인 마크다운 정보가 포함되어 있어, 사용자가 자신만의 문서 생성 도구와 연동하기에 적합합니다.

템플릿 기반 커스터마이징

이 도구는 인자 템플릿 엔진인 [inja](https://github.com/pantor/inja)를 사용하여 템플릿 기반 출력을 지원합니다. 사용자는 --templates 옵션을 통해 자신만의 템플릿 폴더를 지정하여 출력 형태를 완전히 제어할 수 있으며, 템플릿이 지정되지 않은 경우 내장된 기본 템플릿이 사용됩니다. 또한 --generate-templates 명령으로 기본 템플릿을 파일 시스템에 덤프할 수 있습니다.

설정 파일 기반 동작 제어

doxybook2는 JSON 형식의 설정 파일을 통해 세부 동작을 조정할 수 있습니다. --generate-config 명령으로 기본 설정 파일을 생성할 수 있으며, 이 파일에는 copyImages, sort, imagesFolder, linkLowercase, baseUrl, linkSuffix 등과 같은 옵션이 포함됩니다. 예를 들어 MkDocs에서는 linkSuffix를 /로, GitBook에서는 .md로 설정해야 합니다.

다운로드·설치 방법

Windows 사용자는 GitHub 릴리스 페이지에서 플랫폼에 맞는 ZIP 파일을 다운로드해야 합니다. 다운로드한 ZIP 파일을 압축 해제하면 bin 폴더 안에 doxybook2.exe 실행 파일이 있습니다. 이 파일을 시스템 내 적절한 위치에 복사한 후, 시스템의 PATH 환경 변수에 해당 폴더를 추가해야 합니다. 또한 Windows에서는 Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017 and 2019가 사전에 설치되어 있어야 합니다.

기본 사용법/명령어

doxybook2를 사용하기 전에 먼저 Doxygen으로 XML 파일을 생성해야 합니다. Doxyfile에서 GENERATE_XML = YES 및 XML_OUTPUT = xml 옵션을 활성화하고, doxygen 명령을 실행하여 XML 출력을 생성합니다. 그 후 다음과 같이 doxybook2를 실행합니다:

doxybook2 --input path/to/doxygen/xml --output path/to/destination

출력 형식을 제어하려면 설정 파일을 사용할 수 있습니다:

doxybook2 --input path/to/doxygen/xml --output path/to/destination --config path/to/config.json

JSON 전용 출력을 원한다면 다음과 같이 --json 플래그를 추가합니다:

doxybook2 --input path/to/doxygen/xml --output path/to/destination --json

설정 파일을 생성하려면 다음 명령을 사용합니다:

doxybook2 --generate-config /some/path/to/config.json

기본 템플릿을 파일 시스템에 덤프하려면 다음과 같이 실행합니다:

doxybook2 --generate-templates /path/to/folder

이런 경우에 유용합니다

C++ 프로젝트를 개발하고 Doxygen으로 API 문서를 생성하는 개발자에게 유용합니다. 생성된 XML을 마크다운으로 변환하여 GitHub Pages, 정적 사이트 생성기 기반의 문서 사이트 또는 내부 위키에 쉽게 배포할 수 있습니다. 특히 MkDocs나 Hugo와 같은 현대적인 정적 사이트 생성기를 선호하는 팀에게 적합하며, 템플릿과 설정을 통해 브랜드나 스타일에 맞는 문서 레이아웃을 적용할 수 있습니다.

지원 환경·시스템 요구사항

이 도구는 Windows (32비트 및 64비트), Linux (64비트 및 ARM 64비트), macOS (64비트)에서 컴파일 및 테스트되었습니다. Windows ARM64 아키텍처는 현재 테스트되지 않았으며 지원되지 않습니다. Doxygen 1.8.16 이상이 필수이며, 1.8.15는 작동할 수 있으나 권장되지 않습니다. 추가적인 시스템 라이브러리나 의존성은 필요하지 않으며, 모든 것은 정적으로 링크되어 있습니다.

최신 버전·업데이트

현재 버전은 1.5.0이며, 이 버전에서 개발자는 프로젝트가 아카이브되었음을 공지했습니다. 더 이상 새로운 기능 추가 또는 버그 수정이 계획되지 않았으며, 향후 업데이트는 예상되지 않습니다. 개발자는 개인적인 사유와 번아웃으로 인해 유지보수를 중단한다고 밝혔습니다.

제한 사항·확인 사항

이 프로젝트는 아카이브 상태이므로, 향후 버그 수정이나 기능 추가가 이루어지지 않을 수 있습니다. Windows ARM64 플랫폼은 지원되지 않으며, 이 아키텍처에서의 동작은 보장되지 않습니다. 또한 Doxygen 1.8.15 이하 버전에서는 정상적으로 작동하지 않을 수 있으므로, 1.8.16 이상을 사용하는 것이 권장됩니다. 템플릿이나 설정 파일을 커스터마이징할 때는 각 정적 사이트 생성기의 요구사항(예: MkDocs의 baseUrl, Hugo의 linkLowercase)을 충족하도록 구성해야 합니다.

화면으로 보는 주요 기능

Engine::Audio::AudioBuffer 클래스 참조 페이지

클래스 참조 페이지로, Public Classes에 TypedAudioData 구조체, Public Types에 AudioData typedef와 Type 열거형, Public Functions에 setData 및 loop 메서드가 표시됩니다. 왼쪽 탐색 메뉴에서 Classes가 선택되어 있고, 오른쪽 상단에 Grav 로고와 검색창이 있습니다.

Engine::Audio::AudioBuffer 클래스 참조 페이지 (다른 레이아웃)

클래스 참조 페이지로, Public Functions에 소멸자, stop, setData, play 메서드가 추가로 표시됩니다. 오른쪽에는 Public Classes, Public Types, Public Functions 등 다양한 문서 섹션 목록이 보이고, 왼쪽에는 Classes, Namespaces, Modules, Files, Pages 탐색 트리가 있습니다.

Engine::Audio::AudioBuffer 클래스 참조 페이지 (다른 레이아웃)

클래스 참조 페이지로, Public Functions에 setData, loop, stop, play, 소멸자, 파일 기반 생성자가 표시됩니다. 왼쪽 탐색 메뉴에서 Classes가 선택되어 있고, 오른쪽에는 Table of contents가 표시됩니다.

Engine::Audio::AudioBuffer 클래스 참조 페이지 (다른 레이아웃)

클래스 참조 페이지로, Public Functions에 setData, loop, stop, play, 소멸자, 파일 기반 생성자가 표시됩니다. 오른쪽에는 상세한 문서 섹션 목록과 Table of contents가 보이고, 왼쪽에는 Home, Classes, Namespaces, Modules, Files, Related Pages 탐색 트리가 있습니다.