Guidedog / 문서 0.2.0

Sphinx 호환성¶

Guidedog는 프로젝트 이전에 도움이 되는 부분에서 Sphinx를 따르며, 기능별로 호환성을 평가합니다. Python 설정이나 임의의 Python 확장은 실행하지 않습니다. 빌드 성공은 빌드가 완료되었다는 근거일 뿐, 완전한 동등성을 증명하지는 않습니다.

프로젝트와 게시¶

표 20 프로젝트 작업¶
작업	구현된 동작
프로젝트 구조와 빌드 옵션	Sphinx 방식의 소스·출력 디렉터리와 옵션: `-a -E -W -n -D -t -j -b -M -c -C`.
설정	익숙한 Sphinx 설정 이름을 TOML 데이터로 작성합니다. 마이그레이션은 리터럴을 변환하고 계산이 필요한 값을 알립니다.
HTML 빌더	`html`, `dirhtml`, `singlehtml`을 지원합니다. 단일 페이지의 앵커에는 문서 이름이 포함됩니다.
다른 빌더	`text`, `gettext`, `dummy`를 지원합니다. `pdf`는 Typst를 사용하며, `latex`와 `latexpdf`도 같은 경로를 선택합니다.
템플릿	Guidedog의 Jinja 구현, 타입을 유지하는 `html_context`, 레이아웃 상속, 추가 페이지.
증분 빌드	소스, 의존성, 템플릿, 설정, 참조 조회가 바뀌면 관련 출력이 무효화됩니다.
게시	완전한 출력 세대를 게시합니다. 빌드가 실패하면 이전에 게시한 세대를 유지합니다.

-D의 불리언 값은 true와 false 또는 1과 0을 받습니다. index 없이 contents가 있으면 경고와 함께 contents를 루트로 사용할 수 있습니다. 추가 템플릿 페이지는 dirhtml에서도 사이트 루트에 놓입니다. 정확한 규약은 템플릿를 참고하세요.

변경되지 않은 페이지도 진단을 다시 보고하므로 -W는 새 빌드와 변경 없는 빌드에서 같은 의미를 갖습니다. 삭제된 문서의 페이지는 제거합니다. 게시는 복구 가능한 저널을 사용하며, 중단된 커밋은 다음 빌드에서 정리합니다. 불변식과 플랫폼 경계는 완전한 출력 세대 게시을 참고하세요.

epub, man, texinfo, linkcheck, doctest, coverage, changes 빌더는 제공하지 않습니다. 사용하면 수정 안내를 표시합니다. 저장소의 tools/linkcheck는 별도 검증 도구입니다.

소스 언어¶

표 21 고정 버전의 적합성 검증¶
리더	검증 결과와 한계
reStructuredText	코퍼스 소스 98개에서 비교 대상 Docutils 트리와 식별자가 일치합니다. 비교에서 소스 위치와 일부 내부 관리 속성은 제외합니다.
CommonMark 0.31.2	명세 예제 652개가 모두 통과합니다.
MyST 0.16.1 reference	리더 테스트 218개 중 215개, Sphinx 빌드 테스트 10개 중 8개가 일치합니다. 나머지 차이는 기록되어 있습니다.

고정 버전의 테스트이며, 이후 모든 버전과의 호환성을 뜻하지 않습니다. guidedog formats로 실행 파일의 리더와 렌더러 검증 정보를 확인하세요. 각 리더 디렉터리에도 적합성 설명이 있습니다.

rst_prolog는 시작 부분의 서지 필드 뒤에, rst_epilog는 소스 뒤에 삽입합니다. Markdown에는 둘 다 삽입하지 않습니다. only와 ifconfig는 조건이 참이면 내부 절을 유지합니다. 조건부 절이 주변 절의 수준을 바꾸면 배치가 Sphinx와 다를 수 있습니다. MyST의 eval-rst 안에 절 제목이 있으면 오류입니다.

참조와 도메인¶

Guidedog는 toctree, 레이블, 용어집, 절·그림 번호와 ref, doc, numref, term, download, any, keyword, option, envvar, token 참조를 구현합니다. 객체는 목차 트리, 사이드바, 페이지 개요에 나타날 수 있습니다.

