Python 파일을 PDF 또는 DOCX로 변환하는 방법 (LaTeX 설치 없이)

Source: Dev.to

.py 파일이 하나이든 여러 개이든 PDF나 Word 문서가 필요합니다. 과제 제출, 개발자가 아닌 사람에게 코드 공유, 인쇄 가능한 아카이브 생성, 혹은 오프라인에서 오픈소스 레포를 검토하려는 경우일 수 있습니다. 아래는 가장 일반적인 접근 방식들의 간결한 개요와 각 방법의 장단점, 그리고 언제 각각이 빛을 발하는지에 대한 설명입니다.

Pandoc

Pandoc은 성숙하고 널리 사용되는 문서 변환기로 .py를 DOCX 또는 PDF로 잘 처리합니다.

pandoc my_script.py -o output.docx
pandoc my_script.py -o output.pdf

• DOCX 출력은 별도의 의존성 없이 깔끔하게 작동합니다 — 명령줄에 익숙하다면 확실한 선택입니다.
• PDF 출력은 별도의 PDF 엔진이 필요합니다. 기본적으로 Pandoc은 LaTeX(Windows에서는 MiKTeX, macOS에서는 MacTeX)를 사용하며, 이는 큰 설치가 필요합니다. wkhtmltopdf나 weasyprint와 같은 가벼운 대안을 --pdf-engine 플래그로 사용할 수 있지만, 이들 역시 설치가 필요합니다.

Best for: CLI에 익숙한 개발자에게 무료이며 스크립트화 가능한 솔루션을 제공합니다. DOCX는 최소 설정으로 가능하고, PDF는 먼저 PDF 엔진을 선택하고 설치해야 합니다.

nbconvert (Jupyter 노트북용)

.ipynb 노트북을 다루고 있다면 nbconvert가 적합한 도구입니다. 셀 출력, 인라인 플롯, 마크다운 셀을 깔끔하게 처리합니다.

jupyter nbconvert --to html notebook.ipynb
jupyter nbconvert --to pdf notebook.ipynb

• 기본 지원 출력 형식에는 HTML, PDF, Markdown, script가 포함됩니다.
• DOCX는 네이티브 nbconvert 형식이 아니며 — DOCX로 변환하려면 Pandoc과 python-docx를 별도로 설치해야 합니다(필요한 의존성이 있으면 JupyterLab에서 File → Export As → Word 로 이용 가능).
• PDF 출력은 여전히 LaTeX 배포판이 필요합니다.

추천 대상: HTML 또는 PDF 내보내기가 필요한 데이터 과학자와 노트북 사용자. 일반 .py 파일에는 적용되지 않음.

Sphinx

Sphinx는 표준 Python 문서화 도구입니다. 소스 코드에서 전체 문서 사이트를 생성하며, make latexpdf는 PDF를 생성합니다.

• 설정이 복잡합니다: Sphinx를 설정하고, 올바른 형식의 docstring을 작성하며, LaTeX를 설치해야 합니다.
• 출력 품질이 뛰어납니다: 적절한 교차 참조, 모듈 인덱스, 그리고 전문적인 레이아웃을 제공합니다.

Best for: 유지 관리가 필요한 문서화를 필요로 하는 오픈소스 프로젝트에 적합합니다. 빠른 내보내기에는 과도하지만, 진지한 프로젝트를 위한 장기적인 투자로 견고합니다.

VS Code / 브라우저 인쇄

VS Code에서 프린트 확장자를 사용해 파일을 열거나 GitHub에서 보고 브라우저의 Print → Save as PDF를 사용합니다.

• 설치 필요 없고, 명령줄도 없으며 즉시 작동합니다.
• 출력 품질이 제한적입니다 — 여백과 페이지 나눔을 제어할 수 없고, 긴 줄이 잘릴 수 있으며, 목차가 없습니다.

추천 상황: 외관이 크게 중요하지 않은 단일 파일을 빠르게 대략 인쇄하고 싶을 때.

pBinder (Windows only)

pBinder는 Python 파일 및 프로젝트를 DOCX와 PDF로 변환하기 위해 특별히 제작된 휴대용 Windows EXE입니다. LaTeX도, Python 환경도, 설치도 필요하지 않으며—다운로드 후 바로 실행하면 됩니다.

• 단일 파일, 몇 개의 파일, 혹은 전체 프로젝트 디렉터리에서도 작동합니다.
• 탐색 가능한 문서를 생성합니다:
  • 프로젝트 폴더 트리가 포함된 클릭 가능한 목차
  • 로컬에 정의된 모든 클래스, 함수, 메서드를 하이퍼링크와 함께 나열한 심볼 디렉터리
  • 각 사용 위치를 정의로 연결하는 호출 위치 교차 참조

제한 사항: Windows 10 64‑bit 전용; PDF 내보내기는 Microsoft Word가 필요하고 (DOCX는 Word 없이도 작동합니다).

추천 대상: Pandoc이나 Sphinx와 같이 LaTeX 및 CLI 설정 없이 구조화되고 탐색 가능한 출력물을 원하는 Windows 사용자. 14일 무료 체험판을 이용할 수 있습니다.

Comparison Table

올바른 도구 선택

• 한 파일, 간편함: VS Code 또는 브라우저 인쇄.
• 노트북: nbconvert.
• DOCX 출력 스크립팅 (LaTeX 없음): Pandoc.
• 전체 프로젝트 문서화 (장기): Sphinx.
• Windows에서 탐색 가능한 DOCX/PDF, 설정 없이: pBinder.

모든 도구는 정당한 사용 사례가 있습니다. 올바른 선택은 사용 중인 OS, 설정에 투자할 의향이 있는 정도, 그리고 원하는 출력 품질에 따라 달라집니다.