AST Parsing과 Multi-Provider LLM을 활용한 Python 문서 자동화 방법

I’m happy to translate the article for you, but I’ll need the full text of the post (the content you’d like translated). Please paste the article’s body here, and I’ll provide a Korean translation while keeping the source link, formatting, markdown, and any code blocks unchanged.

소개

우리는 모두 그런 경험을 해봤습니다. 고도로 최적화되고 아름답게 설계된 새로운 기능을 만들기 위해 삼 일간 집중해서 작업했죠. 코드는 깔끔하고, 테스트는 통과하고, 린터는 완전히 조용합니다. 브랜치를 푸시하고 풀 리퀘스트를 열었는데, 현실이 트럭처럼 닥칩니다:

“아, 맞다. 문서를 업데이트해야겠네.”

솔직히 말해서, 문서 작성은 개발자들이 사랑하면서도 싫어하는 일입니다. 이상적인 세계에서는 문서가 코드와 함께 진화하지만, 실제로는 문서는 2023년에 머물러 있는 반면 애플리케이션 코드는 2025년을 향해 달려갑니다.

오랫동안 해결책은 수작업(수동으로 하는 일)이나, 약간 복잡한 파이썬 데코레이터나 중첩된 비동기 함수가 등장하는 순간 깨지는 부서지기 쉬운 정규식 기반 파서 중 하나였습니다.

저는 두 옵션 모두에 지쳤습니다. 그래서 지난 몇 주 동안 AutoDocGen(pypiautodocgen on PyPI)를 만들었습니다.

문자열을 찾는 영광스러운 grep 명령처럼 검색하는 대신, AutoDocGen은 파이썬 코드를 추상 구문 트리 (AST) 로 파싱합니다. 그것은 클래스가 무엇인지, private 메서드가 무엇인지, 모듈들이 어떻게 본질적으로 연결되어 있는지를 알고 있습니다. 이 청사진을 여러분이 선택한 대형 언어 모델에 전달해 인간이 읽기 쉬운, 완벽히 포맷된 마크다운 문서를 생성합니다.

제가 어떻게 이를 구축했는지, 마주한 기술적 난관은 무엇이었는지, 그리고 AST 파싱과 AI의 결합이 코드 문서화의 미래라고 믿는 이유에 대한 이야기를 전합니다.

1. 정규식 기반 문서화의 문제점

역사적으로 많은 경량 문서화 도구들은 정규식에 의존해 왔습니다. 이들은 파일을 한 줄씩 스캔하면서 def 혹은 class를 찾고, 뒤따르는 문자열을 추출한 뒤, 그 아래에 있는 docstring 블록을 잡으려 합니다.

이 접근 방식은 현대 파이썬 개발에 근본적으로 결함이 있습니다. 왜일까요? 파이썬 문법은 매우 표현력이 풍부하기 때문입니다.

@cache(ttl=3600)
@validate_schema(UserSchema)
async def fetch_user_data(
    user_id: uuid.UUID,
    include_history: bool = False
) -> Dict[str, Any]:
    """Fetches user data from the primary replica."""
    pass

정규식 파서는 데코레이터가 함수에 속한다는 것을 어떻게든 알아야 하고, 이를 비동기로 정확히 식별하며, 여러 줄에 걸친 시그니처와 타입 힌트를 파싱하고, docstring을 추출해야 합니다. 여기에 중첩 클래스, 클로저, 복잡한 반환 타입까지 추가되면 정규식은 금세 유지보수가 어려운 악몽으로 전락합니다.

정규식은 코드를 이해하지 못합니다; 텍스트 안의 패턴만 인식할 뿐입니다. 저는 파이썬 자체의 구조를 이해하는 도구가 필요했습니다.

2. Enter the Abstract Syntax Tree (AST)

Python includes a built‑in module called ast. It allows you to parse Python source code into a tree of nodes representing the syntactic structure of the program.

Instead of reading lines of text, AutoDocGen uses ast.parse() to read the “DNA” of your code.

When you feed the above snippet into an AST parser, it doesn’t see a string of text. It sees an AsyncFunctionDef node. It knows that this node has a decorator_list containing Call nodes. It maps out the arguments (complete with their type annotations) and gracefully extracts the exact docstring using ast.get_docstring().

By extracting this structured data, AutoDocGen builds a high‑fidelity “blueprint” of your codebase. We extract:

• Module‑level variables and logic
• Class definitions, their base classes (inheritance), and methods
• Standalone functions (sync and async)
• Exact signatures and type hints