표준, Python, C, C++, JavaScript, reStructuredText, 수학 도메인이 구현되어 있습니다. Odin 도메인은 Guidedog 전용 확장으로 패키지, 선언, 시그니처, 생성된 API 페이지를 설명합니다. 소스만 사용하는 탐색과 한계는 Odin 문서화을 참고하세요.

매개변수, 반환값, 예외, 변수 필드는 구조화된 설명을 이룹니다. 정규 이름은 참조와 인벤토리의 별칭이 됩니다. Python 기본값과 어노테이션은 소스 표기를 유지합니다. Sphinx는 Python의 unparser로 이를 다시 출력할 수 있습니다. C++ 선언은 Sphinx 호환 식별자 버전과 심볼 인벤토리를 게시합니다. 중첩 깊이 제한은 적용되며, 중첩 괄호는 선형 시간에 파싱합니다.

numref는 번호 자리 하나를 치환하며, 번호 없는 대상을 보고합니다. 절 번호는 읽기 순서를 따릅니다. 문서마다 한 번만 번호를 붙이고, 두 번째 번호 목차 트리는 충돌을 보고합니다. 서식 치환과 식별자의 세부 사항은 참조 테스트를 확인하세요.

일반 색인, 모듈 색인, 검색이 내장되어 있습니다. 검색은 단어 접두부를 일치시키며 Sphinx의 영어 어간 추출은 사용하지 않습니다.

선언형 객체 타입으로 자주 쓰이는 Python 확장 등록을 대체할 수 있습니다. object_types, crossref_types, directive_aliases가 데이터를 설명합니다. 사용자 정의 Python parse_node는 이름, 표시, 프로그램의 선언형 규칙으로 바꿉니다. 표현할 수 없는 코드는 마이그레이션에서 알립니다. 객체 타입 선언를 참고하세요.

내장 확장의 동작¶

표 22 확장의 범위¶
동작	상태
`todo`, `ifconfig`, `extlinks`, `autosectionlabel`	내장되어 있습니다. 하드코딩한 extlinks 링크에는 역할 사용을 제안할 수 있습니다.
`graphviz`	링크된 Graphviz가 정적 그림을 생성합니다. 자원 접근 경계가 적용됩니다.
`intersphinx`	로컬 인벤토리와 가져온 인벤토리를 지원합니다. Windows는 현재 로컬 파일만 지원합니다.
`githubpages`	정적 사이트 게시 파일을 기본 제공으로 생성합니다.
`mathjax`와 `imgmath`	HTML 수식은 MathJax를 사용합니다. PDF는 지원하는 LaTeX 부분집합을 Typst로 변환합니다.
`myst_parser`	구현된 프로젝트용 Markdown 계층입니다.
`doctest` 지시문	내용을 표시합니다. 프로젝트 빌더는 해당 테스트를 실행하지 않습니다.
`autodoc`	패키지를 임포트하거나 실행하지 않고 Python 소스를 읽습니다.

소스 기반 autodoc은 런타임에 생성되는 모든 객체를 찾을 수 없습니다. 컴파일된 모듈, 외부 데코레이터, 계산된 값, 확장 이벤트 훅에는 명시적인 한계가 있습니다. Python 3.13과 고정 버전의 Sphinx 문서 생성기 테스트를 기준으로 삼습니다. 전체 설정과 예외는 autodoc으로 Python 문서 작성하기을 참고하세요.

autosummary, napoleon, viewcode, 임의의 Python 확장은 이 경로에서 지원하지 않습니다. 설정에 지원하지 않는 확장이 있으면 알립니다. 알 수 없는 지시문이나 역할은 소스 위치와 함께 보고합니다. 생략된 내용은 게시 전에 반드시 검토해야 합니다. 다른 테마 이름도 허용하지만 Guidedog의 테마 구현을 사용합니다.

신뢰와 자원 제한¶

