[Documentation] Sphinx와 Doxygen을 활용한 프로젝트 문서화

 

Sphinx는 파이썬 프로젝트에 자주 사용되는 강력한 문서화 도구이지만, Doxygen과 연동하면 C, C++, Java 등 다양한 언어의 문서화도 가능하다. 본 글에서는 Sphinx와 Doxygen을 함께 활용하여 다중 언어 프로젝트를 문서화하는 방법을 설명한다.

 

 

1. Doxygen이란?

Doxygen은 C, C++, Java, Python, Fortran, VHDL 등 여러 언어의 소스 코드를 문서화할 수 있는 도구이다. Doxygen은 코드 내 주석을 기반으로 HTML, LaTeX, PDF 등의 문서를 생성할 수 있다.

 

 

2. Doxygen 설치

Doxygen은 공식 웹사이트에서 다운로드하거나 패키지 관리자를 통해 설치할 수 있다.

 

Linux:

sudo apt-get install doxygen

 

macOS:

brew install doxygen

 

Windows: Doxygen 공식 웹사이트에서 설치 프로그램을 다운로드하여 설치할 수 있다.

 

 

3. Doxygen 설정 파일 생성

Doxygen을 사용하려면 프로젝트 디렉토리에서 설정 파일을 생성해야 한다.

 

doxygen -g

 

이 명령어는 Doxyfile이라는 설정 파일을 생성한다. Doxyfile을 열어 주요 설정을 변경할 수 있다. 주요 설정 항목은 다음과 같다:

• PROJECT_NAME: 프로젝트 이름 설정.
• OUTPUT_DIRECTORY: 문서가 생성될 디렉토리.
• INPUT: 소스 코드가 위치한 디렉토리.
• GENERATE_XML: Sphinx와 연동하기 위해 YES로 설정.

PROJECT_NAME = "My Project"
OUTPUT_DIRECTORY = "docs"
INPUT = "src"
GENERATE_XML = YES

 

 

 

4. Sphinx와 Doxygen 연동

Sphinx와 Doxygen을 연동하기 위해 Breathe라는 Sphinx 확장을 설치해야 한다. Breathe는 Doxygen이 생성한 XML 출력을 Sphinx에서 사용할 수 있도록 돕는다.

 

pip install breathe

 

그 후, Sphinx 프로젝트를 생성하고 설정 파일(conf.py)을 다음과 같이 수정한다:

import os
import subprocess

# Doxygen으로 XML 문서 생성
subprocess.call('doxygen', shell=True)

# Breathe 설정
extensions = ['breathe']
breathe_projects = {"My Project": "docs/xml"}
breathe_default_project = "My Project"

 

이제 다음 명령어를 실행하면 Sphinx가 Doxygen과 연동된 문서를 생성할 수 있다.

make html

 

 

 

5. Doxygen 주석 작성

다음은 C++ 코드에 Doxygen 주석을 작성하는 예제이다:

/**
 * @brief 두 수를 더한 값을 반환한다.
 * @param a 첫 번째 숫자
 * @param b 두 번째 숫자
 * @return 두 수의 합
 */
int add(int a, int b) {
    return a + b;
}

 

이 주석은 Doxygen에 의해 문서화되며, Breathe를 통해 Sphinx에서 사용될 수 있다.

 

 

Sphinx와 Doxygen을 함께 사용하면 다양한 언어로 작성된 프로젝트를 효율적으로 문서화할 수 있다. Sphinx의 강력한 포맷팅 기능과 Doxygen의 다중 언어 지원을 결합하여 프로젝트의 문서화를 체계적으로 관리할 수 있다.