We then serialize this blueprint into a structured format (JSON or YAML representation of the AST summary).

This is the secret sauce. We aren’t asking the AI to read your code from scratch and guess what it does. We are giving the AI a structural map and asking it to explain the map. This drastically reduces LLM hallucinations and dramatically improves the quality of the generated documentation.

3. 공급업체 종속에서 탈피하기: 다중 제공자 지원

AI 생성 단계를 구축하기 시작했을 때, 현재 AI 개발자 도구 환경에 대한 큰 불만을 깨달았습니다: 거의 모든 도구가 OpenAI API를 하드코딩하고 있었습니다.

GPT‑4o가 놀라운 것은 사실이지만, 우리는 오픈 웨이트 모델과 눈부시게 빠른 추론 API의 황금기에 살고 있습니다. 사용자가 Google 도구를 선호하거나 Groq의 놀라운 속도를 원한다면 OpenAI에 묶여 있기를 원하지 않았습니다.

그래서 AutoDocGen 내에 다중 LLM 제공자를 지원하는 추상화 레이어를 구축했습니다:

구성 계층 구조는 유연합니다. 환경 변수(GROQ_API_KEY), 로컬 .env 파일, autodocgen.yaml 설정 파일, 혹은 pyproject.toml에 직접 설정하여 모든 것을 지정할 수 있습니다.

# autodocgen.yaml
version: 1
ai:
  provider: groq
  model: llama3-70b-8192
output:
  dir: ./docs
  format: markdown

4. 출력 템플릿화: 프리미엄 스타일을 위한 Jinja2

퍼즐의 마지막 조각은 출력 형식이었습니다. 대부분의 자동화된 문서화 도구는 지루하고 영감 없는 텍스트 블록을 생성합니다. 저는 기술 작가가 손수 만든 듯한 문서를 원했습니다.

Markdown을 포맷하기 위해 LLM에 의존하는 대신(이는 종종 일관성 없는 헤딩과 깨진 표를 초래합니다), AutoDocGen은 생성과 프레젠테이션을 엄격히 분리합니다.

LLM은 구조화된 데이터(모듈 요약, 기능에 대한 핵심 포인트 등)를 반환합니다. AutoDocGen은 이 데이터를 Jinja2 템플릿에 삽입하여 문서의 최종 모습과 느낌을 완전히 제어할 수 있게 합니다.

# example_template.md.j2
# {{ module.name }}

{{ module.summary }}

{% for cls in module.classes %}

## Class `{{ cls.name }}`

{{ cls.docstring }}

{% for method in cls.methods %}
### Method `{{ method.name }}{{ method.signature }}`

{{ method.docstring }}

{% endfor %}
{% endfor %}

생성과 렌더링을 분리함으로써 다음을 할 수 있습니다:

• 모든 문서에 일관된 스타일 가이드를 적용할 수 있습니다
• AI 코드를 수정하지 않고도 사용자 정의 섹션(예: 사용 예시, 변경 로그)을 추가할 수 있습니다
• 템플릿을 다른 출력 형식(HTML, PDF 등)으로 교체할 수 있습니다

5. 모두 합치기

AutoDocGen을 실행하는 것은 다음과 같이 간단합니다:

autodocgen path/to/your/package

그 뒤에서 수행되는 작업은 다음과 같습니다:

1. 소스 트리를 순회하며 ast를 사용해 각 .py 파일을 파싱합니다.
2. 전체 패키지에 대한 통합 JSON/YAML 청사진을 생성합니다.
3. 청사진(또는 관련 청크)을 설정된 LLM에 전송합니다.
4. 구조화된 문서 조각들을 받아옵니다.
5. Jinja2 템플릿을 통해 조각들을 렌더링합니다.
6. 지정한 output.dir에 최종 Markdown 파일을 씁니다.

그 결과, 코드베이스와 동기화된 깔끔하고 사람이 읽기 쉬운 문서 세트가 생성되며, 실질적으로 수동 유지보수가 필요 없고 매 CI 실행마다 재생성할 수 있습니다.

6. 왜 이것이 중요한가

• 신뢰성: AST 파싱은 텍스트 패턴이 아닌 실제 코드 구조를 보고 있음을 보장합니다.
• 속도: 대규모 레포지토리에서 정규식 기반 도구가 멈추는 데 몇 분을 기다릴 필요가 없습니다.
• 유연성: 다중 제공자 LLM 지원을 통해 예산, 지연 시간, 프라이버시 요구사항에 맞는 모델을 선택할 수 있습니다.
• 품질: 구조화된 프롬프트와 Jinja2 렌더링을 결합하면 일관되고 전문 수준의 문서를 만들 수 있습니다.

