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

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

이 가이드라인은 glab CLI 참조 문서에 필요한 구조, 콘텐츠 및 언어 규칙을 정의합니다. gitlab-org/cli 프로젝트에서 make gen-docs 로 생성되는 Markdown 파일에 특화된 규칙으로, 문서 스타일 가이드 를 확장합니다. 다음과 같은 경우 이 가이드라인을 사용하세요: gitlab-org/cli 에 새 glab 명령어를 추가할 때 CLI 문서가 되는 Go 소스 문자열을 업데이트할 때 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의 Aliases 필드. 예시(Examples) cobra.Command의 Example 필드. 옵션(Optio