일반 빌드는 프로젝트의 raw HTML·Typst, 템플릿, 네트워크 인벤토리를 허용합니다. 로컬 읽기는 소스 디렉터리와 명시적으로 공유한 루트로 제한합니다. 심볼릭 링크로 이 경계를 넓힐 수 없습니다. 템플릿, 정적 파일, include, 이미지, 글꼴, API 소스에도 같은 규칙이 적용됩니다.

Graphviz 이미지 자원은 문서를 기준으로 해석하며 경로 경계를 적용합니다. 지원되는 이미지 데이터는 그림에 포함합니다. imagepath와 fontpath는 경계를 넓히지 않습니다. Typst는 읽기 가능한 디렉터리를 담은 전용 루트에서 실행되어 책 템플릿과 프리앰블을 선언된 자원으로 제한합니다.

--untrusted는 읽기 범위를 소스 폴더로 좁힙니다. raw 콘텐츠, 안전하지 않은 URL, 외부 자원, 프로젝트 Typst 템플릿과 프리앰블을 진단과 함께 제외합니다. 인벤토리나 Typst 패키지를 가져오지 않습니다. 자원 읽기를 요청하는 그래프는 경고와 함께 코드로 표시합니다. 이 모드는 네이티브 컴파일러의 메모리나 실행 시간을 제한하지 않습니다.

호스트 예산의 기본값은 1 GiB입니다. 할당 전에 용량을 예약합니다. 페이지 작업 공간은 사용 후 해제하지만, 유지하는 프로젝트 그래프와 카탈로그는 프로젝트가 커질수록 메모리를 사용합니다. 읽기 워커가 작업 수락을 조율합니다. 요청을 거부하면 실패한 작업과 수정 옵션을 알립니다.

--memory=ram은 관리 예산 한도에서 멈춥니다. --memory=disk는 관리되는 작업 저장 공간에 메모리 매핑 임시 파일을 허용합니다. 유지되는 호스트 저장 공간은 RAM 예산에 계속 포함됩니다. --disk-budget는 매핑 저장 공간을 제한하며 디스크 여유도 남깁니다. 비대화형 명령은 응답을 기다리지 않습니다. 알려진 머신 여유 용량은 GUIDEDOG_AVAILABLE_MIB로 지정할 수 있습니다.

--max-depth, --max-nodes, --stack-kib는 문서 처리를 제한합니다. 한도를 바꾸면 읽기와 출력 캐시가 무효화됩니다. 깊이와 스택 용량은 맞아야 합니다. 네이티브 Graphviz, tree-sitter, Typst의 할당은 호스트 예산 밖에 있습니다. 엄격한 한도가 필요하면 운영체제 제한을 사용하세요. 오류 메시지와 메모리와 소유권를 참고하세요.

검증과 실제 프로젝트¶

tools/sphinxdiff는 고정된 Sphinx 테스트 루트 42개에서 페이지, 식별자, 본문 링크, 인벤토리, 번호, 진단을 비교합니다. 저장된 결과와 README는 의도적인 차이를 설명합니다. 정확한 소스 위치, 안정적인 읽기 순서의 번호, 대상 형식 전용 raw 콘텐츠를 생략할 때의 명시적 보고가 그 예입니다.

2026년 10월 1일 원격 검증에서 CPython, Django, Flask의 새 빌드와 변경 없는 HTML·PDF 빌드를 실행했습니다. 12번의 빌드가 모두 성공했고 진단과 링크 결과가 기준과 일치했습니다. Linux 테스트 1,039개와 대상 AddressSanitizer 테스트 94개도 통과했습니다.

이 프로젝트에는 지원하지 않는 Python 확장 구문이 포함되어 있으며, 그 진단도 검증 근거의 일부입니다. 종료 상태 0은 모든 비공개 지시문이 재현되었음을 뜻하지 않습니다. 게시에 진단이 없어야 한다면 -W를 사용하세요.

과거 측정값과 소스 리비전은 docs/manual/evidence/manuals.md에 있습니다. 최신 원격 검토 보고서는 build/review-remote-20261001/report.txt입니다. 이 측정값은 기록된 작업 부하를 설명하며, 보편적인 속도나 메모리 한계가 아닙니다.