redhat-community-ai-tools/code-to-docs

AI 기반 GitHub Action으로, 코드 변경 사항을 자동으로 분석하고 모든 OpenAI 호환 LLM(OpenShift AI의 vLLM, Gemini, OpenAI 등)을 사용하여 문서를 업데이트합니다.

Pull Request에 댓글 작성:

• 코드 변경 사항을 분석하고 관련 문서 파일을 식별한 다음, 각 제안을 수락하거나 거부할 수 있는 체크박스가 포함된 검토 댓글을 게시합니다[review-docs]

• 이전 검토에서 승인된 파일만으로 docs PR을 생성하거나(검토가 없는 경우 전체 파이프라인 실행)[update-docs]

• [review-feature] PROJ-123 실행

[review-docs]

그리고 Jira 티켓 및 연결된 사양 문서(Confluence, Google Docs)를 가져와 요구 사항을 PR 코드 변경 사항과 비교하고 커버됨, 누락됨, 계획되지 않은 변경 사항을 식별하는 사양 대 코드 분석 (Spec vs Code Analysis) 섹션을 추가합니다.

• 댓글 작성
  [review-docs]

AI가 업데이트가 필요하다고 식별한 문서 파일 목록을 확인하고 - 업데이트를 원하지 않는 파일은 체크 해제하세요

• 댓글 작성
  [update-docs]

체크된 파일만으로 PR을 생성합니다.

사용자의 [update-docs] 댓글에 지침을 추가하여 AI가 문서 업데이트를 생성하는 방식을 안내할 수 있습니다. filename.ext: instruction 형식의 줄은 개별 파일 지침이며, 나머지 모든 줄은 LLM에 전달되는 전역 지침입니다:

[update-docs] keep changes minimal, here are usage examples for context:
## Example usage
my-tool --flag value
...

반복적인 AI 생성 업데이트에 자동으로 적용되는 저장소 수준의 문서 스타일 규칙을 정의할 수 있습니다. 다음 파일을 리포지토리 루트에 생성하세요:

— 자유 형식 마크다운/산문, LLM에 그대로 전달됩니다.code-to-docs/style.md

이 액션은 이 파일을 자동으로 감지합니다. 대신 사용자 지정 경로를 사용하려면 style-config-path 액션 입력을 설정하세요.

예시 .code-to-docs/style.md:

# Documentation Style
- **능동태(active voice)**와 전문적인 어조를 사용하세요
- 제목에는 문장 케이스를 사용하세요
...

댓글별 지침 ([update-docs] keep changes minimal

) 지속적으로 설정된 구성과 함께 작동하며, 스타일 가이드라인 다음에 추가적인 지침으로 나타납니다. 주석별 또는 파일별 지침이 스타일 가이드라인과 모순되는 경우, 검토자의 지침이 우선합니다.

저장소 루트에 있는 JSON 구성 파일을 사용하여 code-to-docs 동작을 구성할 수 있습니다:

