Guidedog / 문서 0.2.0

프로젝트의 동작 방식¶

프로젝트 루트는 conf.toml이 있는 폴더다. root_doc은 읽기 순서의 시작 문서다. Guidedog은 소스 문서를 찾고 읽어 관계를 해결한 뒤 완전한 출력 세대를 게시한다.

문서와 자원¶

확장자로 리더를 선택한다. RST와 프로젝트 Markdown은 그래프를 공유한다. 이미지와 다운로드는 리소스이며 문서가 쓰는 것을 복사한다. 테마 자산은 html_static_path에 둔다. 포함 파일은 소스 또는 include_roots 안에 있어야 한다.

설명서와 설계 기록은 독자와 읽기 순서가 달라 별도 프로젝트로 둔다. 각각 설정, 템플릿, 캐시, 출력을 갖는다. Guidedog의 docs/manual과 docs/gds가 이 구조다.

Guidedog은 출력별 입력과 조회를 기록한다. 소스가 바뀌면 다시 읽고 의존성이 바뀌면 사용자를 무효화한다. 템플릿 변경은 모든 페이지에 영향을 줄 수 있다. 그대로인 문서는 저장된 객체에서 읽는다.

캐시는 이전 빌드의 증거이며 원본 진실이 아니다. -E는 다음 빌드의 저장 환경을 버리고 -a는 모든 출력을 쓴다. 서로 다른 문제를 해결한다.

\[\text{재사용} = \text{같은 입력} \land \text{같은 조회 결과} \land \text{출력 존재}\]

템플릿의 타임스탬프도 입력이다. 현재 분을 표시하는 페이지는 글이 그대로여도 바뀔 수 있다. 고정 시간이 필요하면 SOURCE_DATE_EPOCH를 쓴다.

빌드는 형제 임시 폴더에 변경을 쓰고 완성한 뒤 파일과 기록을 동기화하고 세대를 바꾼다. 독자는 완전한 이전 또는 새 게시물을 본다. 중단 커밋은 다음 빌드가 처리한다. 설계와 증명 의무는 완전한 출력 세대 게시에 있다.