Guidedog 설명서 0.2.0
언어
이 페이지의 내용
Guidedog / 문서 0.2.0

명령줄 참조

guidedog 명령줄 도구로 문서 프로젝트를 관리하고 빌드, 미리 보기, 번역, 변환할 수 있습니다.

기본 구문

guidedog <command> [arguments] [options]
guidedog --version
guidedog --help

종료 코드

표 6 종료 상태
종료 코드 조건
0 성공: 모든 작업이 완료되었으며 처리되지 않은 오류가 없습니다.
1 빌드 또는 변환 오류. -W 옵션으로 경고를 오류로 처리한 경우도 포함합니다.
2 명령줄 구문이 잘못되었거나 알 수 없는 플래그 또는 옵션을 사용했습니다.
3 설정한 자원 한도에 도달했거나 메모리를 확보할 수 없습니다.
4 파일 작업이나 외부 컴파일러가 실패했습니다.
5 내부 오류입니다. 진단 메시지에 보고 방법이 나옵니다.
70 충돌이 발생했습니다. 이전에 게시한 출력은 유지됩니다.

명령 개요

표 7 CLI 명령
명령 용도
quickstart [DIR] 문서 프로젝트를 만들고 바로 편집할 수 있는 템플릿과 설정을 생성합니다.
build [BUILDER] [DIR] 지정한 출력 형식으로 문서 프로젝트를 빌드합니다.
serve [DIR] 로컬 HTTP 미리 보기 서버를 시작하고 파일이 바뀌면 자동으로 다시 빌드합니다.
clean [DIR] 생성된 빌드 결과와 캐시를 삭제합니다.
convert INPUT 파일 하나 또는 표준 입력을 직접 변환합니다.
migrate [conf.py] Sphinx의 conf.py 를 선언형 conf.toml 로 변환합니다.
intl <update|stat> PO 번역 카탈로그를 갱신하거나 번역 진행 상황을 표시합니다.
formats 내장 리더와 렌더러, 형식별 적합성 정보를 표시합니다.
gds <COMMAND> Guidedog Discussions 설계 기록과 생명주기를 관리합니다.

guidedog quickstart

프로젝트 디렉터리에 conf.toml, index.rst, _templates/ 의 템플릿, _static/ 의 스타일을 생성합니다.

# Interactive prompt
guidedog quickstart docs

# Non-interactive creation with predefined options
guidedog quickstart docs -q -p "My Project" -a "Author Name" -v 1.0 -l en

옵션:

  • -q: 대화형 질문을 생략하고 명령줄에 지정한 값을 사용합니다.
  • -p, --project NAME: 표시할 프로젝트 이름을 지정합니다.
  • -a, --author NAME: 저자 또는 조직 이름을 지정합니다.
  • -v VERSION: 짧은 버전 번호를 지정합니다. 예: 1.0.
  • -r RELEASE: 전체 릴리스 식별자를 지정합니다. 예: 1.0.0-rc1.
  • -l LANGUAGE: 프로젝트 기본 언어를 지정합니다. 기본값은 en 입니다.
  • --sep: 루트에 소스를 두는 대신 source/ 와 build/ 디렉터리를 따로 만듭니다.
  • --suffix EXT: 소스 문서의 기본 확장자를 지정합니다. 기본값은 .rst 입니다.

guidedog build

소스 읽기, 목차 트리와 상호 참조 해석, 최종 결과 게시를 처리합니다.

# Standard project build
guidedog build html docs
guidedog build pdf docs

# Sphinx-build compatibility syntax
guidedog build -b html docs _build/html
guidedog build -M html docs _build

지원하는 빌더:

  • html: 검색과 탐색 기능을 갖춘 HTML 사이트를 생성합니다.
  • dirhtml: dir/index.html 과 같은 디렉터리 형태의 HTML URL을 생성합니다.
  • singlehtml: 모든 문서를 하나의 HTML 페이지로 합칩니다.
  • pdf: Typst로 PDF 책을 조판합니다. 별칭은 latex, latexpdf 입니다.
  • text: 문서마다 일반 텍스트 파일을 생성합니다.
  • gettext: 번역할 문자열을 GNU gettext POT 템플릿으로 추출합니다.
  • dummy: 최종 파일을 쓰지 않고 문서 트리를 파싱하고 참조를 해석합니다. 구문 확인용입니다.