요약하면, AutoDocGen은 언어 인식 파싱과 최신 LLM을 결합하면 문서를 지속적으로 유지하는 실용적이고 확장 가능한 방법임을 보여줍니다.

사용해 보기

pip install pypiautodocgen
autodocgen ./my_project --config autodocgen.yaml

이슈를 열거나 PR을 제출하거나 Jinja2 템플릿을 직접 스타일 가이드에 맞게 커스터마이징한 방법을 공유해 주세요. 문서화 즐겁게 하세요!

일관된 프리미엄 미학

Jinja2(module.md.j2 및 index.md.j2)를 사용하면 CLI가 전체 문서 사이트에 걸쳐 일관되고 프리미엄한 미학을 보장합니다. 함수 시그니처를 완벽하게 포맷하고, 자동 목차를 생성하며, 관련 모듈을 교차 연결합니다.

기본 템플릿이 마음에 들지 않으면 templates/ 디렉터리를 쉽게 포크하여 직접 만들 수 있습니다.

Source: …

5. Security First: The “Zero‑Trust” QA Audit

AI 도구를 출시하면서 소스 코드를 읽어들이는 만큼 보안과 안정성이 최우선이어야 한다는 것을 알았습니다. 단순히 몇 개의 유닛 테스트만 작성하고 끝내지는 않았습니다.

v0.1.0에 도달하기 전에, 프로젝트는 제가 Zero‑trust Forensic QA Audit 라고 부르는 과정을 거쳤습니다. 초기 프로토타입 코드는 완전히 깨졌다고 가정하고, 테스트 스위트를 처음부터 새로 구축했습니다.

우리는 다음을 활용했습니다:

• pytest를 사용한 포괄적인 유닛 및 통합 테스트.
• bandit을 이용한 보안 스캔으로 API 키가 로그에 절대 유출되지 않으며 파일 I/O 작업이 안전하도록 보장.
• 모든 LLM 제공자를 광범위하게 모킹하여 CLI를 CI/CD 환경에서 API 크레딧을 소모하지 않고 깊이 있게 테스트.
• 엣지 케이스 테스트, 여기에는 이국적인 유니코드 식별자 처리도 포함 (예: def grüne_äpfel() 가 완벽히 파싱됨).

이 저장소는 이제 Codecov와 완전히 통합되어, 향후 모든 풀 리퀘스트에 대해 엄격한 기준선을 유지합니다.

시작하기

README 파일이 코드베이스와 동기화되지 않아 지치셨다면, AutoDocGen을 사용해 보시길 강력히 권장합니다. 현재 PyPI에 공개되어 있습니다.

설치

pip install pypiautodocgen

실행

autodocgen -o ./docs --provider groq   # Or openai, gemini, openrouter

현재 디렉터리의 문서를 생성하고 ./docs에 출력합니다.

로드맵

현재 AutoDocGen은 MkDocs와 같은 정적 사이트 생성기나 GitHub에서 직접 사용하기에 완벽한 멋진 Markdown 파일을 생성합니다.

앞으로 탐구하고 싶은 내용은 다음과 같습니다:

• 프레임워크‑특화 파싱 – FastAPI 엔드포인트 또는 Django 모델을 위한 특수 템플릿.
• Diff‑기반 업데이트 – 전체 파일을 재생성하는 대신 커밋에서 변경된 함수에 대한 문서만 재생성.
• Mermaid 다이어그램 생성 – AST import를 기반으로 자동으로 아키텍처 흐름도를 생성.

연결해요!

AutoDocGen을 만들게 된 이유는 저의 불편함을 해결하기 위해서였지만, 커뮤니티가 가지고 있는 놀라운 아이디어로 더 발전시킬 수 있을 것이라 믿습니다.

GitHub에서 소스 코드를 확인해 보세요 (유용하다고 생각되면 별도(star)도 눌러 주세요!):

https://github.com/shifulegend/autodocgen

댓글로 여러분의 의견을 들려 주세요. 아직도 직접 문서를 작성하고 계신가요? 기존 자동 생성 문서 도구를 사용하면서 가장 크게 느꼈던 불편함은 무엇인가요? 알려 주세요!