— 도구 설정 (base 브랜치에서 로드되며, PR 브랜치는 아님) `.code-to-docs/config.json``

지원되는 설정:

예시 .code-to-docs/config.json:

{
"pr-title-prefix": ":book:"
}

이 구성 파일을 사용하면, 생성된 PR은 docs: update documentation from PR #123 대신 :book: docs: update documentation from PR #123라는 제목을 갖게 됩니다.

.

이 파일은 선택 사항입니다. 누락된 경우, 도구는 접두사 없이 기본 제목을 사용합니다.

PR 댓글로 트리거됨 - 누군가 풀 리퀘스트(Pull Request)에 [review-docs], [update-docs], 또는 [review-feature]를 댓글로 달 때
코드 변경 분석 - AI를 사용하여 PR의 git diff를 검사합니다
스마트 파일 선택 - 관련 문서 파일을 자동으로 식별합니다
대화형 검토 - 사용자 큐레이션을 위한 체크박스와 함께 제안을 제시합니다
콘텐츠 생성 - AsciiDoc, Markdown 또는 reStructuredText 형식으로 업데이트된 문서를 생성합니다
Spec vs Code 분석 - Jira 티켓 및 연결된 사양 문서(Confluence, Google Docs)를 가져와 요구사항과 PR 구현 간의 격차를 식별합니다.

.github/workflows/docs-assistant.yml 파일을 생성하세요

:

name: Documentation Assistant
on:
issue_comment:
...

설정 → Secrets → Actions에 이것들을 추가하세요:

이들은 워크플로우 단계에서 with: 매개변수로 설정됩니다 (시크릿으로 설정되지 않음):|

@v1 | 모든 하위 호환 업데이트를 받습니다 (권장)<br>@v1.1.2 | 정확한 릴리스에 고정됩니다<br>@main | 출시되지 않은 변경 사항을 추적하며 안정적이지 않습니다

OpenAI와 호환되는 API라면 무엇이든 작동합니다. 일반적인 예시:

| 백엔드 | MODEL_API_BASE |
MODEL_NAME |
|---|---|---|
| vLLM on OpenShift AI | https://my-model-predictor-namespace.apps.cluster.example.com/v1 |
Your InferenceService 이름 (/v1/models 확인) |
| Gemini | https://generativelanguage.googleapis.com/v1beta/openai/ |
gemini-2.0-flash |
| OpenAI | https://api.openai.com/v1 |
gpt-4o |
| Ollama | http://localhost:11434/v1 |
llama3.1 |

• 🤖
  AI 기반 분석 (AI-Powered Analysis) - 관련 문서를 식별하기 위해 모든 OpenAI 호환 LLM을 사용합니다.
• 📝 스마트 제안 (Smart Suggestions) - 필요한 부분만 업데이트합니다.
• 🔍 리뷰 모드 (Review Mode) - 적용 전에 변경 사항을 확인합니다.
• ⚡ 자동 업데이트 모드 (Auto-Update Mode) - PR(Pull Request)을 자동으로 생성합니다.
• 📚 형식 지원 (Format Support) - AsciiDoc, Markdown, reStructuredText(.rst)를 지원합니다.
• 🚀 최적화된 성능 (Optimized Performance) - 시맨틱 인덱스 및 캐시된 요약으로 API 호출을 줄입니다.
• 🔍 사양 대 코드 분석 (Spec vs Code Analysis) - Jira 사양 문서와 PR 변경 사항을 비교하여 커버된, 누락된, 계획되지 않은 변경 사항을 찾습니다.

The [review-feature]

명령어는 전체 [review-docs] 흐름(관련 문서 파일 식별 및 업데이트 제안)을 실행하고 사양 대 코드 분석 (Spec vs Code Analysis) 섹션을 추가합니다. 이 명령어는 Jira 티켓과 연결된 사양 문서를 가져와 요구사항을 추출하고, PR 코드 변경 사항과 비교하여 커버된, 누락된, 계획되지 않은 변경 사항을 식별합니다.

사양 문서는 Jira 티켓 설명 또는 댓글에서 연결될 수 있습니다. 지원되는 형식은 다음과 같습니다:

Google Docs — Google 서비스 계정 키(GOOGLE_SA_KEY secret)가 필요하며, 문서가 서비스 계정 이메일과 공유되어야 합니다.Confluence — 동일한 Jira 자격 증명(동일 Atlassian 인스턴스)을 사용하여 가져옵니다.

자동으로 가져올 수 없는 링크는 검토를 위해 리뷰에서 플래그 지정됩니다.

The [review-feature]

댓글에는 Jira 티켓 및 연결된 사양 문서(요구사항, 설명, 분석)의 내용이 포함됩니다. 이 댓글은 PR에 접근 권한이 있는 모든 사람에게 표시됩니다. 저장소의 가시성 설정이 Jira 및 사양 문서 콘텐츠의 민감도에 적절한지 확인하십시오.

Python 3.12 이상을 요구합니다. 패키지 관리를 위해 uv를 사용합니다.

# 종속성 설치 (개발 도구 포함)
uv sync --extra dev
# 테스트 실행
...

CI는 모든 PR에 대해 lint, 형식 지정, 그리고 60%의 테스트 커버리지 임계값을 강제합니다.

이 액션은 .doc-index/에 저장되는 시맨틱 인덱스를 빌드합니다.

폴더 인덱스(Folder Indexes) — 각 문서 폴더별 요약본으로, 파일별 설명도 포함됩니다. LLM은 실제 파일 내용을 로드하지 않고 이 설명들에서 관련 파일을 직접 선택하므로 API 호출과 런타임을 줄입니다.

인덱스는 PR을 통해 메인 브랜치에 자동으로 제출되며, 병합되면 모든 PR에서 공유되어 대규모 프로젝트의 런타임을 약 20분에서 약 4분으로 단축합니다.