AnkiHelper 0.1.2

Default template for PDM package

AnkiHelper

JSON으로 작성한 Q&A 노트 묶음을 genanki를 이용해 한 번에 .apkg 파일로 변환해 주는 경량 CLI입니다. notes/ 디렉토리(기본값) 아래에 있는 모든 JSON 노트를 재귀적으로 찾아 하나의 덱으로 묶어 주기 때문에, 폴더 단위로 노트를 모아 두기만 하면 바로 학습 덱을 만들 수 있습니다.

---

핵심 기능

• 스키마 기반 노트 정의: anki-helper.qa.v1 스키마(JSON) 하나로 모든 Q&A 노트를 일관된 형식으로 관리합니다.
• 자동 파일 스캔: notes_dir 아래의 모든 *.json을 재귀적으로 읽어 동일한 덱으로 묶습니다.
• 스타일 지정 템플릿: src/anki_helper/template.py에서 카드 HTML/CSS를 통째로 커스터마이징할 수 있습니다.
• 간결한 CLI: 위치 인자로 루트 덱 이름만 넘기면 되고, --notes-dir, --output 옵션으로 입출력을 제어합니다.

---

요구 사항

• Python 3.9+
• PDM (또는 pip/venv 조합)
• Anki Desktop는 생성된 .apkg만 있으면 별도 설정이 필요 없습니다.

---

빠른 시작

git clone https://github.com/USER/AnkiHelper.git
cd AnkiHelper
pdm install          # 또는 python -m venv .venv && .venv/bin/pip install -e .

1. notes/ 디렉토리를 만들고, 원하는 만큼 하위 폴더/JSON 파일을 추가합니다.
2. 아래 예시처럼 스키마를 포함한 Q&A JSON을 작성합니다.
3. 덱을 빌드합니다.

pdm run anki-helper "Interview Prep" \
  --notes-dir notes \
  --output interview_prep

# 결과: ./interview_prep.apkg

참고
CLI 도우미: pdm run anki-helper -h 또는 --version

---

노트 JSON 스키마

공식 정의는 src/schema/anki_schema_qa/anki_schema_qa_v1.json에 있습니다. 최상위 키는 schema, notes이며 note_type은 선택입니다.

{
  "schema": "anki-helper.qa.v1",
  "notes": [
    {
      "question": "HTTP/2의 Multiplexing이란?",
      "answer": "하나의 TCP 연결에서 ...",
      "tags": ["network", "http"]
    }
  ]
}

• schema: 현재는 anki-helper.qa.v1만 지원합니다.
• notes: 각 노트는 question, answer, (선택) tags 배열을 가집니다.
• 추가 스키마를 만들고 싶다면 src/anki_helper/model.py와 json_reader.py를 확장하면 됩니다.

---

노트 디렉토리 구성

• 프로그램은 notes_dir 아래의 모든 *.json 파일을 재귀적으로 탐색합니다.
• 디렉토리 구조는 파일 정리를 돕는 용도일 뿐, 생성되는 덱은 항상 하나입니다.
• 특정 폴더만 사용하고 싶다면 그 폴더를 --notes-dir 인자로 직접 넘기면 됩니다.

notes/
├─ backend/http.json
└─ os/process.json

위와 같은 구조라도 pdm run anki-helper "CS"로 실행하면 CS라는 하나의 덱 안에 모든 카드가 들어갑니다. 빈 덱이 나온다면 지정한 notes 경로에 JSON 파일이 있는지 다시 확인해 주세요.

---

카드 템플릿 커스터마이징

• HTML/CSS: src/anki_helper/template.py
• 모델 정의: src/anki_helper/model.py
• 템플릿을 수정한 뒤 다시 빌드하면 즉시 변경 사항이 적용된 덱을 얻을 수 있습니다.

---

개발/유지보수

PDM 스크립트를 그대로 사용할 수 있습니다.

pdm run lint        # Ruff
pdm run fmt-code    # Ruff formatter
pdm run fmt-docstrings
pdm run type-check  # mypy

실행 테스트는 pdm run anki-helper ...로 실제 덱을 만들어 보는 것이 가장 빠릅니다.

---

아키텍처 한눈에 보기

1. main.py에서 CLI 인자를 파싱하고 JSON 파일 목록을 찾습니다.
2. json_reader.py가 스키마에 맞춰 genanki.Note 리스트를 생성합니다.
3. builder.py가 무작위 덱 ID를 생성해 genanki.Deck을 만들고,
4. save_deck_to_file이 .apkg 파일로 저장합니다.

---

라이선스

MIT

아이디어나 개선점이 있다면 Issue/PR 모두 환영합니다. 😊