GitLab CLI (glab) 문서화 스타일 가이드

glab CLI 참조 문서의 필수 구조, 콘텐츠, 언어 규칙과 Go 소스 기반 문서 생성 방법을 설명합니다.

이 가이드라인은 glab CLI 참조 문서에 필요한 구조, 콘텐츠 및 언어 규칙을 정의합니다. 다음과 같은 경우 이 가이드라인을 사용하세요: gitlab-org/cli 에 새 glab 명령어를 추가할 때 CLI 문서가 되는 Go 소스 문자열을 업데이트할 때 CLI 문서를 추가하거나 변경하는 머지 리퀘스트를 리뷰할 때 이 가이드라인이 문서 스타일 가이드 와 다른 경우, 페이지 구조, 개요 문구, 플래그 설명, 사용 중단 메시지와 같은 CLI 특화 콘텐츠는 이 페이지를 따르세요. 대문자 표기, 문체, 일반 용어처럼 여기서 다루지 않는 규칙은 문서 스타일 가이드를 따르세요. CLI 문서 생성 방법 # CLI 문서는 gitlab-org/cli 의 Go 소스 파일에서 생성됩니다. 생성기( make gen-docs )는 명령어마다 하나의 Markdown 파일을 생성하고 출력을 docs/source/ 에 저장합니다. 생성된 파일은 GitLab CLI (glab) 문서의 단일 진실 공급원(Single Source Of Truth, SSOT)입니다. docs/source/ 에 있는 파일을 직접 편집하지 마세요. 모든 콘텐츠는 Go 소스에서 작성해야 합니다. 생성된 파일에 대한 변경은 다음에 make gen-docs 를 실행할 때 덮어쓰입니다. 생성 출력에 영향을 주는 Go 소스 문자열을 변경한 경우, make gen-docs 를 실행하고 업데이트된 파일을 머지 리퀘스트의 일부로 커밋하세요. check_docs_update CI/CD job은 make gen-docs 를 실행하여 생성된 파일에 커밋되지 않은 변경 사항이 있으면 실패합니다. 커밋을 푸시하기 전에 문서 문제를 포착하려면 make bootstrap 을 실행하여 Lefthook을 설치하세요. pre-commit 훅은 명령어 파일이 변경되면 문서를 재생성하고, 업데이트된 파일이 스테이징될 때까지 커밋을 차단합니다. 자세한 내용은 Lefthook을 사용한 Git 훅 을 참조하세요. 페이지 구조 # 생성된 모든 CLI 문서 페이지에는 다음 섹션이 이 순서대로 포함되어야 합니다: 제목(Title) 짧은 설명(Short description) 개요(Synopsis) 별칭(Aliases) (명령어에 별칭이 있는 경우) 예시(Examples) 옵션(Options) 상위 명령어에서 상속된 옵션(Options inherited from parent commands) 하위 명령어(Subcommands) (명령어에 하위 명령어가 있는 경우) 다음 표는 각 페이지 섹션과 이를 생성하는 Go 소스 필드 간의 매핑을 보여줍니다: 페이지 섹션 Go 소스 제목(Title) CommandPath() 메서드에서 가져온 전체 명령어 경로. 짧은 설명(Short description) cobra.Command의 Short 필드. 개요(Synopsis) cobra.Command의 Long 필드. 사용법 줄(Usage line) cobra.Command의 UseLine() 메서드. 별칭(Aliases) cobra.Command의 Al