빌드 옵션:

  • -a: 수정 시각과 관계없이 모든 출력 파일을 씁니다.
  • -E: 캐시된 상태를 무시하고 환경을 새로 만듭니다.
  • -W: 경고가 있으면 빌드 실패로 처리합니다.
  • --keep-going: -W 를 사용해도 남은 문서를 계속 처리하여 종료 전에 모든 오류를 보고합니다.
  • -n: 해결되지 않은 모든 상호 참조에 경고를 냅니다.
  • -j N / -j auto: 문서 파싱에 사용할 스레드 수를 지정합니다. auto 는 CPU 코어 수에 맞춥니다.
  • -D name=value: 이번 실행에서만 conf.toml 설정을 덮어씁니다. 예: -D language=de.
  • -D table.key=value: html_context 같은 표 설정의 키 하나만 설정하고 나머지 키는 그대로 둡니다. sphinx-build와 같습니다.
  • -t TAG: only 지시문에 사용할 조건 태그를 정의합니다.
  • -c DIR: conf.toml 이 있는 디렉터리를 지정합니다.
  • -C: conf.toml 파일을 읽지 않고 빌드합니다.
  • -v: 상세 모드로 안내 메시지와 소요 시간을 표시합니다.
  • -q: 경고와 오류만 표시합니다.
  • --color=always|never|auto: 터미널의 ANSI 색상 출력을 제어합니다.
  • --diagnostics=json: 프로그램이 읽을 수 있는 JSON 진단을 표준 오류로 출력합니다.
  • --budget=MIB: 프로젝트 호스트가 보유할 메모리 예산의 상한을 지정합니다. 기본값은 1024 MiB입니다.
  • --memory=ram|disk: 메모리 예산을 소진했을 때의 처리 방식을 지정합니다.
  • --untrusted: 원시 임베디드 마크업을 생략하고 네트워크 가져오기를 비활성화합니다. 이는 기능 제한 정책이며 프로세스 샌드박스는 아닙니다.

guidedog serve

로컬 HTTP 서버와 파일 감시기를 시작합니다. 소스 문서, 템플릿, 자산이 바뀌면 다시 빌드하고 브라우저를 새로 고칩니다.

# Serve current project on default port (8000)
guidedog serve docs

# Serve on custom port and host
guidedog serve docs --port 9000 --host 0.0.0.0

옵션:

  • -p, --port PORT: 로컬 수신 포트입니다. 기본값은 8000 입니다.
  • --host HOST: 바인딩할 IP 주소입니다. 기본값은 127.0.0.1 입니다.

guidedog clean

빌드 디렉터리와 환경 캐시를 삭제합니다.

guidedog clean docs

guidedog convert

프로젝트 디렉터리나 설정 없이 파일 또는 표준 입력을 직접 변환합니다.

# Convert reStructuredText to HTML
guidedog convert guide.rst --output guide.html

# Convert Markdown to PDF
guidedog convert guide.md --to pdf --output guide.pdf

# Stream conversion from standard input to standard output
cat document.md | guidedog convert - --from commonmark --to html --output -

옵션:

  • -o, --output FILE: 출력 파일 경로입니다. - 는 표준 출력입니다.
  • --to FORMAT: 출력 형식은 html, pdf, text 입니다. 파일 이름으로도 추론합니다.
  • --from FORMAT: 입력 리더는 rst, commonmark, myst, typst 입니다. 입력 확장자로도 추론합니다.
  • --force: 확인 없이 기존 출력 파일을 덮어씁니다.
  • --strict: 경고가 하나라도 있으면 실패합니다.
  • --raw=allow|omit: 원시 임베디드 코드 처리 정책입니다. 기본값은 omit 입니다.
  • --emit-typst FILE: 생성한 중간 Typst 소스를 별도 파일에 저장합니다.

guidedog migrate

Sphinx의 Python 설정 파일 conf.py 를 선언형 conf.toml 로 변환합니다.

# Convert conf.py in-place
guidedog migrate docs/conf.py

# Output to a specific file
guidedog migrate docs/conf.py -o docs/conf.toml --force

옵션:

  • -o FILE: 지정한 경로에 저장합니다. - 는 표준 출력입니다.
  • --force: 기존 conf.toml 을 덮어씁니다.

guidedog intl

다국어 문서의 번역 카탈로그를 관리합니다.

# Step 1: Extract POT templates
guidedog build gettext docs

# Step 2: Create or update language PO catalogs
guidedog intl update -l de -l fr docs

# Check translation completion percentages
guidedog intl stat -l de docs

intl update 옵션:

  • -l, --language LANG: 대상 언어 코드입니다. 여러 언어를 반복 지정할 수 있습니다.
  • -p, --pot-dir DIR: 추출된 POT 메시지 템플릿의 경로를 지정합니다.

guidedog formats

내장 리더, 렌더러, 구문 강조 렉서와 명세 테스트의 적합성 결과를 표시합니다.

guidedog formats

guidedog gds

Guidedog Discussions 아키텍처 설계 제안(RFC)을 관리합니다.

guidedog gds new "Feature Title" --author="Name"
guidedog gds list --state=prediscussion
guidedog gds show 0003
guidedog gds promote 0003 --dry-run
guidedog gds state 0003 --to=accepted --reason="Consensus reached"
guidedog gds index
guidedog gds check --render
guidedog gds recover --rollback